API

Get Started

As a member of the TGmembership family, you can use the API to automate your memberships' management. For example, you can connect your Telegram bot directly to your website and give your customers access to your Telegram chats automatically.

Before you can use the TGmembership API, you must have a bot and an API key created. If you don't have one yet, create your Telegram bot and connect it to TGmembership.

Generate API Endpoint

To learn how to generate an API key, please refer to our guide on creating an API key.

Authentication

The TGmembership API uses API keys to authenticate requests. You can view and manage your API key from your bot's settings menu.

All queries to the TGmembership API must be served over HTTPS, using GET, POST or DELETE HTTP methods, and need to be presented in this form: https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/{{METHOD_NAME}}

Calls made over plain HTTP will fail. API requests without authentication will also fail. All methods in the TGmembership API are case-insensitive.

The response contains a JSON object, which always has a Boolean field "ok", Integer field "code" and may have an optional String field "description" with a human-readable description of the result. If "ok" equals true, the request was successful and the result of the query can be found in the "result" field. In case of an unsuccessful request, "ok" equals false and the error is explained in the "description".

/addMember

POST https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/addMember

This API method creates a unique access token that allows users to activate memberships without payment. For more information on access tokens, please check out our help article.

Request Body

Name	Type	Description
plan_id*	Integer	The "plan_id" parameter is a required input when creating an access token via the API. It should be set to the positive integer value that corresponds to the plan you want the access token to be linked to.
member_id	Integer	This parameter allows for easy activation or extension of memberships for existing members without requiring additional user input or interaction. It represents the Telegram ID of a member who has previously interacted with the bot and has not blocked it.

200: OK Success - the access token was generated. Use the provided link to activate the membership.

{
    "ok": true,
    "code": 200,
    "result": {
        "bot_username": "tgmembership_demobot",
        "access_token": "abcd123",
        "link": "https://t.me/tgmembership_demobot?start=accesstoken_abcd123"
    }
}

204: No Content Success - The membership for the given member was successfully activated. You will receive a 204 response code, indicating that the request was successful but there is no content to return.

{
  "ok": true,
  "code": 204
}

401: Unauthorized Method Not Allowed

If you receive this error message, it means that your bot may have violated TGmembership's acceptable use policy. Please refer to this article for more information and steps to resolve the issue.

{
    "ok": false,
    "code": 401,
    "description": "Method Not Allowed: \"addMember\"."
}

404: Not Found The requested resource could not be found.

{
    "ok": false,
    "code": 404,
    "description": "The requested resource could not be found. The provided ID does not match any existing data in our database."
}

/affiliate

POST https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}affiliate

This API method allows you to register new affiliates remotely.

Request Body

Name	Type	Description
member_id*	Integer	The ID of the affiliate you want to register. This must be a user that has previously interacted with the bot.

200: OK

{
    "ok": true,
    "code": 200,
    "result": {
        "affiliate_id": "abcd123",
        "affiliate_link": "https://t.me/tgmembership_demobot?start=r_abcd123"
    }
}

/countOrders

GET https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}countOrders

This method returns a list of daily/monthly/yearly revenue and sales.

Query Parameters

Name	Type	Description
interval_unit	Enum	This parameter specifies the time unit to use when retrieving revenue and sales data. The accepted values are 'day', 'week', and 'month'.
interval_count	Integer	This parameter specifies how many intervals to look back when retrieving revenue and sales data. The value must be a positive integer.

200: OK Success

{
  "ok": true,
  "code": 200,
  "result": {
    "2023-04-29": {
      "revenue": 91.05728036,
      "formatted": "91,06 €",
      "currency": "EUR",
      "sales": 1
    },
    "2023-04-28": {
      "revenue": 9.17954515,
      "formatted": "9,18 €",
      "currency": "EUR",
      "sales": 1
    },
    "2023-04-27": {
      "revenue": 0,
      "formatted": "0,00 €",
      "currency": "EUR",
      "sales": 0
    },
    "2023-04-26": {
      "revenue": 4.55331935,
      "formatted": "4,55 €",
      "currency": "EUR",
      "sales": 1
    },
    "2023-04-25": {
      "revenue": 0,
      "formatted": "0,00 €",
      "currency": "EUR",
      "sales": 0
    },
    "2023-04-24": {
      "revenue": 1.23,
      "formatted": "1,23 €",
      "currency": "EUR",
      "sales": 1
    },
    "2023-04-23": {
      "revenue": 92.28728036,
      "formatted": "92,29 €",
      "currency": "EUR",
      "sales": 2
    }
  }
}

/countUsers

