Telegram#

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

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

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

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

Для формирования тестового запроса с вашими параметрами Внешняя ссылка Открыть генератор запросов 

 1{
 2   "login": "Login",
 3   "password": "Password",
 4   "useTimeDiff": true,
 5   "id": "superId",
 6   "scheduleInfo":
 7   {
 8      "timeBegin": "10:00",
 9      "timeEnd": "12:00",
10      "weekdaysSchedule": "123"
11   },
12   "destAddr": "79211234567",
13   "message":
14   {
15      "type": "TELEGRAM",
16      "data":
17      {
18         "text": "Hello, world!",
19         "serviceNumber": "0000",
20         "ttl": 3600,
21         "ttlUnit": "SECONDS"
22      }
23   }
24}

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

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

Параметр

Тип данных

Описание

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-сообщения#

1 {
2     "mtNum": "7390612217"
3     "id": "8770599"
4 }

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

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

1 {
2     "error": {
3         "code": 4,
4         "description": "Invalid request"
5     },
6     "extendedDescription": "Telegram message is absent"
7 }

В данном примере в 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-сообщений необходимо настроить Сервис получения статусов доставки сообщений.

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

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

 1   {
 2      "mtNum": "107930572",
 3      "status": 9,
 4      "type": "TELEGRAM",
 5      "doneDate": "2024-05-05T10:20:35+0300",
 6      "submitDate": "2024-05-05T10:19:55+0300",
 7      "sourceAddr": "TG_NAME",
 8      "destAddr": "72101234567",
 9      "text": "Hello!",
10      "partCount": "001",
11      "errorCode": "0",
12      "mccMnc": "25012",
13      "trafficType": 0
14   }

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

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

 1 {
 2      "mtNum": "107930572",
 3      "status": 9,
 4      "type": "TELEGRAM",
 5      "doneDate": "2024-05-05T10:20:35+0300",
 6      "submitDate": "2024-05-05T10:19:55+0300",
 7      "sourceAddr": "TG_NAME",
 8      "destAddr": "72101234567",
 9      "text": "Hello!",
10      "partCount": "001",
11      "errorCode": "0",
12      "mccMnc": "25012",
13      "trafficType": 0,
14      "eventType": "view",
15      "eventDate": "2024-05-05T10:30:35+0300",
16      "viewsCount": 2,
17      "clicksCount": 0
18 }