API documentation for developers

Dear developers, by carefully reading these documents, you will be able to use our quality services easily and purchase a Telegram virtual number automatically.

Basic Info

The request URL needs to be determined by BASE and specific endpoint combination.

Base URL : https://api.heytelegram.com
Authorization Type : API Key
- Key : apikey
- Value : Sign in to your account
- Add To : Header
Request Rate Limit : 100/30s

Warning: The existing documentation is not covered by long-term support and there is a possibility that it will change in the future. If you are a developer, develop your programs with these conditions in mind. Do not share your API-KEY with others; in case of sharing, create a new API-KEY.

Country List

Use this endpoint to get a list of countries, prices, available numbers and other information.

HTTP GET : /api/v1/country-list

Query	Type	Mandatory	Discription
operator	string	yes	use operator-1
service	string	yes	use telegram

Success

1  [
2     {
3        "country": "egypt",
4        "ref": " -jncl7d24706ama",
5        "price": 0.6,
6        "code": 20,
7        "exist": "yes"
8     }
9  ]

Error

1  {
2     "message": [
3        "api-key is invalid",
4        "api-key not found",
5        "unknown error"
6     ],
7     "error": "Bad Request",
8     "statusCode": 400
9  }

Account Info

Use this endpoint to get account balance, open orders and other information.

HTTP POST : /api/v1/account-info

Success

1  {
2     "balance": 48.64,
3     "orders": [
4        {
5           "number": "+48459074306",
6           "requestId": "842171623",
7           "code": "48",
8           "country": "poland",
9           "otp": "canceled",
10          "price": 0.52,
11          "status": "canceled"
12       }
13    ],
14    "payments": [
15       {
16          "created_at": "2023-12-28T09:01:10.630Z",
17          "expiration_estimate_date": "2023-12-28T09:21:10.630Z",
18          "network": "trx",
19          "pay_address": "TGsskkb317YGPWnGWR7qDMXyCfx1JZjSpD",
20          "pay_amount": 94.464225,
21          "pay_currency": "trx",
22          "payment_id": "5023146363",
23          "payment_status": "waiting"
24       }
25    ]
26 }

ERROR

1  {
2     "message": [
3        "api-key is invalid",
4        "api-key not found",
5        "unknown error"
6     ],
7     "error": "Bad Request",
8     "statusCode": 400
9  }

Buy Number

To get a new number, you can proceed from this endpoint according to the below instructions. If your number of requests is abnormal, your IP will be blocked.

HTTP POST : /api/v1/buy-number

Param	Type	Mandatory	Discription
operator	string	yes	use operator-1
service	string	yes	use telegram
ref	string	yes	use "ref-string"

Success

1  {
2     "country": "nigeria",
3     "number": "+2348146539431",
4     "requestId": 101428050
5  }

Error

1  {
2     "message": [
3        "maximum limit of open orders",
4        "unknown error",
5        "ref string is invalid",
6        "oprator should not be empty",
7        "country should not be empty",
8        "service should not be empty",
9        "ref should not be empty",
10       "api-key is invalid",
11       "api-key not found",
12       "balance is low"
13    ],
14    "error": "Bad Request",
15    "statusCode": 400
16 }

OTP Code

To receive an OTP code, use this endpoint after entering the number in Telegram. Warning: If for any reason you receive the OTP, the amount will be deducted from your wallet, so be careful when submitting this request.

HTTP POST : /api/v1/otp-code

Param	Type	Mandatory	Discription
operator	string	yes	use operator-1
requestId	string	yes	use "request id number"

Success

1  {
2     "number": "+2348146539431",
3     "otp": "87654"
4  }

Error

1  {
2     "message": [
3        "oprator should not be empty",
4        "request id should not be empty",
5        "api-key is invalid",
6        "api-key not found",
7        "unknown error",
8        "request id is invalid"
9     ],
10    "error": "Bad Request",
11    "statusCode": 400
12 }

Close Order

If you have an open order, you can close it from this endpoint. Changing the status of the order is done automatically, if the OTP code is sent, the status changes to finished, but if the OTP code is not received, the status changes to canceled and the deducted fee is returned to your wallet.

HTTP POST : /api/v1/close-order

Param	Type	Mandatory	Discription
operator	string	yes	use operator-1
requestId	string	yes	use "request id number"

Success

1  {
2     "result": "success"
3  }

Error

1  {
2     "message": [
3        "oprator should not be empty",
4        "request id should not be empty",
5        "api-key is invalid",
6        "api-key not found",
7        "request id is invalid",
8        "unknown error"
9     ],
10    "error": "Bad Request",
11    "statusCode": 400
12 }