Получение callback

Получение callback#

{% hint style=»info» %} Callback-и от сервиса приходят с IP-адреса 185.203.96.7

Значение callbackUrl должно соответствовать стандарту RFC 3986, который в частности допускает:

  • использование как защищенной зоны https, так и http

  • передачу пары логин:пароль для прохождения Basic-авторизации. Пример:"callbackUrl": "https://login:password@example.com/callback"

  • передачу ip-адреса и порта в явном виде. Пример:
    "callbackUrl": "http://12.34.567.89:8080/callback" {% endhint %}

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 будет отправлен запрос следующего вида:

POST {{callback_url}}
Content-Type: application/json
[
  {
    "message_uuid": "063464ec-a34f-4558-90c5-984395000003",
    "channel_type": "SMS",
    "cascade_message_uuid": "063464ec-a34f-4558-90c5-984395000002",
    "cascade_step": 2,
    "callback_event": "delivered",
    "external_message_id": "10898",
    "status": "undelivered",
    "status_time": "2020-10-16T18:51:13Z",
    "error_code": 6969
  }
]

Параметр

Тип

Описание

message_uuid

string

required

uuid сообщения

channel_type

string

required

Канал сообщения

cascade_message_uuid

string

optional

Идентификатор первого сообщения каскада. Отправляется только для каскадных сообщений

cascade_step

integer

optional

Порядковый номер сообщения в каскаде. Отправляется только для каскадных сообщений

callback_event

string

required

Событие, по которому отправлен callback

external_message_id

string
optional

Внутренний id сообщения; передается в коллбэке, если был передан в запросе на отправку.

status

string

required

Статус сообщения

status_time

string

required

Время получения статуса

error_code

integer

optional

Код ошибки

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

При наступлении события price, если оно было указано в запросе на отправку сообщения, на указанный callbackUrl будет отправлен запрос следующего вида:

POST {{callback_url}}
Content-Type: application/json
[
  {
    "message_uuid": "063464ec-a34f-4558-90c5-984395000003",
    "channel_type": "SMS",
    "cascade_message_uuid": "063464ec-a34f-4558-90c5-984395000002",
    "cascade_step": 2,
    "callback_event": "price",
    "external_message_id": "10898",
    "parts": 5,
    "price": 10.25,
    "currency": "RUB",
    "price_time": "2020-10-16T18:51:13Z"
  }
]

Параметр

Тип

Описание

message_uuid

string

required

uuid сообщения

channel_type

string

required

Канал сообщения

cascade_message_uuid

string

optional

Идентификатор первого сообщения каскада. Отправляется только для каскадных сообщений

cascade_step

integer

optional

Порядковый номер сообщения в каскаде. Отправляется только для каскадных сообщений

callback_event

string

required

Событие, по которому отправлен callback

В данном случае: price

external_message_id

string
optional

Внутренний id сообщения; передается в коллбэке, если был передан в запросе на отправку.

parts

integer

required

Количество частей в сообщении

price

number

required

Цена сообщения

currency

string

required

Валюта цены. Трехзначный буквенный код в соответствии с ISO 4217

price_time

string

required

Время установки цены сообщению

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

При наступлении события click, если оно было указано в запросе на отправку сообщения, на указанный callbackUrl будет отправлен запрос следующего вида:

POST {{callback_url}}
Content-Type: application/json
[
  {
    "message_uuid": "063464ec-a34f-4558-90c5-984395000003",
    "callback_event": "click",
    "channel_type": "SMS",
    "cascade_message_uuid": "31d6f174-2ef6-4f25-b03b-c4c06e0e4df8",
    "cascade_step": 3,
    "external_message_id": "10898",
    "url": "https://www.yandex.ru",
    "short_url": "a.bc/69EwQ",
    "click_time": "2021-04-21T17:41:43Z"
  }
]

Параметр

Тип

Описание

message_uuid

string

required

uuid сообщения

channel_type

string

required

Канал сообщения

cascade_message_uuid

string

optional

Идентификатор первого сообщения каскада. Отправляется только для каскадных сообщений

cascade_step

integer

optional

Порядковый номер сообщения в каскаде. Отправляется только для каскадных сообщений

callback_event

string

required

Событие, по которому отправлен callback

В данном случае: click

external_message_id

string
optional

Внутренний id сообщения; передается в коллбэке, если был передан в запросе на отправку.

url

integer

required

Оригинальная ссылка

short_url

number

required

Сокращенная ссылка

click_time

string

required

Время перехода по ссылке

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

Для получения событий по входящим сообщениям:

  1. Подключите возможность получения входящих, написав вашему менеджеру (на данный момент доступно только для канала WhatsApp)

  2. Перейдите на страницу ЛК Настройки / Входящий трафик

  3. Нажмите Добавить и заполните форму

    1. В поле ЦРТ нужно указать центр разделения трафика, к которому должны быть приписаны входящие сообщения

    2. В поле Callback URL нужно указать адрес, на который будет отправлен callback при получении входящего сообщения

    3. При указании Учитывать имена отправителей можно выбрать имена, для входящих сообщений которых будут присваиваться выбранные ЦРТ и CallbackUrl (если не учитывать имена, то присвоение ЦРТ и CallbackUrl будет действовать для всех входящих сообщений канала)

Входящие сообщения, для которых не найдено подходящего правила, будут приписаны к ЦРТ по умолчанию (указан на странице Настройки / Центры разделения трафика).

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

При получении входящего сообщения, для которого нашлось подходящее правило с CallbackUrl, на заданный адрес отправляется запрос следующего вида:

POST {{callback_url}}
[
  {
    "message_uuid": "063464ec-9999-4558-90c5-984395000001",
    "callback_event": "inbound_sent",
    "channel_type": "WHATSAPP",
    "status": "inbound_sent",
    "status_time": "2021-11-15T18:38:07Z",
    "item": {
      "createdTime": "2021-12-06T16:31:22.892Z",
      "sentTime": "2021-11-15T18:38:07.000Z",
      "messageUuid": "063464ec-9999-4558-90c5-984395000001",
      "direction": "inbound",
      "channelType": "VIBER",
      "trafficCenterId": 111,
      "senderName": "UNDELIV2",
      "destination": "79219346527",
      "content": "<текст сообщения>",
      "specialContent": {
        "text": "<текст сообщения>",
        "contentType": "text"
      },
      "totalParts": 1
    }
  }
]

Параметр

Тип

Описание

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 минут.