Telegram Gateway Authorization Codes#

This section describes the specifics of transmitting authorization codes via the HTTP protocol to Telegram Gateway.

Currently, digital codes can only be sent via Telegram by specifying the message type as SMS in the request. The messages will then be converted to the TG format and delivered to Telegram.

The Service Provider supports:

sending authorization code messages via Telegram Gateway;
receiving message delivery statuses.

About Telegram Gateway

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.

Connection#

The service is connected by the Technical Support Service of the Service Provider.

The Partner and the Service Provider must agree on the following to connect:

a service name for transmitting authorization codes to Telegram;
a message lifetime.

Sending Request#

In the request for transmitting the authorization code to Telegram, it is necessary to specify a service name that has been separately agreed upon with the Technical Support Service.

It is recommended to include parameters and values related to the SMS message type in the request.

The message must contain a code consisting of four to eight digits.

Method: GET.

Request Examples#

A GET request containing the plain text Latin message code 12345:

http://partner.ru/login?serviceId=login&pass=123&clientId=79161234567&message=code%2012345
HTTP/1.1
Host: 10.10.10.10:9080

A GET request with a Cyrillic message text код 12345 in URL-encoded format:

http://partner.ru/login?serviceId=login&pass=123&clientId=79161234567&message=%D0%BA%D0%BE%D0%B4+12345
HTTP/1.1
Host: 10.10.10.10:9080

Parameters#

Parameter	Required	Type	Description
clientId	yes	string	Subscriber’s phone number, up to 25 characters. More details Examples: `79036550550`, `+79036550550`, `8-903-655-05-50`, `89036550550`.
message	yes	string	Message to be sent to the subscriber. More details It contains a code consisting of four to eight digits. The text in this parameter must be UTF-8 encoded. Maximum message length is 2000 characters.
serviceId	yes	string	ID of the Partner’s service (login), which is used to send a message. More details The Service Provider establishes `serviceId` while enabling the Partner’s service and reports it to the Partner.
pass	yes	string	Password for authorization in the service. More details The Service Provider establishes the password while enabling the service and reports it to the Partner.
ptag	no	string	Message identifier in the Partner’s system. More details Valid characters: 0...9a...zA...Z- It may contain from 1 to 50 characters. It may be any identifier in the Partner's system. Note For example, it may be the unique identifier of a message or the identifier of subdivision, which initiates the request for sending. In contrast to the `partnerMsgId` parameter, which is needed to control resending and duplication, the Service Provider does not control values sent in the `ptag` parameter (only format compliance is checked). The Service Provider optionally returns this identifier to the Partner as part of a request for receiving the message delivery status (this functionality is described in the section Delivery Status Service).
source	yes	string	Service name of the sender. More details Specify a service name in the request to send an authorization code (including for the main channel in a cascading message sending). This service name must be separately agreed upon with the Technical Support Service.
output	no	string	Request response format. More details If `output = xml`, the response to request will be formed as XML, see Response in the XML Format. If the parameter is not defined or is different, the default format is used: text/plain (see Response to a request in text format).
partnerMsgId	no	string	Message unique identifier in the Partner’s system. More details Allowed length: from 1 to 50 characters. This parameter is required for resending and duplicate control. The Partner can send a request to send a message several times with the same `partnerMsgId`. In this case: the message will be sent to the subscriber only once (when the first request is received); in responses to requests the Service Provider will return to the Partner the same message identifier in the Service Provider system (the same that was sent for the first request). The Service Provider as an option returns this identifier to the Partner as part of the request for receiving the message delivery status (see section Delivery Status Service). This parameter is not available by default. To enable this functionality, please coordinate with your manager.
smsPriority	no	integer	Parameter indicates the priority of the message. More details Messages with a higher priority are sent to the operator first. Possible values: `0` is the lowest priority; `1` is a normal priority; `2` is a high priority. This parameter is not available by default. The connection of this functionality should be agreed with your supervising manager.

Response#

After receiving and processing the request, the Service Provider synchronously returns the response to the Partner.
By default, the response from the Service Provider comes in the text/plain format.
The response can be generated in XML format (optionally).

Note

The Service Provider sends messages to subscribers only if the request is successfully processed.

Response to a request in text format#

Successful Sending#

In case of successful processing of the request the Service Provider returns to the Partner:

HTTP code 200 OK;
the ID of the message in the Service Provider’s system.

OK
4095284974

Response Code	Description	Possible Partner’s action
200	Successful processing of the request. In the body of the response, the identifier assigned to the message by the Service Provider is transmitted. The identifier is a 64-bit positive integer.	Common action with the service.

Sending Errors#

When sending an incorrect request, a short text error message may be transmitted in the response body.

An example of an error response – invalid serviceId/pass combination:

Invalid password

