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

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

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

Сервис-провайдер поддерживает:

  • отправку сообщений с кодами авторизации через Telegram Gateway;

  • получение статусов доставки сообщений.

О Telegram Gateway

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

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

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

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

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

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

  • сервисное имя для передачи авторизационного кода в 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-

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

Это может быть любой идентификатор в системе Партнёра.

Примечание

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

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

source

да

string

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

Подробнее

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

output

нет

string

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

Подробнее

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

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

partnerMsgId

нет

string

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

Подробнее

Количество символов: от 1 до 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>

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

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

Коды ошибок доставки#

Коды ошибок доставки, в зависимости от типа сообщения, приведены в соответствующей вкладке в разделе Описание кодов ошибок (параметр unifiedExtStatus).

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

Каскадная рассылка для передачи авторизационных кодов по протоколу HTTP недоступна (см. Каскадная рассылка).