Документация

Справочник методов API

Все методы одним списком: что делает, какие принимает параметры и какой уровень доступа нужен ключу. Список формируется из кода сервиса, поэтому не расходится с тем, что работает на самом деле.

Попробовать бесплатно Как подключиться

42 методов Один эндпоинт POST /api/v1 Машиночитаемая спека OpenAPI

Все вызовы — POST /api/v1 с заголовком Authorization: Bearer bb_…. Метод указывается полем method, бот — полем botId.

Ошибка самого метода приходит с кодом 200 — «не нашёл подписчика», «нет такой группы» и подобное различаются полем success или error в теле, а не HTTP-статусом. Это унаследовано от прежней версии API и сохранено намеренно: по нему уже работают чужие скрипты. До метода дело доходит не всегда: неверный или отозванный ключ — это 401, запрос не методом POST — 405, превышение частоты — 429. Клиент должен различать оба слоя: проверять HTTP-код и только потом читать тело.

Уровень доступа задаётся при выпуске ключа в разделе «API, MCP» панели. Машиночитаемое описание всех методов — /api/v1/openapi.json: его можно скормить генератору клиента или Swagger UI.

Подписчики и группы

AddUserToGroup изменение

Добавить подписчика в группу или убрать из неё.

Параметр	Тип	Описание
user*	integer	id подписчика
group*	integer	id группы
remove	boolean	true — убрать из группы

CreateGroup изменение

Создать группу подписчиков.

Параметр	Тип	Описание
name*	string	название группы
description	string
grouplist	integer	id папки сегментов; по умолчанию первая

DeleteGroup полный

Удалить группу вместе с членством. Подписчики остаются. Необратимо.

Параметр	Тип	Описание
id*	integer	id группы (GetGroups)

GetBotUsers чтение

Подписчики бота с признаками «закрыл чат» и «заблокирован».

Параметр	Тип	Описание
limit	integer	по умолчанию 1000, максимум 5000
offset	integer

GetGroupUsers чтение

Подписчики группы.

Параметр	Тип	Описание
group*	integer	id группы
limit	integer	по умолчанию 1000, максимум 5000
offset	integer

GetGroups чтение

Группы подписчиков (сегменты).

GetUserProfile чтение

Профиль подписчика: поиск по id, логину, телефону или email.

Параметр	Тип	Описание
user	integer	id подписчика
login	string	логин Telegram без @
phone	string
email	string

Сообщения и рассылки

CancelBroadcast изменение

Отменить запланированную рассылку. Ушедшую в отправку отменить нельзя.

Параметр	Тип	Описание
id*	integer	id рассылки (GetBroadcasts)

CreateBroadcast полный

Разовая рассылка подписчикам: сейчас или по расписанию. Тратит деньги и внимание аудитории.

Параметр	Тип	Описание
text	string	текст (HTML-разметка Telegram); обязателен, если нет mediaFileId и richmessage
richmessage	string	расширенное сообщение (ТОЛЬКО Telegram): HTML с заголовками, цитатами, таблицами, медиа и рядами кнопок; заменяет обычный текст
mediaFileId	integer	id файла в хранилище бота
groupId	integer	id группы; 0 или пусто — всем подписчикам
sendAt	string	'now' или 'YYYY-MM-DD HH:MM' по Москве
buttons	array	кнопки: {text, url} либо {text, categoryId}

GetBroadcasts чтение

Разовые рассылки бота со статусом (запланирована / отправляется / отправлена).

Параметр	Тип	Описание
limit	integer	по умолчанию 200, максимум 200
offset	integer

SendMessage полный

Отправить сообщение конкретным подписчикам или группе. Списывает средства.

Параметр	Тип	Описание
users	array	до 1000 id подписчиков
group	integer	id группы — альтернатива users
message	string	текст сообщения
category	integer	id рубрики: вместо текста запустить сценарий

Переменные

GetVariables чтение

Справочник переменных бота (id, ключ, лимит длины, тип значения).

SetUserVariable изменение

Записать значение переменной подписчику. Если у переменной задан тип (число, дата, телефон, почта, да/нет), значение проверяется и приводится к единому виду — телефон, например, к +7…

Параметр	Тип	Описание
user*	integer	id подписчика
variable*	integer	id типа переменной (GetVariables)
value*	string	значение; проверяется по типу переменной и обрезается по её strlimit

