Коды авторизации Telegram Gateway#

В данном разделе приведено описание особенностей передачи авторизационных кодов по протоколу HTTP в Telegram Gateway.

Подробнее

Сервис Telegram Gateway предназначен для доставки пользователям мессенджера Telegram авторизационных и верификационных цифровых кодов.

Отправка кодов происходит от имени официального канала Verification Codes.

Если пользователь скрывает свой номер телефона в настройках Telegram, это не влияет на доставку сообщения. Также на доставку кодов не влияет наличие или отсутствие у пользователя подписки Telegram Premium.

Отправка цифровых кодов в Telegram возможна в текстах сообщений типа SMS. В процессе обработки сообщения будут конвертированы в TG-формат и переданы в Telegram.

На данный момент сервис поддерживает:

  • отправку сообщений с кодами авторизации через Telegram;
  • получение статусов доставки сообщений;
  • каскадную передачу сообщений в SMS в случае недоставки в Telegram (при необходимости).

Подключение#

Подключение сервиса осуществляет служба технической поддержки Сервис-провайдера.

Для подключения Партнеру и Сервис-провайдеру необходимо согласовать данные:

  • сервисное имя для передачи авторизационного кода в Telegram;

  • время жизни сообщения.

Запрос на отправку#

В запросе на передачу авторизационного кода в Telegram необходимо указывать сервисное имя, отдельно согласованное со службой технической поддержки.

В запросе рекомендуется указать параметры и значения, относящиеся к типу сообщения SMS.

Сообщение должно содержать код от четырёх до восьми цифр.

Метод: GET.

Примеры запросов#

GET-запрос с сообщением на латинице code 12345 в простом текстовом формате:

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

Параметры запросов#

В таблице обязательные параметры выделены полужирным шрифтом.

Параметр

Тип

Описание

clientId

string

Номер телефона абонента, до 25 символов.

Примеры: 79036550550, +79036550550, 8-903-655-05-50, 89036550550.

message

string
Сообщение для отправки абоненту.
Должно содержать код от четырёх до восьми цифр.
Подробнее

Текст в данном параметре должен быть в кодировке UTF-8.

Максимально допустимая длина сообщения: 2000 символов.

serviceId

string

Идентификатор сервиса (логин), от имени которого происходит отправка сообщения.

Подробнее

Сервис-провайдер заводит логин serviceId при подключении сервиса и сообщает его Партнёру.

pass

string

Пароль для авторизации в сервисе.

Подробнее

Сервис-провайдер заводит пароль при подключении сервиса и сообщает его Партнёру.

ptag

string

Идентификатор сообщения в системе Партнёра.

Подробнее

Допустимые символы: 0...9a...zA...Z-

Количество символов: от одного до 50.

Это может быть любой идентификатор в системе Партнёра. Например, уникальный идентификатор сообщения или идентификатор подразделения, инициирующего запрос на отправку. В отличие от параметра partnerMsgId, который нужен для контроля повторных отправок и дублирования, Сервис-провайдер не контролирует значения, переданные в параметре ptag (проверяется только соответствие формату).

Сервис-провайдер опционально возвращает Партнёру данный идентификатор в рамках запроса на получение статуса доставки сообщения (см. Сервис получения статусов доставки).

source

string

Сервисное имя отправителя.

Подробнее

В запросе на передачу авторизационного кода (в т.ч. в основном канале при каскадной отправке) необходимо указывать сервисное имя, отдельно согласованное со службой технической поддержки.

output

string

Формат ответа на запрос.

Подробнее

Если output=xml, то ответ на запрос будет сформирован в виде XML см. Ответ в формате XML.

Если параметр не задан или имеет другое значение, будет применён формат по умолчанию: простой текст (text/plain), см. Ответ на запрос в текстовом формате.

partnerMsgId

string

Уникальный идентификатор сообщения в системе Партнёра.

Подробнее

Количество символов: от одного до 50.

Данный параметр используется для контроля повторных отправок и дублирования. Партнёр может отправить запрос на отправку сообщения с одним и тем же partnerMsgId несколько раз.

При этом:

  • отправка сообщения абоненту будет выполнена только один раз (по первому запросу);
  • в ответах на данные запросы Сервис-провайдер вернет Партнёру один и тот же идентификатор сообщения в системе Сервис-провайдера (тот же, что на первый запрос).

Сервис-провайдер опционально возвращает Партнёру данный идентификатор в рамках запроса на получение статуса доставки сообщения (см. Сервис получения статусов доставки).

Использование данного параметра недоступно по умолчанию. Подключение данного функционала следует согласовать со своим курирующим менеджером.

smsPriority

integer

Параметр указывает на приоритет сообщения.

Подробнее

Сообщения с более высоким приоритетом отправляются оператору в первую очередь.

Возможные значения:

  • 0 – самый низкий приоритет;
  • 1 – нормальный приоритет;
  • 2 – высокий приоритет.

Использование данного параметра недоступно по умолчанию. Подключение данного функционала следует согласовать со своим курирующим менеджером.

Ответ на запрос#

После получения и обработки запроса Сервис-провайдер синхронно возвращает Партнёру ответ.
По умолчанию ответ от Сервис-провайдера приходит в формате text/plain.
По согласованию с Партнёром ответ может быть сформирован в формате XML.

Примечание

Сервис-провайдер отправляет сообщения абонентам только при успешной обработке запроса.

Ответ на запрос в текстовом формате#

Ответ при успешной отправке запроса#

На успешный запрос Сервис-провайдер возвращает Партнёру:

  • HTTP-код 200 OK;

  • идентификатор сообщения в системе Сервис-провайдера.

OK
4095284974

Ошибки при отправке запроса#

При передаче ошибочного запроса в теле ответа может возвращаться короткое текстовое сообщение об ошибке.

Пример ответа в случае возникновения ошибки – неверного сочетания serviceId/pass:

Invalid password

Ответ в формате XML#

Для получения ответа в формате XML Партнеру в теле запроса необходимо передать параметр output=xml.
В таком случае Сервис-провайдер синхронно отвечает на запрос одним из следующих HTTP-кодов:

  • 200 – запрос успешно обработан;

  • 500 – внутренняя ошибка сервера, технические проблемы на стороне Сервис-провайдера.

Примеры ответов#

Пример ответа в формате XML при успешной отправке запроса (HTTP-код 200) .

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

Статусы доставки сообщений#

Для получения статусов сообщений необходимо настроить Сервис получения статусов доставки.

Важно

При отправке абоненту в мессенджер Telegram авторизационных кодов возможно получение только следующих статусов:

  • 2 – доставлено;

  • 5 – не доставлено.

Каскадная отправка#

Каскадная рассылка сообщений по умолчанию недоступна. Для подключения и настройки Партнёру необходимо обратиться в службу технической поддержки Сервис-провайдера.

Для передачи сообщений в каскаде (Telegram > SMS) Партнёру достаточно будет отправить запрос на отправку только первого сообщения каскада.

Далее каскад сработает автоматически на основе настроек.