Получение callback
Значение callbackUrl должно соответствовать стандарту RFC 3986, который в частности допускает:
  • использование как защищенной зоны https, так и http
  • передачу пары логин:пароль для прохождения Basic-авторизации. Пример:"callbackUrl": "https://login:[email protected]/callback"
  • передачу ip-адреса и порта в явном виде. Пример: "callbackUrl": "http://12.34.567.89:8080/callback"

Callback по исходящим сообщениям

Если при запросе на отправку сообщений POST /v1/message в объекте сообщения был передан параметр callbackUrl (и опционально callbackEvents), то при наступлении одного из указанных событий (или события по умолчанию) на указанный callbackUrl будет отправлен callback.
Событие
Описание
delivered
Получение сообщением одного из статусов:
  • delivered – сообщение доставлено
  • undelivered – сообщение не доставлено за время жизни (по умолчанию 25 часов)
  • unsent – сообщение не отправлено
Является событием по умолчанию – при наличии callbackUrl и отсутствии callbackEvents в запросе.
sent
Получение сообщением статуса sent – отправлено
read
Получение сообщением одного из статусов:
  • read – сообщение прочитано
  • unread – сообщение не прочитано за время жизни (по умолчанию 25 часов)
price
Изменение цены сообщения
click
Переход по сокращенной ссылке в тексте сообщения

Изменение статуса сообщения

При наступлении какого-либо из событий delivered, sent, read, указанных в запросе на отправку сообщения, на указанный callbackUrl будет отправлен запрос следующего вида:
1
POST {{callback_url}}
2
Content-Type: application/json
3
[
4
{
5
"message_uuid": "063464ec-a34f-4558-90c5-984395000003",
6
"channel_type": "SMS",
7
"cascade_message_uuid": "063464ec-a34f-4558-90c5-984395000002",
8
"cascade_step": 2,
9
"callback_event": "delivered",
10
"status": "undelivered",
11
"status_time": "2020-10-16T18:51:13Z",
12
"error_code": 6969
13
}
14
]
Copied!
Параметр
Тип
Описание
message_uuid
string
required
uuid сообщения
channel_type
string
required
cascade_message_uuid
string
optional
Идентификатор первого сообщения каскада. Отправляется только для каскадных сообщений
cascade_step
integer
optional
Порядковый номер сообщения в каскаде. Отправляется только для каскадных сообщений
callback_event
string
required
Событие, по которому отправлен callback
status
string
required
status_time
string
required
Время получения статуса
error_code
integer
optional

Изменение цены сообщения

При наступлении события price, если оно было указано в запросе на отправку сообщения, на указанный callbackUrl будет отправлен запрос следующего вида:
1
POST {{callback_url}}
2
Content-Type: application/json
3
[
4
{
5
"message_uuid": "063464ec-a34f-4558-90c5-984395000003",
6
"channel_type": "SMS",
7
"cascade_message_uuid": "063464ec-a34f-4558-90c5-984395000002",
8
"cascade_step": 2,
9
"callback_event": "price",
10
"parts": 5,
11
"price": 10.25,
12
"currency": "RUB",
13
"price_time": "2020-10-16T18:51:13Z"
14
}
15
]
Copied!
Параметр
Тип
Описание
message_uuid
string
required
uuid сообщения
channel_type
string
required
cascade_message_uuid
string
optional
Идентификатор первого сообщения каскада. Отправляется только для каскадных сообщений
cascade_step
integer
optional
Порядковый номер сообщения в каскаде. Отправляется только для каскадных сообщений
callback_event
string
required
Событие, по которому отправлен callback
В данном случае: price
parts
integer
required
Количество частей в сообщении
price
number
required
Цена сообщения
currency
string
required
Валюта цены. Трехзначный буквенный код в соответствии с ISO 4217
price_time
string
required
Время установки цены сообщению

Переход по сокращенной ссылке