GET https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}countUsers

This API method returns the number of known users, leads, churned customers, and paying members.

200: OK Success

{
  "ok": true,
  "code": 200,
  "result": {
    "users": 100,
    "leads": 10,
    "churned": 10,
    "members": {
      "total": 80
    }
  }
}

/getPlans

GET https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/getPlans

This method returns a list of all available plans, including their names, prices, and durations. It provides more detailed information about each plan and can be used for various purposes.

Query Parameters

Name	Type	Description
plan_id	Integer	An optional positive integer parameter that specifies the ID of the plan to be returned. If this parameter is not provided, all available plans will be returned.
limit	Integer	An optional positive integer parameter that limits the number of results returned by the API. The valid range of this parameter is from 1 to 100. If this parameter is not provided, the API will return all available plans or the plan matching the 'plan_id' parameter if specified.

200: OK Success, without "plan_id" parameter.

{
    "ok": true,
    "code": 200,
    "result": {
        "0": {
            "plan_id": 19,
            "plan_name": "USD Demo Plan",
            "plan_description": null,
            "duration": 0,
            "price": "9.99",
            "currency": "USD",
            "exclude_chats": {},
            "options": {
                "recurring": 0,
                "newcomers": 0,
                "singleuse": 0,
                "token_only": 0,
                "credit_only": 0,
                "invitee_only": 0,
                "is_hidden": 0
            },
            "max_customers": 0,
            "days_to_purchase": {
                "monday": 1,
                "tuesday": 1,
                "wednesday": 1,
                "thursday": 1,
                "friday": 1,
                "saturday": 1,
                "sunday": 1
            },
            "sort_order": 100,
            "enabled": 1
        },
        "1": {
            "plan_id": 20,
            "plan_name": "EUR Demo Plan",
            "plan_description": null,
            "duration": 0,
            "price": "1.23",
            "currency": "EUR",
            "exclude_chats": {},
            "options": {
                "recurring": 0,
                "newcomers": 0,
                "singleuse": 0,
                "token_only": 0,
                "credit_only": 0,
                "invitee_only": 0,
                "is_hidden": 0
            },
            "max_customers": 0,
            "days_to_purchase": {
                "monday": 1,
                "tuesday": 1,
                "wednesday": 1,
                "thursday": 1,
                "friday": 1,
                "saturday": 1,
                "sunday": 1
            },
            "sort_order": 99,
            "enabled": 1
        },
        "2": {
            "plan_id": 21,
            "plan_name": "GBP Demo Plan",
            "plan_description": null,
            "duration": 0,
            "price": "5",
            "currency": "GBP",
            "exclude_chats": {},
            "options": {
                "recurring": 0,
                "newcomers": 0,
                "singleuse": 0,
                "token_only": 0,
                "credit_only": 0,
                "invitee_only": 0,
                "is_hidden": 0
            },
            "max_customers": 0,
            "days_to_purchase": {
                "monday": 1,
                "tuesday": 1,
                "wednesday": 1,
                "thursday": 1,
                "friday": 1,
                "saturday": 1,
                "sunday": 1
            },
            "sort_order": 98,
            "enabled": 1
        },
        "3": {
            "plan_id": 23,
            "plan_name": "RUB Demo Plan",
            "plan_description": null,
            "duration": "01.01.2030",
            "price": "150",
            "currency": "RUB",
            "exclude_chats": {},
            "options": {
                "recurring": 0,
                "newcomers": 0,
                "singleuse": 1,
                "token_only": 0,
                "credit_only": 0,
                "invitee_only": 0,
                "is_hidden": 0
            },
            "max_customers": 0,
            "days_to_purchase": {
                "monday": 1,
                "tuesday": 1,
                "wednesday": 1,
                "thursday": 1,
                "friday": 1,
                "saturday": 1,
                "sunday": 1
            },
            "sort_order": 0,
            "enabled": 1
        },
        "4": {
            "plan_id": 25,
            "plan_name": "BRL Demo Plan",
            "plan_description": null,
            "duration": "7 years",
            "price": "50.37",
            "currency": "BRL",
            "exclude_chats": {},
            "options": {
                "recurring": 0,
                "newcomers": 0,
                "singleuse": 0,
                "token_only": 0,
                "credit_only": 0,
                "invitee_only": 0,
                "is_hidden": 0
            },
            "max_customers": 0,
            "days_to_purchase": {
                "monday": 1,
                "tuesday": 1,
                "wednesday": 1,
                "thursday": 1,
                "friday": 1,
                "saturday": 1,
                "sunday": 1
            },
            "sort_order": 0,
            "enabled": 1
        }
    }
}

