# Получение callback

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

Значение callbackUrl должно соответствовать стандарту [RFC 3986](https://tools.ietf.org/html/rfc3986), который в частности допускает:

* использование как защищенной зоны https, так и http
* передачу пары логин:пароль для прохождения Basic-авторизации. Пример:`"callbackUrl": "https://login:password@example.com/callback"`
* передачу ip-адреса и порта в явном виде. Пример:\
  `"callbackUrl": "http://12.34.567.89:8080/callback"`
  {% endhint %}

## Callback по исходящим сообщениям <a href="#outbound_callback" id="outbound_callback"></a>

Если при запросе на отправку сообщений POST /v1/message в объекте сообщения был передан параметр `callbackUrl` (и опционально `callbackEvents`), то при наступлении одного из указанных событий (или события по умолчанию) на указанный `callbackUrl` будет отправлен callback.

| Событие   | Описание                                                                                                                                                                                                                                                                                                                                                        |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| delivered | <p>Получение сообщением одного из статусов:</p><ul><li>delivered – сообщение доставлено</li><li>undelivered – сообщение не доставлено за время жизни (по умолчанию 25 часов)</li><li>unsent – сообщение не отправлено</li></ul><p>Является событием по умолчанию – при наличии <code>callbackUrl</code> и отсутствии <code>callbackEvents</code> в запросе.</p> |
| sent      | Получение сообщением статуса sent – отправлено                                                                                                                                                                                                                                                                                                                  |
| read      | <p>Получение сообщением одного из статусов:</p><ul><li>read – сообщение прочитано</li><li>unread – сообщение не прочитано за время жизни (по умолчанию 25 часов)</li></ul>                                                                                                                                                                                      |
| price     | Изменение цены сообщения                                                                                                                                                                                                                                                                                                                                        |
| click     | Переход по сокращенной ссылке в тексте сообщения                                                                                                                                                                                                                                                                                                                |

### Изменение статуса сообщения <a href="#status_callback" id="status_callback"></a>

При наступлении какого-либо из событий `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          | <p>string</p><p><em>required</em></p>  | uuid сообщения                                                                          |
| channel\_type          | <p>string</p><p><em>required</em></p>  | [Канал сообщения](https://api.docs.direct.i-dgtl.ru/extra/references#channel-types)     |
| cascade\_message\_uuid | <p>string</p><p><em>optional</em></p>  | Идентификатор первого сообщения каскада. Отправляется только для каскадных сообщений    |
| cascade\_step          | <p>integer</p><p><em>optional</em></p> | Порядковый номер сообщения в каскаде. Отправляется только для каскадных сообщений       |
| callback\_event        | <p>string</p><p><em>required</em></p>  | Событие, по которому отправлен callback                                                 |
| external\_message\_id  | <p>string<br><em>optional</em></p>     | Внутренний id сообщения; передается в коллбэке, если был передан в запросе на отправку. |
| status                 | <p>string</p><p><em>required</em></p>  | [Статус сообщения](https://api.docs.direct.i-dgtl.ru/extra/references#message-states)   |
| status\_time           | <p>string</p><p><em>required</em></p>  | Время получения статуса                                                                 |
| error\_code            | <p>integer</p><p><em>optional</em></p> | [Код ошибки](https://api.docs.direct.i-dgtl.ru/extra/error-codes)                       |

### Изменение цены сообщения <a href="#price_callback" id="price_callback"></a>

При наступлении события `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          | <p>string</p><p><em>required</em></p>  | uuid сообщения                                                                                                          |
| channel\_type          | <p>string</p><p><em>required</em></p>  | [Канал сообщения](https://api.docs.direct.i-dgtl.ru/extra/references#channel-types)                                     |
| cascade\_message\_uuid | <p>string</p><p><em>optional</em></p>  | Идентификатор первого сообщения каскада. Отправляется только для каскадных сообщений                                    |
| cascade\_step          | <p>integer</p><p><em>optional</em></p> | Порядковый номер сообщения в каскаде. Отправляется только для каскадных сообщений                                       |
| callback\_event        | <p>string</p><p><em>required</em></p>  | <p>Событие, по которому отправлен callback</p><p>В данном случае: <code>price</code></p>                                |
| external\_message\_id  | <p>string<br><em>optional</em></p>     | Внутренний id сообщения; передается в коллбэке, если был передан в запросе на отправку.                                 |
| parts                  | <p>integer</p><p><em>required</em></p> | Количество частей в сообщении                                                                                           |
| price                  | <p>number</p><p><em>required</em></p>  | Цена сообщения                                                                                                          |
| currency               | <p>string</p><p><em>required</em></p>  | Валюта цены. Трехзначный буквенный код в соответствии с [ISO 4217](https://www.iso.org/ru/iso-4217-currency-codes.html) |
| price\_time            | <p>string</p><p><em>required</em></p>  | Время установки цены сообщению                                                                                          |

### Переход по сокращенной ссылке <a href="#click_callback" id="click_callback"></a>

При наступлении события `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          | <p>string</p><p><em>required</em></p>  | uuid сообщения                                                                           |
| channel\_type          | <p>string</p><p><em>required</em></p>  | [Канал сообщения](https://api.docs.direct.i-dgtl.ru/extra/references#channel-types)      |
| cascade\_message\_uuid | <p>string</p><p><em>optional</em></p>  | Идентификатор первого сообщения каскада. Отправляется только для каскадных сообщений     |
| cascade\_step          | <p>integer</p><p><em>optional</em></p> | Порядковый номер сообщения в каскаде. Отправляется только для каскадных сообщений        |
| callback\_event        | <p>string</p><p><em>required</em></p>  | <p>Событие, по которому отправлен callback</p><p>В данном случае: <code>click</code></p> |
| external\_message\_id  | <p>string<br><em>optional</em></p>     | Внутренний id сообщения; передается в коллбэке, если был передан в запросе на отправку.  |
| url                    | <p>integer</p><p><em>required</em></p> | Оригинальная ссылка                                                                      |
| short\_url             | <p>number</p><p><em>required</em></p>  | Сокращенная ссылка                                                                       |
| click\_time            | <p>string</p><p><em>required</em></p>  | Время перехода по ссылке                                                                 |

## Callback по входящим сообщениям <a href="#inbound_callback" id="inbound_callback"></a>

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

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

Входящие сообщения, для которых не найдено подходящего правила, будут приписаны к ЦРТ по умолчанию (указан на странице [Настройки / Центры разделения трафика](https://direct.i-dgtl.ru/settings/traffic-centers)).

### Получение входящего сообщения <a href="#inbound_sent_callback" id="inbound_sent_callback"></a>

При получении входящего сообщения, для которого нашлось подходящее правило с 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   | <p>string<br><em>required</em></p> | uuid сообщения                                                           |
| callback\_event | <p>string<br><em>required</em></p> | Событие, по которому отправлен callback. В данном случае: `inbound_sent` |
| channel\_type   | <p>string<br><em>required</em></p> | Канал сообщения                                                          |
| status          | <p>string<br><em>required</em></p> | В данном случае: `inbound_sent`                                          |
| status\_time    | <p>string<br><em>requied</em></p>  | Время отправки сообщения                                                 |
| item            | <p>object<br><em>required</em></p> | Объект сообщения в формате объекта ответа GET /v1/message                |

## Ожидаемый ответ <a href="#response" id="response"></a>

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