При наступлении события click, если оно было указано в запросе на отправку сообщения, на указанный callbackUrl будет отправлен запрос следующего вида:
1
POST {{callback_url}}
2
Content-Type: application/json
3
[
4
{
5
"message_uuid": "063464ec-a34f-4558-90c5-984395000003",
6
"callback_event": "click",
7
"channel_type": "SMS",
8
"cascade_message_uuid": "31d6f174-2ef6-4f25-b03b-c4c06e0e4df8",
9
"cascade_step": 3,
10
"url": "https://www.yandex.ru",
11
"short_url": "a.bc/69EwQ",
12
"click_time": "2021-04-21T17:41:43Z"
13
}
14
]
Copied!
Параметр
Тип
Описание
message_uuid
string
required
uuid сообщения
channel_type
string
required
cascade_message_uuid
string
optional
Идентификатор первого сообщения каскада. Отправляется только для каскадных сообщений
cascade_step
integer
optional
Порядковый номер сообщения в каскаде. Отправляется только для каскадных сообщений
callback_event
string
required
Событие, по которому отправлен callback
В данном случае: click
url
integer
required
Оригинальная ссылка
short_url
number
required
Сокращенная ссылка
click_time
string
required
Время перехода по ссылке

Callback по входящим сообщениям

Для получения событий по входящим сообщениям:
  1. 1.
    Подключите возможность получения входящих, написав вашему менеджеру (на данный момент доступно только для канала WhatsApp)
  2. 2.
    Перейдите на страницу ЛК Настройки / Входящий трафик
  3. 3.
    Нажмите Добавить и заполните форму
    1. 1.
      В поле ЦРТ нужно указать центр разделения трафика, к которому должны быть приписаны входящие сообщения
    2. 2.
      В поле Callback URL нужно указать адрес, на который будет отправлен callback при получении входящего сообщения
    3. 3.
      При указании Учитывать имена отправителей можно выбрать имена, для входящих сообщений которых будут присваиваться выбранные ЦРТ и CallbackUrl (если не учитывать имена, то присвоение ЦРТ и CallbackUrl будет действовать для всех входящих сообщений канала)
Входящие сообщения, для которых не найдено подходящего правила, будут приписаны к ЦРТ по умолчанию (указан на странице Настройки / Центры разделения трафика).

Получение входящего сообщения

При получении входящего сообщения, для которого нашлось подходящее правило с CallbackUrl, на заданный адрес отправляется запрос следующего вида:
1
POST {{callback_url}}
2
[
3
{
4
"message_uuid": "063464ec-9999-4558-90c5-984395000001",
5
"callback_event": "inbound_sent",
6
"channel_type": "WHATSAPP",
7
"status": "inbound_sent",
8
"status_time": "2021-11-15T18:38:07Z",
9
"item": {
10
"createdTime": "2021-12-06T16:31:22.892Z",
11
"sentTime": "2021-11-15T18:38:07.000Z",
12
"messageUuid": "063464ec-9999-4558-90c5-984395000001",
13
"direction": "inbound",
14
"channelType": "VIBER",
15
"trafficCenterId": 111,
16
"senderName": "UNDELIV2",
17
"destination": "79219346527",
18
"content": "<текст сообщения>",
19
"specialContent": {
20
"text": "<текст сообщения>",
21
"contentType": "text"
22
},
23
"totalParts": 1
24
}
25
}
26
]
Copied!
Параметр
Тип
Описание
message_uuid
string required
uuid сообщения
callback_event
string required
Событие, по которому отправлен callback. В данном случае: inbound_sent
channel_type
string required
Канал сообщения
status
string required
В данном случае: inbound_sent
status_time
string requied
Время отправки сообщения
item
object required
Объект сообщения в формате объекта ответа GET /v1/message

Ожидаемый ответ

В ответ на callback любого типа ожидается получение HTTP-кода 2**. При отсутствии ответа в течение суток будет производиться переотправка с периодичностью раз в 5 минут.