Рассылки

Методы для управления рассылками: создание, редактирование, запуск, остановка, просмотр статуса и статистики доставки. Это те же действия, что доступны в личном кабинете в разделе «Рассылки», но через API — удобно, если вы создаёте и запускаете рассылки автоматически из своей системы (CRM, внутренний сервис и т.д.).

Методы рассылок доступны только на тарифе Premium.

Как это работает вкратце

Вы создаёте черновик рассылки — метод create. Можно указать только тип сообщения, а можно сразу передать текст и аудиторию.
Пока рассылка не запущена, она в статусе «черновик» — её можно сколько угодно раз менять через save.
Если получателей нужно задать собственным списком (а не выбрать по условиям) — проще всего указать chat_ids прямо в аудитории через тип сегмента list (см. ниже), без отдельного запроса. Метод upload-segment нужен только для очень больших списков, которые не помещаются в одно тело запроса — он позволяет загрузить список по частям несколькими вызовами; возвращаемый segment_id (тип custom) работает только для той рассылки, в которую список загружен, использовать его в другой рассылке нельзя.
Когда всё готово — запускаете рассылку через activate. Она встаёт в очередь на отправку.
Следить за статусом и статистикой доставки можно через get и list.
Уже запущенную рассылку можно остановить через cancel.

Как оформить текст сообщения (жирный, курсив, ссылки, эмодзи) — см. инструкцию по форматированию.

Авторизация

Если ваш API-ключ привязан к одному боту (обычный ключ из раздела «Мои боты» — см. Авторизацию) — ничего дополнительно указывать не нужно, все методы применяются к этому боту.

Если вы используете ключ из раздела «API-ключи», выданный сразу на несколько ботов или на все ваши боты, в каждом запросе нужно явно указать, какого бота он касается — заголовком Resource-Key либо полем (для POST) или параметром (для GET) resource_key. Значение — публичный ключ бота: часть до двоеточия в API-ключе бота, который вы видите в разделе «Мои боты» рядом с иконкой ключа (формат ключ_бота:api_key).

Формат ответа

Успешный ответ:

{ "ok": true, "data": { ... } }

Ответ с ошибкой:

{ "ok": false, "error": "...", "error_code": 400 }

Объект рассылки

Рассылка (task) — это то, что возвращают методы create, save, get, activate, cancel, и каждый элемент в list.

Поле

Тип

Описание

id

int

ID рассылки

status

int

Статус — см. таблицу ниже

name

string

Название (для вашего удобства, получателям не показывается)

type

string

Тип сообщения — sendMessage, sendPhoto и т.д., см. раздел «Содержимое сообщения» ниже

segmentations

object

Аудитория — см. раздел «Аудитория рассылки» ниже

message

object

Текст и медиа сообщения

settings

object

Настройки отправки — см. раздел «Настройки отправки» ниже

date_send

string|null

Когда запланирован запуск

date_finish

string|null

Когда рассылка завершилась или была остановлена

count_recipients

int

Сколько всего получателей у рассылки

count_delivered

int

Сколько сообщений доставлено

count_not_delivered

int

Сколько сообщений не доставлено (например, пользователь заблокировал бота)

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

Код

Значение

0

Черновик — можно редактировать

1

Запланирована, ждёт обработки

2

В процессе отправки

3

Завершена

4

Остановлена

5

Ошибка

6, 7, 8

Промежуточные технические статусы — рассылка готовится к отправке системой

Редактировать (save) можно только рассылку в статусе черновик (0). Для остальных статусов save вернёт текущую рассылку без изменений — то есть правки молча не применятся.

Аудитория рассылки

Поле segmentations определяет, кому будет отправлена рассылка:

{
  "include": [ { "type": "all", "config": {} } ],
  "exclude": [ { "type": "filter", "config": { "user_conditions": [...] } } ]
}

include и exclude — списки сегментов одного формата { "type": ..., "config": ... }. Итоговая аудитория — это объединение всех сегментов из include, из которого вычитается объединение всех сегментов из exclude.

