Telegram

Поддерживаются следующие варианты Telegram-сообщений:

• только текст;

• текст + ссылка для перехода.

Примеры запросов на отправку Telegram-сообщений

ТекстТекст + ссылка

{
   "login": "Login",
   "password": "Password",
   "useTimeDiff": true,
   "id": "superId",
   "scheduleInfo":
   {
      "timeBegin": "10:00",
      "timeEnd": "12:00",
      "weekdaysSchedule": "123"
   },
   "destAddr": "79211234567",
   "message":
   {
      "type": "TELEGRAM",
      "data":
      {
         "text": "Hello, world!",
         "serviceNumber": "0000",
         "ttl": 3600,
         "ttlUnit": "SECONDS"
      }
   }
}

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

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

Параметр	Тип данных	Описание
login	string	Имя Партнёра.
password	string	Пароль Партнёра для отправки сообщений.
useTimeDiff	boolean	Учитывание часового пояса при запуске рассылки. Если true, то отправка сообщения осуществляется абоненту согласно расписанию рассылки и его часовому поясу. Если false, то сообщение отправляется согласно расписанию инициатора рассылки UTC+3, не обращая внимание на часовой пояс получателя сообщения. Значение по умолчанию: false.
id	string	Уникальный идентификатор на стороне Партнёра. Данный параметр нужен для контроля повторных отправок и дублирования (сервис контроля включается отдельно). Партнёр может вызывать Сервис-провайдера (запрос на отправку сообщения) с одним и тем же id несколько раз. При этом: отправка сообщения абоненту будет выполнена только один раз (по первому запросу). В ответах на запросы Сервис-провайдер вернет Партнёру один и тот же идентификатор сообщения в системе Сервис-провайдера (тот же, что на первый запрос). Сервис-провайдер опционально возвращает Партнёру данный идентификатор при его наличии в отчёте о доставке сообщения.
scheduleInfo	object	Расписание рассылки. Если не указано, отправляется сразу же, в момент получения запроса.
scheduleInfo/timeBegin	string	Время начала, например, «10:00».
scheduleInfo/timeEnd	string	Время окончания, например, «21:00».
scheduleInfo/weekdaysSchedule	string	Дни рассылки. Задаются цифрами от 1 (понедельник) до 7 (воскресение), например, «12345». Если ограничений по дням недели нет, то данный параметр может быть пустой или не передан в запросе.
scheduleInfo/deadline	string	Дата окончания рассылки, например, 2019-05-10T16:29:30+0300.
destAddr	string	Номер телефона абонента. Содержит код страны, код оператора и номер телефона. Для РФ код может быть „8“, „7“ или „+7“. Примеры: 72101234567, +72101234567, 8-210-123-45-67, 82101234567.
message	object	Параметры отправляемого сообщения.
message/type	enum	Тип сообщения. Передается значение TELEGRAM.
message/data	object	Параметры отправляемых данных. Для передачи только текста следует указать атрибут text. Для передачи текста и ссылки для перехода - text и link.
message/data/text	string	Текст отправляемого сообщения. Количество символов: не более 1000. Текст сообщения может быть на кириллице или латинице, содержать эмоджи.
message/data/link	string	Произвольный URL-адрес, передаваемый в тексте Telegram-сообщения. Количество символов в ссылке - не более 256. Если передан пустой параметр, сообщение будет отклонено с ошибкой. Текст ошибки «В сообщении отсутствует значение у параметра link». Если длина ссылки превысит указанное значение, то сообщение будет отклонено с ошибкой. Текст ошибки: «В сообщении превышен лимит значения у параметра link».
message/data/serviceNumber	string	Сервисное имя, от которого осуществляется отправка сообщения.
message/data/ttl	integer	Срок жизни сообщения. Допустимый диапазон, сек: от 30 до 86400. Примечание. При ttl = 0 или отсутствии параметра в запросе берётся значение из настроек по умолчанию, которые задаются при настройке интеграции отдельно для каждого клиента.
message/data/ttlUnit	enum	Единица измерения периода доставки сообщения. Передается только вместе с ttl. Допустимые значения: SECONDS; MINUTES (значение по-умолчанию); HOURS.
extraParam	string	Дополнительные параметры, передаваемые в виде param1=value1,param2=value2, где param1 и param2 – названия параметров, value1 и value2 – значения. Символ запятой в название параметра входить не может, но может входить в его значение - в этом случае он должен удваиваться. Пример: строка место=абзаково,название=гостевой дом-2,координаты=53.8085896,, 58.6362112,c=23.02.09,по=05.03.09.
registeredDelivery	integer	Необходимость отчётов о доставке. Возможные значения: 0 - статусы не нужны; 1 - нужны статусы (по умолчанию); 2 - нужен только статус НЕ ДОСТАВЛЕНО.
notifyUrl	string	Hostname входящего api для получения отчета о доставке. Этот параметр в запросе необязательный, но при его отправке нужно учесть следующее: если парметр указан, он не может быть пустым. Длина строки notifyUrl не должна превышать 2048 символов. При невыполнении любого из указанных условий будет сгенерирована ошибка, запрос не будет выполнен.
cascadeChainLink	object	Параметры каскадных сообщений. См. Каскадная рассылка.

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

После отправки сообщения Сервис-провайдер синхронно возвращает ответ. В случае успешной отправки возвращается HTTP-code 200 OK.

Ответ при успешной отправке Telegram-сообщения

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

{
    "mtNum": "7390612217"
    "id": "8770599"
}

Ошибки при отправке Telegram-сообщения

Для ошибочных результатов HTTP-код ответа будет отличный от 200 (см. Коды ошибок отправки).

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

{
    "error": {
        "code": 4,
        "description": "Invalid request"
    },
    "extendedDescription": "Telegram message is absent"
}

В данном примере в Telegram-сообщении текст отсутствует, а передаётся только ссылка, что является ошибкой.

Коды ошибок отправки

Код	Описание	HTTP-код
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

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

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

Пример запроса

Описание параметров приведено в п. Отчёт о доставке.

   {
      "mtNum": "107930572",
      "status": 9,
      "type": "TELEGRAM",
      "doneDate": "2024-05-05T10:20:35+0300",
      "submitDate": "2024-05-05T10:19:55+0300",
      "sourceAddr": "TG_NAME",
      "destAddr": "72101234567",
      "text": "Hello!",
      "partCount": "001",
      "errorCode": "0",
      "mccMnc": "25012",
      "trafficType": 0
   }

Уведомление о событии

Дополнительные параметры предназначены для передачи корректной статистики по показам и переходам в Telegram-сообщениях.

Пример запросаОписание параметров

{
     "mtNum": "107930572",
     "status": 9,
     "type": "TELEGRAM",
     "doneDate": "2024-05-05T10:20:35+0300",
     "submitDate": "2024-05-05T10:19:55+0300",
     "sourceAddr": "TG_NAME",
     "destAddr": "72101234567",
     "text": "Hello!",
     "partCount": "001",
     "errorCode": "0",
     "mccMnc": "25012",
     "trafficType": 0,
     "eventType": "view",
     "eventDate": "2024-05-05T10:30:35+0300",
     "viewsCount": 2,
     "clicksCount": 0
}