---
title: Broadcasts API — рассылки и шаблоны
description: Broadcasts API Multi API — запуск рассылок, управление шаблонами рассылок, параметры запроса, вебхук статусов
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.



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

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

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

## Что такое Broadcasts API

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

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

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

## Эндпоинты

| Метод | Эндпоинт | Для чего |
|---|---|---|
| POST | `/broadcast/broadcasts` | Запуск рассылки |
| GET | `/broadcast/templates` | Список шаблонов рассылок |
| POST | `/broadcast/templates` | Создать шаблон рассылки |
| GET | `/broadcast/templates/{id}` | Детали шаблона |
| PUT | `/broadcast/templates/{id}` | Обновить шаблон |
| DELETE | `/broadcast/templates/{id}` | Удалить шаблон |

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

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

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

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

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| webhook | string | Да | URL вебхука для статусов рассылки |
| templateId | integer | Да* | ID существующего шаблона рассылки |
| payload | object | Да* | Inline-содержимое рассылки |
| recipientsList | array | Нет | Список получателей. Если не указан — используются фильтры шаблона |
| launchTime | string | Нет | Время запуска (ISO 8601). Если не указано — рассылка стартует сразу после модерации |
| name | string | Нет | Название рассылки. Если не указано — сгенерируется автоматически |
| description | string | Нет | Описание рассылки |

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

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

```bash
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. Отложенная рассылка с указанием получателей:**

```bash
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-содержимое):**

```bash
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": "Привет! Наша летняя распродажа начинается сегодня!"
          }
        ]
      }
    }
  }'
```

<Note>
`recipientsList` принимает один или несколько объектов с полем `phoneNumber`. Если `phoneNumber` не указан — API вернёт код `400`.
</Note>

## Формат payload

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

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| contentType | integer | Да | Тип содержимого: `1` — Fallback, `2` — Chat Bot, `3` — RCS Capability Check |
| contentSettings | object | Да | Настройки содержимого |
| rcsCheck | boolean | Нет | Проверять поддержку RCS перед отправкой |

**Объект `contentSettings`:**

| Поле | Тип | Что означает |
|---|---|---|
| flowSteps | array | Список шагов рассылки (каскад) |
| rcsCapabilityCheck | object | Настройки проверки RCS |
| scenario | object | Настройки сценария (для Chat Bot) |

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

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| channelType | integer | Да | Номер канала |
| senderId | string | Нет | Имя отправителя |
| contentPattern | object | Нет | Содержимое сообщения |
| deliveryCondition | string | Нет | Условие успеха: `SUBMIT_SUCCESS`, `DELIVERY_SUCCESS`, `DISPLAY_SUCCESS` |
| timeout | integer | Нет | Секунды до перехода на следующий шаг |
| order | integer | Нет | Порядок шага |

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

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

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

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

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

| Параметр | Тип | По умолчанию | Что указать |
|---|---|---|---|
| limit | integer | 10 | Максимум записей |
| offset | integer | 0 | Смещение |

**Пример:**

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

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

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

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

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| name | string | Да | Название шаблона |
| contentType | integer | Да | `1` — Fallback, `2` — Chat Bot, `3` — RCS Capability Check |
| content | object | Да | Конфигурация содержимого (`flowSteps`, `scenario`, `rcsCapabilityCheck`) |
| description | string | Нет | Описание |
| tags | array | Нет | Теги получателей |
| filterList | array | Нет | ID фильтров получателей |
| extraRecipientList | array | Нет | Точные номера телефонов получателей |
| rcsCheck | boolean | Нет | Проверять поддержку RCS перед отправкой |

**Пример:**

```bash
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}`

**Пример:**

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

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

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

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

**Пример:**

```bash
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}`

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

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

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

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

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

**Формат:**

| Поле | Тип | Что означает |
|---|---|---|
| status | string | Обновлённый статус рассылки |
| webhook | string | URL вебхука |
| broadcastId | integer | ID рассылки |
| message | string | Описание ошибки (если есть) |

## Коды ответов

| Код | Что означает |
|---|---|
| 200 OK | Успешно |
| 204 No Content | Успешно, тело пустое (для удаления) |
| 400 | Ошибка параметров запроса |
| 401 | Неверный или отсутствующий API-ключ |
| 403 | Нет прав |
| 404 | Шаблон не найден |
| 500 | Внутренняя ошибка сервера |

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

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

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

<Accordion title="400 Bad Request: Phone number can't be null">
**Причина:** в `recipientsList` есть объект без поля `phoneNumber`.

**Решение:** убедитесь, что в каждом объекте указан `phoneNumber`.
</Accordion>

<Accordion title="404 Not Found: Templates not found">
**Причина:** `templateId` не существует или не принадлежит вашей компании.

**Решение:** проверьте ID в списке шаблонов (`GET /broadcast/templates`).
</Accordion>

<Accordion title="401 Unauthorized">
**Причина:** заголовок `X-API-Key` не передан или ключ неверный.

**Решение:** проверьте заголовок. Подробнее — [Ошибка 401](/06-reference/03-troubleshooting/ts-mapi-401).
</Accordion>

<Accordion title="403 Forbidden">
**Причина:** у ключа нет scope `broadcasts`.

**Решение:** откройте ключ в разделе **API Подключения** и добавьте нужный scope.
</Accordion>

<Accordion title="Рассылка запущена, но не доставляется">
**Причина:** возможны разные причины — от настроек шаблона до статусов на стороне провайдера.

**Решение:** проверьте статусы рассылки через вебхук, указанный при запуске.
</Accordion>

## См. также

<Columns cols={2}>
  <Card title="OMNI API — отправка сообщений" icon="paper-plane" href="/03-multiapi/02-api/mapi-103-omni-api">
    Эндпоинты `/messages`, `/omnimessages`
  </Card>
  <Card title="Форматы payload по каналам" icon="code" href="/03-multiapi/02-api/mapi-104-omni-payload">
    JSON-примеры для каждого канала
  </Card>
  <Card title="Вебхуки" icon="link" href="/06-reference/01-api/api-webhooks">
    Статусы сообщений и рассылок
  </Card>
  <Card title="Подключение к API" icon="plug" href="/03-multiapi/02-api/mapi-102-api-connection">
    Аутентификация и базовый URL
  </Card>
</Columns>

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

- Multi API: support@multiapi.ru