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

NameTypeDescription

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.

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

/affiliate

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

This API method allows you to register new affiliates remotely.

Request Body

NameTypeDescription

member_id*

Integer

The ID of the affiliate you want to register. This must be a user that has previously interacted with the bot.

{
    "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

NameTypeDescription

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.

{
  "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.

{
  "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

NameTypeDescription

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.

{
    "ok": true,
    "code": 200,
    "result": {
        "0": {
            "plan_id": 19,
            "project_id": 1,
            "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,
            "project_id": 1,
            "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,
            "project_id": 1,
            "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,
            "project_id": 1,
            "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,
            "project_id": 1,
            "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
        }
    }
}

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

This endpoint retrieves the list of projects associated with the bot.

/getProjects

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

This endpoint retrieves the list of projects associated with the bot.

Response

{
  "ok": true,
  "code": 200,
  "result": {
    "0": {
      "id": 1,
      "name": "Project 1",
      "options": {
        "sort": 100,
        "hidden": false
      }
    },
    "1": {
      "id": 3,
      "name": "Project 2",
      "options": {
        "hidden": true
      }
    },
    "2": {
      "id": 4,
      "name": "test project",
      "options": {
        "hidden": true
      }
    }
  }
}

/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

NameTypeDescription

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.

{
  "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

NameTypeDescription

user_id

Integer

ID of the user you are searching for.

{
    "ok": true,
    "code": 200,
    "result": {
        "11111111": {
            "user_id": 11111111,
            "plan_id": 20,
            "membership_start_time": 1615201830,
            "membership_end_time": 0,
            "user_email": "email@example.com",
            "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": "demo@tgmembership.com",
            "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.

{
  "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

NameTypeDescription

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."

return_url

String

The URL to which the user will be redirected after the payment process is completed successfully. If this parameter is not provided, the default TGmembership return URL will be used. This parameter is only applicable for payment methods that support custom return URLs.

cancel_url

String

The URL to which the user will be redirected if they cancel the payment process. If this parameter is not provided, the default TGmembership cancellation URL will be used. This parameter is only applicable for payment methods that support custom cancellation URLs.

{
  "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

{
  "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.

{
  "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

NameTypeDescription

url*

String

The URL for your webhook endpoint.

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

/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

NameTypeDescription

url*

String

The URL for your webhook endpoint.

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

Last updated