Балансы

GetBalanceTypes чтение

Типы внутренних балансов бота и курсы обмена.

SetBalanceTypeExchangeRate изменение

Изменить курс обмена типа баланса.

Параметр	Тип	Описание
balancetype*	integer	id типа (GetBalanceTypes)
exchangerate*	number	новый курс

SetUserBalance полный

Изменить внутренний баланс подписчика. Движение денег — операция необратимая.

Параметр	Тип	Описание
user*	integer	id подписчика
balancetype*	integer	id типа баланса
amount*	number	сумма: со знаком — изменение, иначе установка
comment	string	комментарий в историю операций

Оплата

CreatePaymentSystem полный

Создать способ оплаты бота. Ключи, без которых платёж не пройдёт, обязательны сразу. На MAX и ВКонтакте внешних шлюзов нет — там допустим только тип manual.

Параметр	Тип	Описание
name*	string	название способа оплаты (видит только владелец)
type*	string	manual (ручной перевод с подтверждением) \| token (платёжный токен от @BotFather) \| stars (Telegram Stars) \| cryptobot \| yookassa \| cloudpayments \| tinkoff
balancetype	integer	id внутреннего баланса, в котором считается сумма (GetBalanceTypes)
paymenttoken	string	секрет: платёжный токен бота (token) либо api-key приложения @CryptoBot (cryptobot)
cryptobotcurrency	string	код криптовалюты счёта @CryptoBot (USDT, TON…) — обязателен для cryptobot
paymentshop	string	секрет: shopId (ЮKassa) \| Public ID (CloudPayments) \| Terminal Key (Т-Банк)
paymentsecret	string	секрет: секретный ключ \| API Secret \| пароль терминала
invoicerfswitch	boolean	передавать данные чека по 54-ФЗ
invoicedatatype	string	откуда брать данные чека: sendphone \| sendphonevar \| sendemailvar \| sendphoneemailvar \| userinputphone \| userinputemail \| userinputphoneemail
invoiceemailvar	integer	id переменной с email для чека (GetVariables)
invoicephonevar	integer	id переменной с телефоном для чека

DeletePaymentSystem полный

Удалить способ оплаты. Действия «Оплата», ссылавшиеся на него, останутся с висячей ссылкой и уведут подписчика по маршруту ошибки — их число вернётся в actionsAffected. Необратимо.

Параметр	Тип	Описание
id*	integer	id способа оплаты (GetPaymentSystems)

GetPaymentSettings чтение

Денежные настройки бота: реферальная программа (выплата пригласившему за подтверждённый платёж) и уведомления владельца об оплатах.

GetPaymentSystems чтение

Способы оплаты бота: тип, баланс, настройки чека 54-ФЗ и признак готовности (ready/missing). Токены и ключи эквайринга не возвращаются — только признак «задано» в secrets.

SetPaymentSettings полный

Изменить денежные настройки бота (частично). Реферальная выплата начисляется пригласившему в момент подтверждённого платежа приглашённого и тратит баланс бота на каждой оплате.

Параметр	Тип	Описание
paymentrefswitch	boolean	включить реферальную программу
paymentrefpercentswitch	boolean	выплата процентом от суммы оплаты (иначе фиксированная сумма)
paymentrefpercent	number	процент выплаты: больше 0 и не больше 100
paymentrefamount	number	фиксированная выплата: больше нуля
paymentrefbalancetype	integer	id баланса начисления (GetBalanceTypes); обязателен при включённой программе
paymentrefmessage	string	сообщение пригласившему при выплате; пусто — не отправлять
notifyfinance	boolean	уведомлять владельца об оплатах, ждущих его решения

UpdatePaymentSystem полный

Изменить способ оплаты (частично: переданные поля обновляются, остальные сохраняются). Смена реквизитов перенаправляет оплаты клиентов на другой счёт.

Параметр	Тип	Описание
id*	integer	id способа оплаты (GetPaymentSystems)
name	string
type	string
balancetype	integer
paymenttoken	string
cryptobotcurrency	string
paymentshop	string
paymentsecret	string
invoicerfswitch	boolean
invoicedatatype	string
invoiceemailvar	integer
invoicephonevar	integer

Каналы и ссылки

CreateChannelPost полный

Пост в канал или группу бота: черновик, по расписанию или сразу. Опубликованное сразу видят все подписчики канала.

