# Получение 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>  | [Канал сообщения](/extra/references.md#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>  | [Статус сообщения](/extra/references.md#message-states)                                 |
| status\_time           | <p>string</p><p><em>required</em></p>  | Время получения статуса                                                                 |
| error\_code            | <p>integer</p><p><em>optional</em></p> | [Код ошибки](/extra/error-codes.md)                                                     |

### Изменение цены сообщения <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>  | [Канал сообщения](/extra/references.md#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>  | [Канал сообщения](/extra/references.md#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 минут.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.docs.direct.i-dgtl.ru/messages/callback.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.