Рассылка 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	Пароль Партнёра.
destAddr	да	string	Номер телефона абонента. Подробнее Содержит код страны, код оператора и номер телефона. Для РФ код может быть 8, 7 или +7. Примеры: 72101234567, +72101234567, 8-210-123-45-67, 82101234567.
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.
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 – значения. Пример: строка место=турбаза,название=гостевой дом 3 Символ запятой в название параметра входить не может, но может входить в его значение. В в этом случае он должен удваиваться. Пример: координаты=53.8085896,,58.6362112
registeredDelivery	нет	integer	Необходимость отчётов о доставке. Подробнее Укажите, нужны ли отчёты о доставке для отслеживания статусов. Допустимые значения: 0 – статусы не нужны; 1 – статусы нужны (значение по умолчанию); 2 – нужен только статус НЕ ДОСТАВЛЕНО.
notifyUrl	нет	string	Имя хоста входящего API для получения отчета о доставке. Подробнее Этот параметр в запросе необязательный, но при его отправке нужно учесть следующее: если параметр указан, он не может быть пустым; длина строки notifyUrl не должна превышать 2048 символов. При невыполнении любого из указанных условий будет сгенерирована ошибка, запрос не будет выполнен.
cascadeChainLink	нет	object	Параметры каскадных сообщений. См. Каскадная рассылка.

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

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

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

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

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

{
    "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
}