Документация для разработчиков внешних проектов и сотрудников · 14 октября 2026 · Контракт licensed-multibot-v2, основа Telegram 1.3.2.
Лицензии можно назначить одного или нескольких Telegram-ботов. Для внешнего клиента botid — это реальный Telegram Bot ID, возвращаемый Telegram в getMe.result.id. Внутренний номер строки BiNuke, ID записи webhook и токен для выбора не используются.
| У лицензии | Поведение |
|---|---|
| Один выделенный бот | Во всех запросах к этому боту botid можно не передавать. Бот выбирается автоматически. |
| Два или более выделенных бота | Без botid API вернёт error: "bot_id_required" и availableBots. Повторите запрос с полем botid — реальным Telegram ID нужного бота. |
| Не назначены выделенные боты | Накопители и управление webhook запрещены (dedicated_bot_required). Режимы со стандартным ботом из старого API продолжают работать согласно политике лицензии. |
| Telegram запрещён | telegram_forbidden. Даже если в БД остались старые назначения, они не дают доступ. |
Никогда не передавайте внутренний ID BiNuke в botid. Не передавайте токен Telegram-бота при обычном чтении или отправке — он нужен только для TGAccountCreate. Ключ лицензии передавайте в POST, не в URL.
Адрес: https://api.binuke.info/api.php (либо свой адрес установленного BiNuke). Метод HTTP — POST, параметр формы json содержит JSON с mode и license. Ответы методов BiNuke — JSON UTF-8. В накопителях и списках ботов Telegram ID возвращаются строками; вложенный ответ самого Telegram (result и TGgetChat.chat) сохраняет типы полей Telegram API.
curl -X POST 'https://api.binuke.info/api.php' \
--data-urlencode 'json={"mode":"TGAccounts","license":"YOUR_LICENSE"}'
TGAccounts показывает разрешённые боты и их Telegram ID; вызов не требует botid. Метод полезен при запуске внешнего приложения и для построения выбора бота в интерфейсе.
Для TGSend используются независимые уровни адресации. Идентификатор проекта/подразделения не равен номеру темы Telegram.
| Поле | Чьё это ID | Откуда брать | Влияет на доставку? |
|---|---|---|---|
license | Лицензия внешнего проекта | Выдаётся администратором BiNuke | Проверяет права |
botid | Реальный ID Telegram-бота, например 7412345678 | Из TGAccounts.bots[].botId. Можно не указывать, когда выделен один бот. | Да — от имени какого бота отправлять |
to | ID Telegram-чата (личного, группы или супергруппы), например -1001234567890 | TGChats.items[].chatid либо заранее известный ID Telegram | Да — в какой чат отправлять |
topicid | ID темы внутри чата, например 357 | TGChatTopics.items[].topicid после выбора чата. В Telegram Bot API называется message_thread_id. | Да — в какую тему выбранного чата |
serviceid | Внутренний ID филиала, отдела, клиента или учётной записи в вашем проекте, например 42 | Определяет само внешнее приложение, не Telegram | Нет. Только учёт и последующая группировка исходящих по подразделениям |
Пример из интернет-магазина: serviceid=42 означает «филиал №42», но Telegram не знает о филиалах. Если филиал пишет в тему «Заказы» (topicid=357) группы to=-1001234567890, нужно передать оба значения в разных полях. Для небольшого сайта serviceid вообще не нужен.
Пример из сервиса бухгалтерских документов: serviceid=7821 может означать внутреннюю учётную запись зарегистрированного клиента сервиса. Это по-прежнему не Telegram-бот, не пользователь Telegram, не чат и не тема. Кому доставить уведомление, определяют botid, to и при необходимости topicid.
| mode | Параметры помимо mode и license | Назначение |
|---|---|---|
TGAccounts | — | Назначенные боты: bots[{botId,name}], count, botIdRequired, canCreate. Без секретов. |
TGConnectionStatus | botid? | Проверка getMe, текущий статус подключения, политики лицензии. |
TGChats | botid?, page?, limit? | Чаты выделенного бота из накопителя. |
TGChatInfo | botid?, chatid | Описание конкретного сохранённого чата. |
TGChatTopics | botid?, chatid, page?, limit? | Сохранённые темы выбранного чата (после проверки принадлежности чата боту). |
TGUsers | botid?, page?, limit? | Пользователи, которых накопитель видел через новые webhook с известным ботом. |
TGUserInfo | botid?, userid | Карточка пользователя из накопителя бота. |
TGSend | botid?, to, body?, filename?, fileBase64?, topicid?, serviceid? | Отправка текста или файла. topicid адресует тему Telegram; serviceid только классифицирует отправку внутри проекта. |
TGOutgoingRecent | botid?, page?, limit? | Исходящие сообщения этой лицензии, отправленные конкретным ботом. |
TGIncomingRecent | botid?, limit? | Последние входящие по указанному боту. Работает с большим старым журналом; не используйте частый опрос. |
TGList | botid? | Старый формат списка известных чатов. Для нового кода предпочтительнее TGChats. |
TGgetChat | botid?, chatid | Онлайн-запрос Telegram getChat от имени выделенного бота. |
TGWebhookStatus | botid? | Прочитать фактический статус webhook без изменения настройки. |
TGWebhookEnsure | botid? | Явно установить/обновить webhook для выбранного бота через действующий механизм прокси. |
TGAccountCreate | name, token | Подключить собственного бота, если лицензии разрешено создание. Другие назначения остаются. botid не нужен. |
TGApiInfo, TGApiHelp | — | Машинный контракт и эта HTML-страница, не требуют лицензии. |
TGProxyConfig | — | Действующий публичный контракт конфигурации webhook-прокси. |
Служебный TGBack принимает webhook Telegram; внешние проекты его не вызывают. Все методы с пометкой botid? требуют ID только при наличии нескольких выделенных ботов.
TGSend — универсальный внешний метод отправки. После проверки лицензии BiNuke выбирает Telegram-бота и вызывает один из трёх методов Telegram Bot API: sendMessage, sendPhoto или sendDocument. Исходящая запись сохраняется в binuketg; это журнал проекта, а не таблица Telegram-тем.
| Поле | Тип | Обязательно | Точное значение |
|---|---|---|---|
mode | строка | да | TGSend |
license | строка | да | Серийный ключ лицензии BiNuke |
botid | строка десятичных цифр | только если несколько ботов | Реальный Telegram Bot ID, не внутренний номер BiNuke |
to | строка | да | Telegram chat_id; один чат может содержать множество тем |
body | строка | для обычного текста | Текст сообщения; используется parse_mode=HTML; при отправке файла становится подписью (caption) |
topicid | положительное целое число либо строка с его цифрами | нет | ID темы в to. BiNuke передаёт его в Telegram как message_thread_id. Если не указан, параметр темы в Telegram не передаётся. |
serviceid | целое число | нет | Внутреннее подразделение вашего проекта. Приводится к int, по умолчанию 0. Сохраняется в binuketg.serviceid, не передаётся Telegram. |
filename | строка | для файла | Название прикрепляемого файла с расширением, например report.pdf или photo.jpg. |
fileBase64 | строка | для файла через JSON | Содержимое файла Base64, можно с префиксом data:...;base64,. С filename отправляется как фото для JPG/PNG, иначе как документ. |
Имена полей чувствительны к регистру: для внешнего JSON пишите строго topicid, serviceid и botid строчными буквами. Формы topicId, serviceId и botId в запросе не являются их эквивалентами. В ответах список ботов, напротив, использует поле botId — это отдельный публичный контракт ответа.
Особенно важно: поле message_thread_id — это имя аргумента самого Telegram Bot API. Во внешнем запросе к BiNuke используйте поле topicid. Поле serviceid никогда не подставляется в message_thread_id.
{"mode":"TGSend","license":"YOUR_LICENSE","to":"123456789","body":"Ваш заказ принят"}
Этот пример подходит лицензии с одним назначенным ботом. Нет ни темы, ни подразделения. Никакой botid или serviceid добавлять не нужно.
{"mode":"TGSend","license":"YOUR_LICENSE","to":"-1001234567890","topicid":"357","body":"Новая заявка в отдел продаж"}
Здесь to — ID самой группы, topicid — ID темы в этой группе. Нельзя использовать только topicid вместо to; также нельзя помещать номер темы в serviceid.
{"mode":"TGSend","license":"YOUR_LICENSE","botid":"7412345678","to":"-1001234567890","topicid":"357","serviceid":42,"body":"Филиал №42: поступил новый заказ"}
Бот выбирается полем botid; группа — to; тема — topicid; внутренний филиал — serviceid. Каждый параметр выполняет свою задачу.
{"mode":"TGSend","license":"YOUR_LICENSE","to":"123456789","serviceid":7821,"body":"Готов акт сверки за сентябрь"}
В этом примере serviceid=7821 — числовой ID аккаунта в сервисе документов. Сообщение отправляется в личный Telegram-чат и не имеет темы. Если аккаунты во внешнем приложении обозначены UUID или буквенно-цифровой строкой, их необходимо сопоставить с числовыми внутренними ID либо не передавать serviceid: текущий метод приводит его к целому числу.
{"mode":"TGSend","license":"YOUR_LICENSE","to":"-1001234567890","topicid":"357","serviceid":7821,"filename":"invoice-2026-10.pdf","fileBase64":"JVBERi0xLjQKLi4u","body":"Счёт за октябрь"}
Строка Base64 здесь сокращена исключительно для иллюстрации — её нельзя использовать как настоящий PDF. В реальном запросе подставьте полное Base64 содержимое файла. Для .jpg/.jpeg/.png код использует Telegram sendPhoto, для других расширений — sendDocument; topicid работает в обоих случаях.
curl -X POST 'https://api.binuke.info/api.php' \
--data-urlencode 'json={"mode":"TGSend","license":"YOUR_LICENSE","to":"-1001234567890","topicid":"357","body":"Тест в тему"}'
Важно для интегратора: код api.php получает JSON из POST-поля формы json, а не напрямую из raw body с Content-Type: application/json. Не рассчитывайте, что отправка только сырого JSON без формы сработает.
{"error":"","botId":"7412345678","result":{"ok":true,"result":{"message_id":123,"chat":{"id":-1001234567890},"message_thread_id":357}}}
Схематический пример: Telegram сам определяет возвращаемые поля result.result. Внешнее приложение должно проверять и error === "" (BiNuke), и result.ok === true (Telegram). Если тема не существует, бот не участник группы или у него нет прав, Telegram может вернуть result.ok:false с описанием — при этом error BiNuke может оставаться пустым.
{"error":"invalid_topicid"}
Ошибка invalid_topicid означает, что переданный topicid не является положительным целым числом. Ошибка предотвращает непреднамеренную отправку сообщения в общую ленту при неверном ID темы. Не передавайте ноль: для отправки без конкретной темы просто опустите поле.
TGAccounts, чтобы выбрать разрешённого бота (или используйте автоматический выбор при одном боте).TGChats для получения chatid группы.TGChatTopics с тем же chatid. Возьмите items[].topicid нужной темы.TGSend: to = chatid, topicid = items[].topicid, при необходимости botid и serviceid.result.ok в ответе и получение тестового сообщения в нужной теме.Список TGChatTopics — это локально сохранённые темы, а не универсальный онлайн-перечень всех тем Telegram. Если тема не попала в накопитель, отсутствие её в списке не доказывает, что её нет в Telegram: ID можно получить из события message.message_thread_id или через интерфейс администратора при создании темы. Отправка по известному topicid не требует предварительной записи темы в этот накопитель.
{"error":"","bots":[{"botId":"7412345678","name":"Новости"},{"botId":"7523456789","name":"Поддержка"}],"count":2,"botIdRequired":true,"canCreate":false}
{"error":"bot_id_required","availableBots":[{"botId":"7412345678","name":"Новости"},{"botId":"7523456789","name":"Поддержка"}]}
curl -X POST 'https://api.binuke.info/api.php' \
--data-urlencode 'json={"mode":"TGChats","license":"YOUR_LICENSE","botid":"7523456789","page":1,"limit":50}'
{"error":"","botId":"7523456789","items":[{"chatid":"-1001234567890","name":"Группа поддержки","added":1791912000}],"page":1,"limit":50,"hasMore":false}
{"mode":"TGUsers","license":"YOUR_LICENSE","page":1,"limit":50}
{"mode":"TGSend","license":"YOUR_LICENSE","botid":"7412345678","to":"123456789","body":"Привет!"}
Если выбрана чужая учётная запись, метод вернёт bot_not_allowed. В ответе нет внутренних ID BiNuke, токенов и конфигураций пересылок. Сервер всегда проверяет права лицензии до обращения к данным или Telegram.
{"mode":"TGAccounts","license":"YOUR_LICENSE"}
{"mode":"TGChats","license":"YOUR_LICENSE","page":1,"limit":50}
{"mode":"TGUsers","license":"YOUR_LICENSE","page":1,"limit":50}
Это три отдельных POST-запроса в поле json. Один назначенный бот выбирается автоматически.
Запрос:
{"mode":"TGChatTopics","license":"YOUR_LICENSE","chatid":"-1001234567890","page":1,"limit":50}
Типовой ответ:
{"error":"","chatid":"-1001234567890","items":[{"topicid":"357","name":"Заказы"},{"topicid":"401","name":"Бухгалтерия"}],"page":1,"limit":50,"hasMore":false}
chatid обозначает группу, topicid — тему. Если у лицензии больше одного бота, добавьте реальный botid к запросу TGChatTopics, как и к TGSend.
TGUsers и TGUserInfo читают новый накопитель binuketgusers, который пополняется только будущими входящими событиями с установленным ботом. Это не список всех подписчиков Telegram и не результат обхода миллиона старых webhook-записей. userid — Telegram ID пользователя; serviceid — ID аккаунта вашей системы, они не заменяют друг друга.
TGOutgoingRecent возвращает исходящие этой лицензии через выбранного бота, в том числе serviceid каждой записи. Он не является фильтром доставки и не предоставляет отдельного API «получить все сообщения филиала X»: для такого отчёта внешний проект может фильтровать полученные записи сам либо понадобится отдельный серверный метод. В текущем ответе TGOutgoingRecent нет отдельного поля topicid; подтверждение фактической темы можно получать из ответа отправки Telegram, если он её возвращает.
Бот должен иметь доступ к нужному чату; для публикации в теме Telegram должен разрешать отправку. Внешний botid нельзя подменить внутренним ID или произвольным ID другого бота. Если бот один — botid опускается; если несколько — API вернёт bot_id_required. Вся адресация to/topicid относится к выбранному боту.
TGAccounts, TGChats, TGChatInfo, TGChatTopics, TGUsers, TGUserInfo, TGOutgoingRecent и TGWebhookStatus только читают сведения. TGSend отправляет сообщение; TGWebhookEnsure меняет webhook; TGAccountCreate подключает бота — эти операции не следует вызывать ради проверки документации. TGIncomingRecent читает большой исторический журнал и не предназначен для частого опроса.
parse_mode=HTML), не Markdown. Передаваемый текст с символами < и & следует экранировать, если он не должен считаться HTML.serviceid — целое число, необязательное, по умолчанию 0. Для буквенно-цифровых бизнес-ID используйте сопоставление в собственном проекте.topicid — положительное целое, не внутренний ID отдела. Если не знаете ID темы, не подставляйте serviceid «для проверки».error, затем result.ok, затем нужные поля result.result.TGBack — внутренний webhook, а не публичная точка отправки сообщений. Его параметры не используются для отправки через TGSend.| error | Значение / действие |
|---|---|
bot_id_required | Разрешено несколько ботов; выберите botId из availableBots. |
bot_not_allowed | Переданный Telegram ID не разрешён этой лицензии. |
invalid_topicid | Неверный ID темы в TGSend; передайте положительное целое topicid или полностью опустите поле. |
invalid_botid | Поле botid не является корректной строкой десятичных цифр Telegram Bot ID. |
dedicated_bot_required | Выделенный бот не назначен; накопители и webhook не доступны стандартной лицензии. |
telegram_forbidden | Telegram полностью отключён в лицензии. |
bot_identity_unavailable | Для назначенного бота нельзя установить реальный Telegram ID из настроек; проверьте его токен/настройку в админке. |
bot_identity_conflict | Две внутренних записи одного и того же Telegram-бота назначены одной лицензии. |
personal_bot_creation_not_allowed | Создание собственного бота не разрешено администратором. |
run_telegram_install_first | Не выполнен установочный скрипт с таблицей дополнительных назначений. |
Привязки редактируются в административном разделе BiNukeTGLicenses: можно назначить несколько существующих ботов и отдельно включить «Разрешить TGAccountCreate». Старое поле binukelicens.tgaccid сохраняется для основного бота; дополнительные назначения хранятся в binuketglicensebots. Реальный Bot ID хранится в binuketgaccounts.telegramid (VARCHAR), а для старых записей определяется из числового префикса токена.
При самостоятельном подключении через TGAccountCreate вызывается Telegram getMe, проверяется идентичность токена, сохраняется назначение лицензии и запускается штатная установка webhook. Ранее назначенные боты не снимаются. Изменение выданных прав выполняет только администратор; лицензия не может назначить себе чужого бота по его ID.
Никакой обработки старых webhook: накопитель binuketgusers продолжает собирать только новые события с установленным ID бота. Исторический миллионный журнал не перечитывается и не пересвязывается. Для отправленных сообщений сохраняется ограничение по проекту и боту.
Контракт отправки в темы: topicid → Telegram message_thread_id. Контракт внутренних подразделений: serviceid → binuketg.serviceid. Не путать при поддержке внешних разработчиков.
Это спецификация релиза; после развёртывания необходимо провести проверку на рабочей MySQL и на тестовых ботах Telegram. Реальный вызов TGWebhookEnsure изменяет webhook. Ссылку на справку можно передавать разработчикам без лицензий и токенов.