Если хотя бы один сегмент в include имеет type: "all", остальные сегменты include не учитываются — берутся все пользователи бота.

Доступные типы сегментов:

type

config

Описание

all

{}

Все пользователи бота

list

{ "chat_ids": [...] }

Готовый список получателей прямо в запросе — без отдельной загрузки. Подходит для одноразового списка; работает и в exclude

custom

{ "segment_id": ... }

Список получателей, загруженный заранее через метод upload-segment (см. ниже) или через дашборд. Сегмент жёстко привязан к той рассылке, в которую был загружен — в другой рассылке его указать нельзя

channel

{ "chat_ids": [...] }

Конкретные пользователи, чаты, группы или каналы по chat_id (для групп и каналов chat_id — отрицательное число). По смыслу то же самое, что list

from_task

{ "task_id": ... }

Получатели другой вашей рассылки

filter

см. ниже

Аудитория по условиям — поля пользователя и/или совершённые события

Сегмент `type: "filter"`

{
  "user_conditions": ["and", ["=", "users.language_code", "ru"], ["=", "users.is_premium", 1]],
  "event_filters": [
    "and",
    ["performed_event", { "event_id": 42, "negation": false, "period_days": 30 }]
  ]
}

Ключ

Описание

user_conditions

Условие на поля пользователя

event_filters

Условие на совершённые пользователем события

Формат условия (user_conditions) — вложенный массив [оператор, ...аргументы]:

Логика: ["and", условие1, условие2, ...], ["or", ...], ["not", условие]
Сравнение: ["=", "поле", значение], ["!=", ...], [">", ...], ["<", ...], [">=", ...], ["<=", ...]
Текст: ["like", "поле", "%подстрока%"], ["not like", ...]
Список значений: ["in", "поле", [значение1, значение2, ...]], ["not in", ...]
Диапазон: ["between", "поле", от, до], ["not between", ...]
Проверка на пустое значение: ["is", "поле", null]

Доступные поля: users.user_id, users.full_name, users.username, users.first_name, users.last_name, users.date_create, users.date_last_active, users.gender, users.is_bot, users.user_status, users.is_premium, users.language_code, users.timezone, а также ваши кастомные поля — users.custom_fields.<имя> / users.addition_fields.<имя>.

Пример: пользователи с русским языком интерфейса, у которых либо была активность после 1 июня, либо стоит кастомный флаг vip:

["and",
  ["=", "users.language_code", "ru"],
  ["or",
    [">", "users.date_last_active", "2026-06-01"],
    ["=", "users.custom_fields.vip", "1"]
  ]
]

Формат event_filters — дерево такого же вида, но листья — это performed_event:

Группа: ["and"|"or", узел1, узел2, ...]
Лист: ["performed_event", { "event_id": ..., "negation": ..., "period_days": ... }]

Поле листа

Описание

event_id

ID события (необязателен — если не указан, проверяется любое событие)

negation

false — «совершил событие», true — «не совершал»

period_days

За сколько последних дней проверять (0 — за всё время)

conditions

Дополнительные условия на свойства события, в том же формате, что user_conditions, но по полям events.*

Содержимое сообщения

Поле message зависит от type рассылки. Все текстовые поля поддерживают переменные {{user.first_name}} и условия {% raw %}{% if %}{% endraw %} — они подставляются индивидуально для каждого получателя в момент отправки.

type

Поля message

sendMessage

text (обязательно), parse_mode (html или MarkdownV2), reply_markup (инлайн-кнопки Telegram), disable_notification, protect_content, pin_message (закрепить сообщение после отправки)

sendPhoto

photo (ссылка на изображение или file_id), caption, parse_mode, reply_markup, pin_message

sendVideo

video, caption, parse_mode, reply_markup, pin_message

sendDocument

document, caption, parse_mode

sendAnimation

animation, caption, parse_mode

sendAudio

audio, caption

sendVoice

voice, caption

sendMediaGroup