200: OK Success, with "plan_id" parameter.

{
    "ok": true,
    "code": 200,
    "result": {
        "plan_id": 20,
        "plan_name": "EUR Demo Plan",
        "plan_description": null,
        "duration": 0,
        "price": 123,
        "currency": "EUR",
        "exclude_chats": null,
        "options": "00000",
        "max_customers": 0,
        "days_to_purchase": null,
        "sort_order": 99,
        "enabled": 1
    }
}

/getRevenue

GET https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/getRevenue

This API method returns the total revenue generated and the number of sales for a specific period of time.

Query Parameters

Name	Type	Description
from	Integer	UNIX timestamp indicating the start of the time period for which revenue and sales data should be retrieved. Only data generated after this time will be included in the results. If not specified, the API will default to the earliest timestamp available.
to	Integer	UNIX timestamp indicating the end of the time period for which revenue and sales data should be retrieved. Only data generated before this time will be included in the results. If not specified, the API will default to the latest timestamp available.

200: OK Success

{
  "ok": true,
  "code": 200,
  "result": {
    "from": 1681159917,
    "to": 1683751930,
    "revenue": 428.77880368,
    "formatted": "428,78 €",
    "currency": "EUR",
    "sales": 47
  }
}

/getSubscribers

GET https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/getSubscribers

Fetch all subscribers

Query Parameters

Name	Type	Description
user_id	Integer	ID of the user you are searching for.

200: OK Success, without "user_id" parameter.

{
    "ok": true,
    "code": 200,
    "result": {
        "11111111": {
            "user_id": 11111111,
            "plan_id": 20,
            "membership_start_time": 1615201830,
            "membership_end_time": 0,
            "user_email": "[e-mail]",
            "referred_by": null
        },
        "22222222": {
            "user_id": 22222222,
            "plan_id": 20,
            "membership_start_time": 1665556819,
            "membership_end_time": 0,
            "user_email": null,
            "referred_by": null
        },
        "33333333": {
            "user_id": 33333333,
            "plan_id": 11,
            "membership_start_time": 1618833147,
            "membership_end_time": 0,
            "user_email": null,
            "referred_by": null
        },
        "44444444": {
            "user_id": 44444444,
            "plan_id": 29,
            "membership_start_time": 1618616835,
            "membership_end_time": 1618703999,
            "user_email": null,
            "referred_by": 33333333
        },
        "55555555": {
            "user_id": 55555555,
            "plan_id": 11,
            "membership_start_time": 1618258273,
            "membership_end_time": 0,
            "user_email": "[e-mail]",
            "referred_by": 33333333
        }
    }
}

200: OK Success, with "user_id" parameter.

{
    "ok": true,
    "code": 200,
    "result": {
        "user_id": 55555555,
        "plan_id": 11,
        "membership_start_time": 1618258273,
        "membership_end_time": 0,
        "user_email": "[e-mail]",
        "referred_by": 33333333
    }
}

/mostPopularPaymentMethods

GET https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/mostPopularPaymentMethods

This API method returns a list of the most popular payment methods used for sales, along with the number of sales made using each payment method.

200: OK Success

{
  "ok": true,
  "code": 200,
  "result": {
    "0": {
      "sales": 85,
      "method": "Crypto (Crypto.Com)"
    },
    "1": {
      "sales": 76,
      "method": "Credit / Debit card (Stripe)"
    },
    "2": {
      "sales": 18,
      "method": "PayPal"
    }
  }
}

/order

POST https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/order

Create a new invoice

Request Body

Name	Type	Description
plan_id*	Integer	The "plan_id" parameter is a required input when creating an invoice via the API. It should be set to the positive integer value that corresponds to the plan you want the invoice to be linked to.
payment_gateway*	String	Choose the payment method for this invoice, such as "PayPal," "Stripe," "CryptoNoKYC," or any other installed method. Remember, the selected method must be installed in the bot to work. If you're uncertain about the available options, you can retrieve a list of installed payment methods using the GET /paymentMethods API request.
member_id	Integer	This parameter represents the Telegram ID of a member that will be granted membership privileges upon successful completion of the order.
email	String	This parameter is optional. It's only needed for specific payment methods, such as Paystack, for instance.
token	String	This parameter is optional. It's only needed for specific payment methods, such as crypto. When using BinancePay, pass the name of the token, e.g. "USDT." For CryptoNoKYC, include both the token name and the network, formatted as "TOKEN.NETWORK," for example, "USDT.MATIC."

200: OK

