Вебхуки

Коротко: вебхук — это URL, на который платформа отправляет события: статусы сообщений, входящие сообщения и статусы рассылок. URL задаётся в трёх местах, платформа использует первый непустой.

Кому подходит

• Роль: Разработчик
• Уровень: Опытный

Что такое вебхук

Вебхук — это HTTP-запрос, который платформа отправляет на указанный вами URL, когда происходит событие. Так вы получаете уведомления о статусах сообщений, ответах получателей и статусах рассылок.

Как задаётся URL вебхука

Вебхук разрешается в следующем порядке (используется первое непустое значение):

1. Поле webhook в теле запроса.
2. Вебхук, настроенный для имени отправителя.
3. Вебхук, настроенный для API-доступа (API-ключ или Basic Auth).

Если ни одно значение не задано, вебхук не отправляется.

Типы событий

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

Отправляется в эндпоинтах OMNI API, когда сообщение меняет статус.

Формат:

{
  "event": "messageStatus",
  "message": {
    "messageId": "4aab1947-7a34-4efe-8c51-e9c8f9b1412b",
    "omniTransactionId": "57f29fdd-1127-45b3-a7d5-260a831a4662",
    "channel": 2,
    "senderId": "emulator",
    "status": "delivered",
    "timestamp": "2023-09-08T15:30:00Z",
    "contact": "905324546496",
    "cost": "1.00",
    "clientInfo": "custom_data"
  }
}

Поля:

Возможные статусы:

Причина ошибки (reason):

Альтернатива: pull-запрос

Вебхук — это push-способ: платформа сама отправляет статус на ваш URL.

Если push не подходит — например, удобно обойтись без своего эндпоинта или статусы нужны пачкой раз в час — статусы можно запрашивать самостоятельно через API. Это pull-способ.

Эндпоинт: GET /api/v1/edrs — возвращает записи о доставке сообщений.

Подробнее о двух способах получения статусов — в статьях по сервисам:

• Статусы сообщений в OTP-кодах
• Статусы сообщений в Multi API
• Статусы сообщений в «Мой диалог»

Входящее сообщение (message)

Отправляется, когда получатель отвечает на ваше сообщение (MO — Mobile Originated).

Формат:

{
  "event": "message",
  "message": {
    "messageId": "4aab1947-7a34-4efe-8c51-e9c8f9b1412b",
    "omniTransactionId": "57f29fdd-1127-45b3-a7d5-260a831a4662",
    "timestamp": "2023-09-08T15:30:00Z",
    "channel": "SMS",
    "senderId": "2813380676",
    "contact": "8172958708",
    "payload": {
      "text": "test SMS"
    }
  }
}

Поля:

Статус рассылки

Отправляется из Broadcasts API. Приходит, когда рассылка меняет статус.

Формат:

См. также

Нужна помощь?

• OTP-коды: support@otpcod.ru
• Multi API: support@multiapi.ru
• Мой диалог: support@mydialogi.ru