media — массив { "type": "photo"|"video", "media": "<ссылка>", "caption"?: "..." } (альбом из нескольких фото/видео)

Пример для sendMessage:

{
  "text": "Привет, {{user.first_name}}! У нас акция.",
  "parse_mode": "html",
  "reply_markup": {
    "inline_keyboard": [[{ "text": "Перейти", "url": "https://example.com" }]]
  }
}

reply_markup — обычная структура инлайн-клавиатуры Telegram Bot API.

Настройки отправки

Поле settings — необязательное, все ключи имеют значения по умолчанию:

{
  "intervalCap": 10,
  "rateLimitOnError": { "stop": true, "extraDelay": 0 }
}

Ключ

Тип

По умолчанию

Описание

intervalCap

int

10

Сколько сообщений отправлять в секунду

rateLimitOnError.stop

bool

true

Останавливать рассылку, если Telegram ответил ограничением по скорости (429)

rateLimitOnError.extraDelay

int (мс)

0

Дополнительная задержка между отправками при срабатывании ограничения

Методы

POST /v1/broadcast/create

Создаёт новый черновик рассылки.

Можно ограничиться только type (пустой черновик — как при создании рассылки в дашборде), а можно сразу передать содержимое и аудиторию и/или запустить рассылку — без отдельных вызовов save/activate.

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

type

string

да

Тип сообщения — sendMessage, sendPhoto и т.д.

name

string

нет

Название рассылки

segmentations

object

нет

Аудитория

message

object

нет

Текст и медиа сообщения

settings

object

нет

Настройки отправки

date_send

string

нет

Дата и время запуска, формат YYYY-MM-DD HH:MM:SS

activate

bool

нет

true — запустить рассылку сразу после создания

Пример запроса

POST /v1/broadcast/create
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "type": "sendMessage",
  "name": "Анонс акции",
  "segmentations": { "include": [{ "type": "all", "config": {} }] },
  "message": { "text": "У нас акция, {{user.first_name}}!" }
}

Ответ

{ "ok": true, "data": { "task": { "id": 4821, "status": 0, "...": "..." } } }

POST /v1/broadcast/save

Обновляет рассылку — работает только для черновика (статус 0).

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

id

int

да

ID рассылки

name

string

нет

Название

segmentations

object

нет

Аудитория

message

object

нет

Текст и медиа сообщения

settings

object

нет

Настройки отправки

date_send

string

нет

Дата и время запуска, формат YYYY-MM-DD HH:MM:SS

Пример запроса

POST /v1/broadcast/save
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "id": 4821,
  "message": { "text": "У нас акция, {{user.first_name}}! Успей забрать скидку." }
}

Ответ

{ "ok": true, "data": { "task": { "id": 4821, "status": 0, "...": "..." } } }

GET /v1/broadcast/get

Возвращает рассылку по ID — текущее содержимое, статус и статистику доставки.

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

id

int

да

ID рассылки

Пример запроса

GET /v1/broadcast/get?id=4821

Ответ

{ "ok": true, "data": { "task": { "id": 4821, "status": 3, "count_recipients": 1200, "count_delivered": 1180, "count_not_delivered": 20, "...": "..." } } }

GET /v1/broadcast/list

Возвращает список рассылок ресурса с фильтрами и сортировкой.

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

filters[status]

int

нет

Фильтр по статусу

filters[name]

string

нет

Фильтр по названию (частичное совпадение)

filters[date_create]

string

нет

Фильтр по дате создания

orders[<поле>]

asc|desc

нет

Сортировка по полю, например orders[date_create]=desc

limit

int

нет

Количество записей, по умолчанию 100, максимум 500

offset

int

нет

Смещение, по умолчанию 0

Пример запроса

GET /v1/broadcast/list?filters[status]=3&orders[date_create]=desc&limit=20

Ответ

{
  "ok": true,
  "data": {
    "tasks": [
      { "id": 4821, "status": 3, "name": "Анонс акции", "...": "..." }
    ],
    "count": 1
  }
}