Response Code	Description	Possible Partner’s action
400	Mandatory parameters are unavailable or they are set incorrectly. More details For example, the `message` parameter is not set (where it's needed).	Troubleshooting Please repeat the request with the correct combination of parameters and their correct values.
401	Incorrect combination of `serviceId` and `pass`.	Troubleshooting Please repeat the request with the correct `serviceId` and `pass`.
402	The balance of paid messages has been exhausted (for Partners working on prepaid).	Troubleshooting To resume sending messages, the Partner needs to make an advance payment and contact the supervising manager. The Partner shouldn't repeat the request.
403	The service with the `serviceId` parameter being sent is unavailable or inactive.	Troubleshooting Please contact your supervising manager. The Partner shouldn't repeat the request.
406	Impossible to send a message to a subscriber with `clientId`.	Troubleshooting The Partner shouldn't repeat the request.
408	Allowable rate of message sending is exceeded. More details Note The Partner's service is set to a permissible speed of 10 requests per second. The Partner sent 12 requests per second. The first 10 requests will be successfully processed: in response to these requests the Service Provider will return the `200` status and send messages to subscribers. In response to the last 2 requests the Service Provider will return the `408` status to the Partner and won`t send messages to subscribers.	Troubleshooting The Partner can repeat the request without exceeding the allowed rate.
409	Sending duplicates prohibited. More details Note The duplicate blocking feature is activated for the Partner's service. During 24 hours the Partner sent 3 requests to send the message with the same text to the same number. The first request will be processed successfully and the message will be sent to the subscriber. In response to the last 2 requests the Service Provider will return the `409` status and won't send these 2 messages to the subscriber. The duplicate blocking feature is deactivated for the Partner by default. The feature can be activated by the Partner's request. The Service Provider can also activate the duplicate blocking feature for the Partner, if necessary: for example, in case of subscribers complaints.	Troubleshooting The Partner shouldn't repeat the request. If it is necessary to send a duplicate message, the Partner can contact the Technical Support Service and provide it with the most complete information about the conditions for this situation.
414	The allowed length of the message body sent in the `message` parameter.	Troubleshooting The Partner can repeat the request after shortening the message text to the allowed length.
500	Server internal error. Technical difficulties at the Service Provider side.	Troubleshooting When receiving the `500` status or when the timeout of waiting for a response expires, the Partner needs to wait for at least 1 minute. After the pause, the Partner can repeat the request. If you receive the `500` status more than 10 times, you have to stop transmitting the request. After that, you should provide the Technical Support Service with the most complete information about the conditions for the occurrence of this error for further analysis.
503	The request is being currently processed. More details The error might appear if the Partner almost simultaneously sends several requests with the same `partnerMsgId` value. Until the first request is processed the Service Provider will return the `503` status to the Partner for all following requests with the same `partnerMsgId`.	Troubleshooting The Partner should wait for a response to the first request with the `partnerMsgId` parameter value sent. The Partner can repeat the request if the first request is not answered.

Response in the XML Format#

To receive the response in XML format the Partner needs to send the output = xml parameter in the body of the request.

In this case the Service Provider synchronously responds to the request with one of the following HTTP codes:

200 — the request was successfully processed;
500 — internal server error, technical problems on the Service Provider’s side.

Response Examples#

Response example in XML format in case of successful request sending (HTTP code 200) .

<?xml version="1.0" encoding="utf-8"?>
<response>
    <code>200</code>
    <text>OK</text>
    <payload>
        <id>4095284976</id>
    </payload>
</response>

Response example in XML format in case of error request sending: invalid combination of serviceId/pass.

<?xml version="1.0" encoding="utf-8"?>
<response>
    <code>401</code>
    <text>Invalid password</text>
</response>

When receiving the 500 status or when the timeout of waiting for a response expires, the Partner needs to wait for at least 1 minute. After the pause, the Partner can repeat the request.

Note

When receiving the 500 status more than 10 times, the request transmitting should be stopped. After that, the Partner needs to provide Technical Support Service with the most complete information about the conditions for the occurrence of this error for further analysis.

Name	Required	Description	Note
xml version	yes	Number of XML version.	It is contained in the prologue of the XML document.
encoding	no	Encoding.	It is contained in the prologue of the XML document.
response	yes	A root element. It contains `code`, `text`, `payload` elements.
code	yes	A response code (values correspond to HTTP codes for responses of type text/plain).	For more details see Response to a request in text format.
text	no	Additional brief textual information about the response.	It may contain error information.
payload	no	Information about the message, contains the `id` element.	Would be sent only if the request is performed successfully (when `code = 200`).
id	no	The identifier assigned to the message by the Service Provider. The identifier is a 64-bit positive integer.

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 Error codes (parameter unifiedExtStatus) section.

Cascading Message Sending#

Cascading message sendin for delivering authorization codes via the HTTP protocol is not available (Cascading Message Sending).