Отправка шаблонов через Omni API

Коротко: шаблоны можно отправлять через Omni API, указав параметр template с ID шаблона и его параметрами.

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

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

Что это

Omni API — интерфейс для отправки сообщений через платформу. Он поддерживает два эндпоинта:

• POST /api/v1/messages — отправка одного сообщения.
• POST /api/v1/omnimessages — каскадная отправка с автоматическим переключением между каналами.

В тело запроса добавляется параметр template. Он обязателен, если нужно отправить сообщение по шаблону. Для произвольного сообщения используется параметр payload.

Эндпоинты

Параметр template

Как работает каскад

В каскадном запросе (/api/v1/omnimessages) вы передаёте массив messages — по одному объекту на каждый канал.

Для каждого сообщения (кроме последнего) можно указать:

• successOn — статус, при котором сообщение считается успешным и переход на следующий канал не нужен. Возможные значения: sent, delivered, seen. По умолчанию sent.
• timeout — время в секундах, в течение которого платформа ждёт наступления successOn. Если статус не наступил — отправляется следующее сообщение из массива. По умолчанию 1200 секунд (20 минут).

На верхнем уровне запроса можно указать cooldown — время в секундах, на которое контакт блокируется, если последнее сообщение в каскаде не было успешным. По умолчанию блокировка выключена.

Пример 1. Отправка через RCS

curl --location 'https://<API-endpoint>/api/v1/messages' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <APItoken>' \
  --data-raw '{
    "contact": "<dnis>",
    "webhook": "<webhookURL>",
    "channel": 2,
    "senderId": "<senderID>",
    "template": {
      "id": <templateID>,
      "params": {
        "attribute.phoneNumber": "112332",
        "attribute.name": "test-name"
      }
    }
  }'

Пример 2. Каскад RCS → SMS: два шаблона

curl --location 'https://<API-endpoint>/api/v1/omnimessages' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <APItoken>' \
  --data-raw '{
    "contact": "<dnis>",
    "webhook": "<webhookURL>",
    "isOtp": true,
    "cooldown": 86400,
    "messages": [
      {
        "channel": 2,
        "senderId": "<senderID>",
        "successOn": "delivered",
        "timeout": 60,
        "template": {
          "id": <rcsTemplateID>,
          "params": {
            "attribute.phoneNumber": "112332",
            "attribute.name": "test-name"
          }
        }
      },
      {
        "channel": 1,
        "senderId": "<senderID>",
        "template": {
          "id": <smsTemplateID>,
          "params": {
            "attribute.phoneNumber": "112332",
            "attribute.code": "1234"
          }
        }
      }
    ]
  }'

Пример 3. Каскад RCS-шаблон → SMS-текст

curl --location 'https://<API-endpoint>/api/v1/omnimessages' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <APItoken>' \
  --data-raw '{
    "contact": "<dnis>",
    "webhook": "<webhookURL>",
    "messages": [
      {
        "channel": 2,
        "senderId": "<senderID>",
        "successOn": "delivered",
        "timeout": 60,
        "template": {
          "id": <rcsTemplateID>,
          "params": {
            "attribute.phoneNumber": "112332"
          }
        }
      },
      {
        "channel": 1,
        "senderId": "<senderID>",
        "payload": {
          "type": "text",
          "text": "Резервное сообщение"
        }
      }
    ]
  }'

Таблица параметров запроса

*- нужен либо payload, либо template.

Таблица каналов

Что в ответе

Пример успешного ответа:

{
    "error": false,
    "data": {
        "channel": 4,
        "transactionId": "95e3e0da-9684-4ba4-88a3-e9207ddeca05",
        "messageId": "6719b5f4-36af-4fba-b111-49ff07f4f96b"
    }
}

Вебхуки

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

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

1. Поле webhook в теле запроса.
2. Вебхук, настроенный для имени отправителя.
3. Вебхук, настроенный для 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"
  }
}

Возможные статусы: sent, failed, delivered, undeliverable, displayed, unknown.

Частые проблемы

Что дальше

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

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