Параметр	Тип	Описание
channelId	integer	id канала (GetChannels)
text	string	текст поста (HTML-разметка Telegram), до 4000 символов; обязателен даже при richmessage — он превью и запасной вариант
richmessage	string	расширенное сообщение (ТОЛЬКО Telegram): HTML с таблицами, цитатами, файлами и рядами кнопок
mode	string	draft (по умолчанию), scheduled (нужен sendAt) или now
sendAt	string	'YYYY-MM-DD HH:MM' в местном времени канала
buttons	array	кнопки {text, url}; в постах канала только https-ссылки

CreateInviteLink изменение

Создать инвайт-ссылку канала.

Параметр	Тип	Описание
channel*	integer	id канала
name	string	название ссылки (видно только вам)
expire_date	string	срок действия, YYYY-MM-DD
member_limit	integer	лимит переходов
join_request	boolean	вступление по заявке
advercost	string	стоимость размещения (для отчёта по рекламе)
description	string	заметка

DeleteChannelPost полный

Удалить пост из плана публикаций. Уже опубликованное сообщение остаётся в канале — его убирают в самом мессенджере.

Параметр	Тип	Описание
channelId	integer	id канала (GetChannels)
id	integer	id поста (GetChannelPosts)

DeleteInviteLink полный

Отозвать инвайт-ссылку. Необратимо.

Параметр	Тип	Описание
channel*	integer	id канала
link*	string	сама ссылка

EditInviteLink изменение

Изменить инвайт-ссылку.

Параметр	Тип	Описание
channel*	integer	id канала
link*	string	сама ссылка (GetInviteLinks)
name	string
expire_date	string
member_limit	integer
join_request	boolean
advercost	string
description	string

GetChannelPosts чтение

Посты канала: черновики, запланированные и опубликованные, свежие сверху.

Параметр	Тип	Описание
channelId	integer	id канала (GetChannels)
limit	integer	по умолчанию 200, максимум 200
offset	integer

GetChannels чтение

Каналы и группы, к которым подключён бот.

GetInviteLinks чтение

Инвайт-ссылки канала со статистикой переходов.

Параметр	Тип	Описание
channel*	integer	id канала (GetChannels)

События и структура

GetAccess чтение

Заявки на доступ с даты.

Параметр	Тип	Описание
date*	string	с какого момента
user	integer
limit	integer
offset	integer

GetCategories чтение

Структура бота: списки рубрик и рубрики внутри них.

GetSignals чтение

Сигналы (события сценариев) с даты.

Параметр	Тип	Описание
date*	string	с какого момента: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS'
user	integer	только по одному подписчику
limit	integer
offset	integer

GetStorage чтение

Файлы и тексты, присланные подписчиками, с даты.

Параметр	Тип	Описание
date*	string	с какого момента
user	integer
limit	integer
offset	integer

SetAccess изменение

Одобрить или отклонить заявку на доступ.

Параметр	Тип	Описание
accessid*	integer	id заявки (GetAccess)
status*	string	allow \| deny

Бронирование

GetBooking чтение

Одна бронь по id.

Параметр	Тип	Описание
booking*	integer	id брони

GetBookingList чтение

Брони объекта на ближайшие дни.

Параметр	Тип	Описание
object*	integer	id объекта
days	integer	горизонт в днях: по умолчанию 14, максимум 90

GetBookingLots чтение

Свободные слоты объекта по услугам.

Параметр	Тип	Описание
object*	integer	id объекта (GetBookingObjects)
services	array	id услуг
days	integer	горизонт в днях
date	string	конкретный день, YYYY-MM-DD

GetBookingObjects чтение

Объекты бронирования (готовые к записи).

GetBookingServices чтение

Услуги бронирования: длительность и цена.

GetBookingStatusList чтение

Справочник статусов брони.

SetBookingStatus изменение

Изменить статус брони.

Параметр	Тип	Описание
booking*	integer	id брони
status*	string	ключ статуса (GetBookingStatusList)

Звёздочкой отмечены обязательные параметры. Поле botId обязательно во всех методах и здесь не повторяется.

Зачислим 200 рублей для тестов при регистрации

Нужен ключ доступа?

Ключи выпускаются в разделе «API, MCP» панели: выберите уровень доступа — чтение, изменение или полный — и скопируйте ключ.

Попробовать бесплатно → Стартовый обучающий курс