Broadcasts API — рассылки и шаблоны

Коротко: Broadcasts API запускает рассылки и управляет их шаблонами. Рассылка может использовать готовый шаблон или inline-содержимое через payload.

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

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

Что такое Broadcasts API

Broadcasts API — интерфейс для работы с рассылками. Два блока:

• Запуск рассылки — POST /broadcast/broadcasts.
• Управление шаблонами рассылок — /broadcast/templates.

Каждая рассылка запускается через шаблон или через inline-содержимое. Все результаты приходят на вебхук.

Эндпоинты

Полный URL: https://web.multiapi.ru/api/v1/broadcast/broadcasts и https://web.multiapi.ru/api/v1/broadcast/templates.

Запуск рассылки

Эндпоинт: POST /broadcast/broadcasts

Параметры запроса:

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

Пример 1. Запуск рассылки по шаблону:

curl --location 'https://web.multiapi.ru/api/v1/broadcast/broadcasts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "templateId": 3091,
    "launchTime": "",
    "webhook": "https://webhook.site/9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a"
  }'

Пример 2. Отложенная рассылка с указанием получателей:

curl --location 'https://web.multiapi.ru/api/v1/broadcast/broadcasts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "templateId": 3091,
    "launchTime": "2024-08-30T09:14:45.410958Z",
    "webhook": "https://webhook.site/9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a",
    "recipientsList": [
      { "phoneNumber": "4915735987904" }
    ]
  }'

Пример 3. Рассылка без шаблона (inline-содержимое):

curl --location 'https://web.multiapi.ru/api/v1/broadcast/broadcasts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "name": "Летняя распродажа",
    "description": "Распродажа летней коллекции",
    "launchTime": "2025-08-30T09:14:45.410958Z",
    "webhook": "https://webhook.site/9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a",
    "recipientsList": [
      { "phoneNumber": "4915735987904" },
      { "phoneNumber": "4948735987296" }
    ],
    "payload": {
      "contentType": 1,
      "contentSettings": {
        "flowSteps": [
          {
            "channelType": 1,
            "senderId": "smsGate",
            "timeout": 172800,
            "deliveryCondition": "SUBMIT_SUCCESS",
            "contentPattern": "Привет! Наша летняя распродажа начинается сегодня!"
          }
        ]
      }
    }
  }'

Формат payload

Поле payload используется для inline-содержимого, когда рассылка запускается без шаблона.

Объект contentSettings:

Элемент flowSteps — шаг каскада:

Управление шаблонами рассылок

Шаблон рассылки — это сохранённая конфигурация: шаги, каналы, содержимое, условия успеха. Один и тот же шаблон можно запускать несколько раз.

Список шаблонов

Эндпоинт: GET /broadcast/templates

Query-параметры:

Пример:

curl --location 'https://web.multiapi.ru/api/v1/broadcast/templates?limit=2' \
  --header 'X-API-Key: <ваш-ключ>'

Создание шаблона

Эндпоинт: POST /broadcast/templates

Тело запроса:

Пример:

curl --location 'https://web.multiapi.ru/api/v1/broadcast/templates' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "name": "Летняя распродажа",
    "description": "Шаблон для продвижения летней коллекции",
    "extraRecipientList": [],
    "filterList": [],
    "tags": ["promo"],
    "contentType": 1,
    "content": {
      "flowSteps": [
        {
          "channelType": 1,
          "senderId": "sms_sender",
          "contentPattern": "Привет из шаблона",
          "deliveryCondition": "DELIVERY_SUCCESS",
          "timeout": 259200
        }
      ]
    }
  }'

Детали шаблона

Эндпоинт: GET /broadcast/templates/{id}

Пример:

curl --location 'https://web.multiapi.ru/api/v1/broadcast/templates/1670' \
  --header 'X-API-Key: <ваш-ключ>'

Обновление шаблона

Эндпоинт: PUT /broadcast/templates/{id}

Поддерживается частичное обновление: переданные поля обновляются, null игнорируются. Для смены contentType нужно передать полностью новый content.

Пример:

curl --location --request PUT 'https://web.multiapi.ru/api/v1/broadcast/templates/1670' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "name": "Летняя распродажа 2024",
    "description": "Обновлённое описание"
  }'

Удаление шаблона

Эндпоинт: DELETE /broadcast/templates/{id}

Удаление необратимо.

curl --location --request DELETE 'https://web.multiapi.ru/api/v1/broadcast/templates/1670' \
  --header 'X-API-Key: <ваш-ключ>'

Успешное удаление возвращает код 204 No Content.

Вебхук статусов рассылки

URL вебхука обязателен при запуске рассылки. Платформа отправляет на него статусы по мере выполнения.

Формат:

Коды ответов

Пример ответа с ошибкой:

{
  "execId": null,
  "key": null,
  "code": null,
  "message": "Phone number can`t be null or empty",
  "args": null
}

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

См. также

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

• Multi API: support@multiapi.ru