{
  "ok": true,
  "code": 200,
  "result": {
    "order_key": "ABCD123",
    "amount": "123.456",
    "currency": "USDT",
    "address": "0xabcdefghijklmnopqrstuvwxyz0123456789",
    "network": "MATIC",
    "qr_link": "https:\\/\\/example.com\\/qr.png",
    "expire": 1693942452
  }
}

/paymentMethods

GET https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/paymentMethods

Check your bot's payment methods

200: OK

{
  "ok": true,
  "code": 200,
  "result": {
    "0": {
      "name": "authorizenet",
      "user_friendly_name": "AuthorizeNet"
    },
    "1": {
      "name": "binancepay",
      "user_friendly_name": "Crypto (Binance Pay)"
    },
    "2": {
      "name": "cryptocom",
      "user_friendly_name": "Crypto (Crypto.Com)"
    },
    "3": {
      "name": "cryptonokyc",
      "user_friendly_name": "Crypto (No KYC)"
    },
    "4": {
      "name": "flutterwave",
      "user_friendly_name": "Flutterwave"
    },
    "5": {
      "name": "paystack",
      "user_friendly_name": "Paystack"
    },
    "6": {
      "name": "razorpay",
      "user_friendly_name": "RazorPay"
    },
    "7": {
      "name": "reepay",
      "user_friendly_name": "Billwerk+"
    },
    "8": {
      "name": "stripe",
      "user_friendly_name": "Credit \\/ Debit card (Stripe)"
    }
  }
}

/plansPerformance

GET https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/plansPerformance

This API method returns the revenue and number of sales for each subscription plan offered by your service on a monthly basis for the last 6 months.

200: OK Success

