Рассылки

Рассылка — сообщение, которое бот отправляет подписчикам: всем или выбранному сегменту.

Типичный порядок:

Создать рассылку — в ответе сразу будут id и message.id.
При необходимости поменять текст или тип.
Привязать сегмент (или оставить «всем»).
Запустить сразу или поставить время старта.

Адрес API: https://api.bot-t.com
Все запросы — POST, тело — JSON.

Как подключиться

Параметр	Обязательно	Что это
`bot_id`	да	ID вашего бота
токен бота или секретный ключ	да	`token` / `botToken` или `secretKey`

Content-Type: application/json

Успех:

{ "result": true, "data": { } }

Ошибка:

{ "result": false, "message": "текст ошибки" }

Всегда проверяйте result === true. Лимит: 120 запросов в минуту.

Время — в часовом поясе бота.

Одновременно может идти только одна рассылка. Тип сообщения API в рассылке использовать нельзя.

Содержимое сообщения рассылки настраивается теми же методами, что и свободное сообщение: после создания возьмите message.id и вызывайте /v1/bot/messagenew/..., клавиатуры, настройки и медиа.

Карта методов

Задача	Адрес
Список рассылок	`/v1/bot/mailing/mailing/index`
Карточка рассылки	`/v1/bot/mailing/mailing/view`
Создать	`/v1/bot/mailing/mailing/create`
Создать из готового сообщения	`/v1/bot/mailing/mailing/create-from-message`
Изменить текст	`/v1/bot/mailing/mailing/update-text`
Изменить тип	`/v1/bot/mailing/mailing/update-type`
Задать сегмент	`/v1/bot/mailing/mailing/set-group`
Задать время старта	`/v1/bot/mailing/mailing/set-time`
Запустить сразу	`/v1/bot/mailing/mailing/start`
Остановить	`/v1/bot/mailing/mailing/stop`

Текст, тип, кнопки, медиа, настройки, обратная связь, условие, случайное, очередь и оплата — через методы свободного сообщения и message.id (см. ниже).

Сегмент создаётся отдельно через /v1/bot/group/....

Что приходит в карточке

create, create-from-message, update-text, update-type и view возвращают одну и ту же карточку.

Нужные поля:

Поле	Что это
`id`	ID рассылки — его передаёте дальше как `id`
`message.id`	ID сообщения внутри рассылки
`message.text`	Текст или подпись
`message.type.type`	Числовой тип
`status.id`	Статус
`group`	Сегмент или пусто
`started_time`	Время старта, или `-` если ещё не задано

Статусы

`status.id`	Название	Что значит
`0`	Черновик	Создана, ещё не запущена
`1`	В очереди	Стоит время старта, ждёт своей минуты
`2`	В процессе	Сейчас отправляется
`3`	Завершена	Всех обработали
`4`	Ошибка	Остановилась с ошибкой

Типы сообщения

При создании и смене типа передавайте число. Набор тот же, что у свободного сообщения, кроме API (14).

`type`	Что отправится
`0`	Текст
`17`	Развёрнутое (Rich)
`1`	Картинка
`2`	Обратная связь
`4`	Видео
`5`	GIF
`3`	Файл
`6`	Стикер
`7`	Таймер
`8`	Видео-кружок
`9`	Голосовое
`16`	Аудио
`10`	Альбом (медиагруппа)
`11`	Условие
`12`	Случайное сообщение
`13`	Очередь
`15`	Оплата

Тип 14 (API) метод не примет — ни при создании, ни при смене типа, ни при копировании свободного сообщения.

После смены типа на картинку, видео, файл, стикер или альбом привяжите медиа методами свободного сообщения (message.id).

1. Создать рассылку

Адрес: /v1/bot/mailing/mailing/create

Можно сразу передать текст. Если text нет — будет «Текст рассылки».

{
  "bot_id": 1,
  "type": 0,
  "text": "Завтра открываем предзаказ."
}

В data придёт карточка. Запомните data.id.

Можно скопировать уже готовое свободное сообщение (не из сценария и не спецтип, тип не API):

Адрес: /v1/bot/mailing/mailing/create-from-message

{
  "bot_id": 1,
  "message_id": 55
}

Исходное сообщение не меняется — в рассылку попадает копия. В ответе тоже карточка.

Карточка уже созданной: /v1/bot/mailing/mailing/view

{
  "bot_id": 1,
  "id": 100
}

2. Обновить текст или тип

Оба метода принимают ID рассылки, не сообщения.

Текст

Адрес: /v1/bot/mailing/mailing/update-text

{
  "bot_id": 1,
  "id": 100,
  "text": "Привет! Сегодня скидка 20%."
}

В ответе — обновлённая карточка.

Для картинки, видео и файла это поле — подпись к медиа.

Тип

Адрес: /v1/bot/mailing/mailing/update-type

