Telegram Gateway Authorization Codes#
This section describes the specifics of transmitting authorization codes through the platform to Telegram Gateway.
To transmit a code, send a request including the corresponding code. The code (without any additional text) will be passed to the operator, who will insert it into the message template.
More details
The Telegram Gateway service is designed to deliver authorization and verification digital codes to Telegram Messenger users.
Codes are sent from the Verification Codes official channel.
Hiding one's phone number in Telegram settings does not affect message delivery. The delivery of codes is also unaffected by whether the user has a Telegram Premium subscription or not.
Currently, the service supports:
- sending authorization code messages via Telegram;
- receiving message delivery statuses;
- cascading message sending to alternative channels in case of non-delivery to Telegram (if necessary).
Sending Request#
1 {
2 "login": "YOUR_LOGIN",
3 "password": "YOUR_PASSWORD",
4 "useTimeDiff": true,
5 "id": "superId",
6 "shortenLinks": false,
7 "scheduleInfo": {
8 "timeBegin": "10:00",
9 "timeEnd": "12:00",
10 "weekdaysSchedule": "123"
11 },
12 "destAddr": "SUBSCRIBER'S_PHONE_NUMBER",
13 "message": {
14 "type": "TGCODE",
15 "data": {
16 "text": "12345",
17 "serviceNumber": "SENDER'S_NAME",
18 "ttl": 120,
19 "ttlUnit": "SECONDS"
20 }
21 }
22 }
Parameter |
Required |
Data type |
Description |
|---|---|---|---|
login |
yes |
string |
Partner’s name. |
password |
yes |
string |
Partner’s password for sending messages. |
destAddr |
yes |
string |
Subscriber’s phone number. More detailsIt contains the country code, operator code and phone number.
For the Russian Federation, the code can be
Examples: |
id |
no |
string |
Unique identifier on the Partner’s side. More detailsThis parameter is necessary for controlling repeated submissions and duplication (the control service is activated separately). The Partner can call the Service Provider (request to send a message) multiple times with the same ID. In this case, the message will be sent to the subscriber only once (on the first request). In response to the requests, the Service Provider will return the same message identifier in the Service Provider's system to the Partner (the same as for the first request). The Service Provider optionally returns this identifier to the Partner in the message delivery report if it is available. |
message |
yes |
object |
Parameters of a message being sent. More detailsIt contains information about the message type and its content. |
{message}
type
|
yes |
enum |
Message type. More details
Specify the |
{message}
data
|
yes |
object |
Parameters of the data being sent. |
{message/data}
text
|
yes |
string |
Message text. More detailsThe message must contain a code consisting of four to eight digits. Messages without digit codes will not be delivered. Character limit: no more than 2000. If the message contains multiple codes, only the first one will be transmitted.
Any accompanying text in Cyrillic or Latin (including emojis)
is ignored and replaced with a default Telegram template based
on the user interface language: |
{message/data}
serviceNumber
|
yes |
string |
Sender’s name from which the message is being sent. |
{message/data}
ttl
|
yes |
integer |
Message lifetime. More detailsAcceptable range in seconds: from 31 to 86400. Note When |
{message/data}
ttlUnit
|
yes |
enum |
Unit of measurement of the message delivery period. More details
It is transmitted only with Possible values are:
|
extraParam |
no |
string |
Additional parameters passed in the message. More details
Parameters are passed as
Example: The comma character cannot be included in the parameter name, but it can be included in its value — in this case it must be doubled.
Example: |
registeredDelivery |
no |
integer |
Requirement of delivery reports. More detailsSpecify whether delivery reports are required to track statuses. Possible values are:
For cascading message sending specify the |
notifyUrl |
no |
string |
Hostname of the incoming API to obtain the delivery report. More detailsThis parameter is optional in the request, but when sending you need to consider the following:
If any of the specified conditions are not met, an error will be generated and the request will not be executed. |
Response#
After sending a message the Service Provider returns a response synchronously.
Successful Sending#
In case of successful sending the Service Provider returns the 200 OK HTTP-code.
1 {
2 "mtNum": "7390612217"
3 "id": "8770630"
4 }
Parameter |
Data type |
Description |
|---|---|---|
mtNum |
string |
Sending chain identifier assigned by the Service Provider platform. |
id |
string |
Partner-side unique ID. Available, if it was included when sending. |
Sending Errors#
For results with errors, a response HTTP code will differ from 200 (see Error Codes).
1 {
2 "error": {
3 "code": 4,
4 "description": "Invalid request"
5 },
6 "extendedDescription": "В сообщении отсутствует код"
7 }
In this example, the Telegram message does not contain a digital authorization code.
Parameter |
Data type |
Description |
|---|---|---|
error |
object |
Error information. |
error/code |
int |
Error code. |
error/description |
string |
A brief description of the error. |
extendedDescription |
string |
Detailed description of the error (optional parameter). |
Error Codes#
Code |
Description |
HTTP-code |
|---|---|---|
1 |
Service is unavailable |
503 |
2 |
Invalid IP-address |
403 |
3 |
Too many connections |
429 |
4 |
Invalid request |
400 |
5 |
Invalid login |
401 |
6 |
Invalid password |
401 |
7 |
serviceNumber is not defined |
400 |
8 |
destAddr is not correct |
406 |
9 |
Message type is not correct |
406 |
10 |
Prohibited sending duplicates |
409 |
11 |
Invalid TTL |
406 |
100 |
100 |
500 |
Delivery Statuses#
To receive message statuses, you need to set up the Delivery Status Service.
Delivery Error Codes#
Delivery error codes for each message type are provided in the corresponding tab of the Description of Error Codes (parameter status=5) section.