{
  "ok": true,
  "code": 200,
  "result": {
    "19": {
      "2023-05": {
        "plan_name": "USD Demo Plan",
        "currency": "EUR",
        "sales": 2,
        "revenue": "182.48015416",
        "formatted": "182,48 €"
      },
      "2023-04": {
        "plan_name": "USD Demo Plan",
        "currency": "EUR",
        "sales": 4,
        "revenue": "364.96030832",
        "formatted": "364,96 €"
      },
      "2023-03": {
        "plan_name": "USD Demo Plan",
        "currency": "EUR",
        "sales": 3,
        "revenue": "273.72023124",
        "formatted": "273,72 €"
      },
      "2023-02": {
        "plan_name": "USD Demo Plan",
        "currency": "EUR",
        "sales": 5,
        "revenue": "45.5789764",
        "formatted": "45,58 €"
      },
      "2023-01": {
        "plan_name": "USD Demo Plan",
        "currency": "EUR",
        "sales": 9,
        "revenue": "82.04215752",
        "formatted": "82,04 €"
      },
      "2022-12": {
        "plan_name": "USD Demo Plan",
        "currency": "EUR",
        "sales": 9,
        "revenue": "82.04215752",
        "formatted": "82,04 €"
      }
    },
    "20": {
      "2023-05": {
        "plan_name": "EUR Demo Plan",
        "currency": "EUR",
        "sales": 9,
        "revenue": "11.07",
        "formatted": "11,07 €"
      },
      "2023-04": {
        "plan_name": "EUR Demo Plan",
        "currency": "EUR",
        "sales": 18,
        "revenue": "22.14",
        "formatted": "22,14 €"
      },
      "2023-03": {
        "plan_name": "EUR Demo Plan",
        "currency": "EUR",
        "sales": 3,
        "revenue": "3.69",
        "formatted": "3,69 €"
      },
      "2023-02": {
        "plan_name": "EUR Demo Plan",
        "currency": "EUR",
        "sales": 10,
        "revenue": "12.3",
        "formatted": "12,30 €"
      },
      "2023-01": {
        "plan_name": "EUR Demo Plan",
        "currency": "EUR",
        "sales": 1,
        "revenue": "1.23",
        "formatted": "1,23 €"
      },
      "2022-12": {
        "plan_name": "EUR Demo Plan",
        "currency": "EUR",
        "sales": 1,
        "revenue": "1.23",
        "formatted": "1,23 €"
      }
    },
    "21": {
      "2023-05": {
        "plan_name": "GBP Demo Plan",
        "currency": "EUR",
        "sales": 0,
        "revenue": 0,
        "formatted": ""
      },
      "2023-04": {
        "plan_name": "GBP Demo Plan",
        "currency": "EUR",
        "sales": 0,
        "revenue": 0,
        "formatted": ""
      },
      "2023-03": {
        "plan_name": "GBP Demo Plan",
        "currency": "EUR",
        "sales": 1,
        "revenue": "5.7477871",
        "formatted": "5,75 €"
      },
      "2023-02": {
        "plan_name": "GBP Demo Plan",
        "currency": "EUR",
        "sales": 1,
        "revenue": "5.7477871",
        "formatted": "5,75 €"
      },
      "2023-01": {
        "plan_name": "GBP Demo Plan",
        "currency": "EUR",
        "sales": 0,
        "revenue": 0,
        "formatted": ""
      },
      "2022-12": {
        "plan_name": "GBP Demo Plan",
        "currency": "EUR",
        "sales": 3,
        "revenue": "17.2433613",
        "formatted": "17,24 €"
      }
    },
    "25": {
      "2023-05": {
        "plan_name": "BRL Demo Plan",
        "currency": "EUR",
        "sales": 0,
        "revenue": 0,
        "formatted": ""
      },
      "2023-04": {
        "plan_name": "BRL Demo Plan",
        "currency": "EUR",
        "sales": 1,
        "revenue": "9.18105122",
        "formatted": "9,18 €"
      },
      "2023-03": {
        "plan_name": "BRL Demo Plan",
        "currency": "EUR",
        "sales": 1,
        "revenue": "9.18105122",
        "formatted": "9,18 €"
      },
      "2023-02": {
        "plan_name": "BRL Demo Plan",
        "currency": "EUR",
        "sales": 2,
        "revenue": "18.36210244",
        "formatted": "18,36 €"
      },
      "2023-01": {
        "plan_name": "BRL Demo Plan",
        "currency": "EUR",
        "sales": 1,
        "revenue": "9.18105122",
        "formatted": "9,18 €"
      },
      "2022-12": {
        "plan_name": "BRL Demo Plan",
        "currency": "EUR",
        "sales": 0,
        "revenue": 0,
        "formatted": ""
      }
    },
    "34": {
      "2023-05": {
        "plan_name": "Recurring Plan Demo",
        "currency": "EUR",
        "sales": 1,
        "revenue": "1.82498404",
        "formatted": "1,82 €"
      },
      "2023-04": {
        "plan_name": "Recurring Plan Demo",
        "currency": "EUR",
        "sales": 1,
        "revenue": "4.5624601",
        "formatted": "4,56 €"
      },
      "2023-03": {
        "plan_name": "Recurring Plan Demo",
        "currency": "EUR",
        "sales": 2,
        "revenue": "6.38744414",
        "formatted": "6,39 €"
      },
      "2023-02": {
        "plan_name": "Recurring Plan Demo",
        "currency": "EUR",
        "sales": 1,
        "revenue": "4.5624601",
        "formatted": "4,56 €"
      },
      "2023-01": {
        "plan_name": "Recurring Plan Demo",
        "currency": "EUR",
        "sales": 0,
        "revenue": 0,
        "formatted": ""
      },
      "2022-12": {
        "plan_name": "Recurring Plan Demo",
        "currency": "EUR",
        "sales": 0,
        "revenue": 0,
        "formatted": ""
      }
    }
  }
}

/webhook

POST https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/webhook

This API method allows you to register a webhook endpoint to receive notifications for events related to your account. Once you have registered a webhook endpoint, we will send HTTP POST requests to that endpoint whenever an event of interest occurs.

Request Body

Name	Type	Description
url*	String	The URL for your webhook endpoint.

200: OK Success

{
  "ok": true,
  "code": 200,
  "result": {
    "0": {
      "url": "https:\\/\\/example.com\\/webhookEndpoint",
      "secret": "abcdefghijklmnopqrstuvwxyz"
    }
  }
}

400: Bad Request Invalid URL provided

{
    "ok": false,
    "code": 400,
    "description": "Bad Request: Invalid URL provided. Please ensure the URL is valid and it responds with a successful HTTP status code (200)"
}

403: Forbidden Webhook limit exceeded.

{
    "ok": false,
    "code": 403,
    "description": "You are not allowed to add more than one webhook for this bot."
}

/webhook

DELETE https://api.tgmembership.com/bot{{BOT_ID}}/{{API_KEY}}/webhook

This method allows you to remove an existing webhook associated with your Telegram bot. Provide the endpoint URL for the webhook you wish to delete, and the webhook will be removed from your bot.

Request Body

Name	Type	Description
url*	String	The URL for your webhook endpoint.

204: No Content Success

{
    "ok": true,
    "code": 204
}

404: Not Found The requested resource could not be found.

{
    "ok": false,
    "code": 404,
    "description": "The requested resource could not be found. The provided URL does not match any existing data in our database."
}