{
  "bot_id": 1,
  "id": 100,
  "type": 1
}

В ответе — обновлённая карточка. Если поставили картинку или другое медиа — после этого привяжите файл методами свободного сообщения.

3. Настроить сообщение как свободное

У рассылки внутри есть обычное сообщение. Его ID — data.message.id из карточки.

Дальше вызывайте те же методы, что для свободного сообщения. В теле передавайте bot_id и message_id (иногда поле называется id) — это ID сообщения, не рассылки.

Задача	Куда идти
Текст, заголовок, тип, цвет, следующее сообщение	`/v1/bot/messagenew/message/...`
Настройки (уведомления, защита контента, эффект)	`/v1/bot/message/settings/...`
Inline-кнопки	`/v1/bot/keyboard/inline-new/...`
Reply-кнопки	`/v1/bot/keyboard/reply-new/...`
Картинка	`/v1/bot/manager/photos/assign`
Видео, файл, GIF, голос, кружок, аудио	`/v1/bot/manager/videos/assign`, `files/assign`, `animations/assign`, `voice/assign`, `videonotes/assign`, `audio/assign`
Альбом	`/v1/bot/messagenew/media-group/...`
Обратная связь	`/v1/bot/messagenew/feedback/...`
Условие	`/v1/bot/messagenew/condition/...`
Случайное	`/v1/bot/messagenew/random/...`
Очередь	`/v1/bot/messagenew/queue/...`
Оплата	`/v1/bot/messagenew/payment/...`

Пример. Рассылка с картинкой:

Создать или сменить тип на 1.
Привязать файл к message.id:

POST /v1/bot/manager/photos/assign
{ "bot_id": 1, "id": 55, "link": "promo.jpg" }

id здесь — message.id из карточки рассылки.

Пример. Текст и кнопки:

POST /v1/bot/messagenew/message/update-text
{ "bot_id": 1, "message_id": 55, "text": "Сегодня скидка 20%." }

Дальше кнопки — /v1/bot/keyboard/inline-new/add-button-with-line с тем же message_id.

/v1/bot/mailing/mailing/update-text и update-type тоже работают: они принимают ID рассылки и правят то же внутреннее сообщение.

4. Задать сегмент

Адрес: /v1/bot/mailing/mailing/set-group

group_id — ID сегмента из /v1/bot/group/index, из ответа create-from-preset / create-with-users или из аналитики действий (/v1/common/link-track/create-segment, поле data.group_id).

Отправить только сегменту:

{
  "bot_id": 1,
  "id": 100,
  "group_id": 42
}

Отправить всем подписчикам — передайте пустой group_id или не передавайте его:

{
  "bot_id": 1,
  "id": 100,
  "group_id": null
}

Если сегмент не задан, рассылка идёт всем подходящим пользователям бота.

Сегмент нельзя задать, если рассылка привязана к конкретной копии бота: получатели тогда — пользователи этой копии.

Как собрать сегмент: /v1/bot/group/create-from-preset, /v1/bot/group/create-with-users или по действиям в боте — /v1/common/link-track/create-segment. Список сегментов — /v1/bot/group/index.

5. Время старта и запуск

Два разных сценария. Не смешивайте их.

Запустить сразу

Адрес: /v1/bot/mailing/mailing/start

{
  "bot_id": 1,
  "id": 100
}

Рассылка сразу переходит в статус «В процессе» и начинает отправку.

Если уже идёт другая рассылка, придёт ошибка:
Нельзя запустить больше одной рассылки!Из-за лимитов телеграм

Если получателей нет, рассылка завершится сразу.

Поставить на время

Адрес: /v1/bot/mailing/mailing/set-time

Формат: Y-m-d H:i в часовом поясе бота. Время в прошлом нельзя.

{
  "bot_id": 1,
  "id": 100,
  "time": "2026-09-17 10:30"
}

Рассылка встанет в очередь. Когда время наступит, её запустит система.
Отдельно вызывать start не нужно — start сбросит время на «сейчас» и начнёт отправку немедленно.

Пример целиком: текст сегменту завтра утром

Создать с текстом:

POST /v1/bot/mailing/mailing/create
{ "bot_id": 1, "type": 0, "text": "Завтра открываем предзаказ." }

Из ответа взять data.id.

Привязать сегмент:

POST /v1/bot/mailing/mailing/set-group
{ "bot_id": 1, "id": 100, "group_id": 42 }

Поставить время:

POST /v1/bot/mailing/mailing/set-time
{ "bot_id": 1, "id": 100, "time": "2026-09-17 10:00" }

Чтобы отправить сразу — вместо шага 3 вызовите /v1/bot/mailing/mailing/start.

Если текст нужно поменять позже:

POST /v1/bot/mailing/mailing/update-text
{ "bot_id": 1, "id": 100, "text": "Предзаказ переносим на пятницу." }