POST /v1/broadcast/activate

Сохраняет переданные поля (как save) и запускает рассылку.

Если для вашего тарифа исчерпана квота на рассылки, запрос вернёт ошибку error: "mailing_not_allowed". Подробности о лимитах — на странице тарифов.

Параметры

Те же, что у метода save выше.

Пример запроса

POST /v1/broadcast/activate
Api-Key: YOUR_API_KEY
Content-Type: application/json

{ "id": 4821 }

Ответ

{ "ok": true, "data": { "task": { "id": 4821, "status": 1, "...": "..." } } }

POST /v1/broadcast/cancel

Останавливает рассылку. Если она уже запущена — переводит в статус «остановлена» (4) и помечает неотправленным получателям, что для них рассылка отменена (повторный запуск не отправит им сообщение). Если рассылка ещё не была подхвачена в обработку — просто возвращает её в черновик.

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

id

int

да

ID рассылки

Пример запроса

POST /v1/broadcast/cancel
Api-Key: YOUR_API_KEY
Content-Type: application/json

{ "id": 4821 }

Ответ

{ "ok": true, "data": { "task": { "id": 4821, "status": 4, "...": "..." } } }

POST /v1/broadcast/upload-segment

Загружает список получателей для конкретной рассылки (task_id) — список привязывается именно к ней и не может быть использован в других рассылках. Работает только для рассылки в статусе черновик (0). Получатели передаются как массив Telegram ID (для групп и каналов — отрицательные числа).

В большинстве случаев этот метод не нужен — передайте chat_ids прямо в segmentations через тип сегмента list: { "include": [{ "type": "list", "config": { "chat_ids": [...] } }] }. upload-segment пригождается только для очень больших списков, которые нужно загрузить несколькими запросами (по частям), указав затем несколько segment_id в include.

После загрузки используйте полученный segment_id в segmentations рассылки:

{ "include": [{ "type": "custom", "config": { "segment_id": 17 } }] }

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

task_id

int

да

ID рассылки, к которой привязывается список

chat_ids

array of int

да, непустой

Telegram ID получателей

Пример запроса

POST /v1/broadcast/upload-segment
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "task_id": 4821,
  "chat_ids": [123456789, 987654321, -1001670520580]
}

Ответ

{ "ok": true, "data": { "segment_id": 17, "count_list": 3, "duplicates": 0 } }

Поле

Описание

segment_id

ID загруженного списка — используйте в segmentations

count_list

Сколько получателей сохранено (после удаления дублей)

duplicates

Сколько повторов было удалено из переданного списка

Возможные ошибки

Код

Когда возникает

400

Не передан обязательный параметр, или параметр неверного формата

401

API-ключ не передан или недействителен

403

Метод недоступен на вашем тарифе (требуется Premium), либо ресурс недоступен этому ключу

404

Рассылка с указанным id не найдена

500

Внутренняя ошибка сервера — повторите запрос позже

Пример ошибки:

{ "ok": false, "error": { "errors": "Premium tariff required" }, "error_code": 403 }

ПредыдущаяРеферальная система

СледующаяАвтоматизации

Последнее обновление 2 месяца назад

Как это работает вкратце

Авторизация

Формат ответа

Объект рассылки

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

Аудитория рассылки

Сегмент type: "filter"

Содержимое сообщения

Настройки отправки

Методы

POST /v1/broadcast/create

Параметры

Пример запроса

Ответ

POST /v1/broadcast/save

Параметры

Пример запроса

Ответ

GET /v1/broadcast/get

Параметры

Пример запроса

Ответ

GET /v1/broadcast/list

Параметры

Пример запроса

Ответ

POST /v1/broadcast/activate

Параметры

Пример запроса

Ответ

POST /v1/broadcast/cancel

Параметры

Пример запроса

Ответ

POST /v1/broadcast/upload-segment

Параметры

Пример запроса

Ответ

Возможные ошибки

Сегмент `type: "filter"`