Документация Tribly → Боты и Bot API

Боты и Bot API

Бот — это автоматическая учётная запись, которая пишет и читает сообщения через программный интерфейс (Bot API). На ботах делают оповещения, дежурных помощников, приём заявок и связки с внешними сервисами.

Системные боты

Бот	Назначение
`botmother`	«Фабрика ботов»: создаёт ботов, выдаёт токены, показывает справку по API
`botai`	ИИ-ассистент в переписке (см. отдельную страницу)
`bothr`	HR-опросы (см. «HR-модуль»)
`botkanban`	Оповещает об изменениях в задачах канбан-досок тех, кого они касаются
`botsupport`	Техническая поддержка, тикеты, список изменений

Системные боты идут вне счёта и работают постоянно.

Создание бота

Ботов заводит системный бот botmother. Напишите ему и следуйте подсказкам. Команды:

Команда	Что делает
`/newbot <имя>`	Создать нового бота
`/mybots`	Показать список ваших ботов
`/token <имя>`	Показать токен бота
`/newtoken <имя>`	Выпустить новый токен; прежний перестаёт действовать
`/seticon <имя>`	Задать боту аватар: бот попросит прислать картинку следующим сообщением
`/seticon <имя> <ссылка>`	То же, но сразу ссылкой на картинку этого сервера
`/setname <имя> <отображаемое имя>`	Сменить отображаемое имя бота (см. ниже)
`/setcommands <имя> <список>`	Задать меню команд бота (см. ниже)
`/deletebot <имя>`	Удалить бота
`/api`	Справка по Bot API с примерами кода
`/help`	Список команд

Меню команд в чате с ботом отдаёт GET /api/v1/channels/:id/bot-commands — по нему клиент рисует список после «/».

Набор задаётся у botmother одной командой:

/setcommands mybot start - Начать работу | help - Справка | report - Отчёт за день

Команды перечисляются через |: имя, дефис, описание. Имя — латиница, цифры и подчёркивание, до 32 символов. Набор заменяется целиком, поэтому чтобы убрать команду, пришлите список без неё. До 20 команд на бота.

/setcommands mybot без списка показывает текущее меню, /setcommands mybot - очищает его.

Нажатие команды в меню отправляет боту обычное сообщение — разбирает его сам бот.

Токен — 64-символьный ключ, он же пароль бота. Если токен утёк, выпустите новый командой /newtoken <имя> — прежний перестаёт действовать сразу.

Один человек заводит до 20 ботов; лицензия может поднять этот предел.

Отображаемое имя и @имя бота

В чатах бота подписывает отображаемое имя, в профиле под ним стоит @имя. Отображаемое имя меняют:

создатель бота с правом «Управление ботами» — командой /setname mybot Отчёты у botmother или кнопкой «Изменить имя» (карандаш рядом с именем) в профиле бота;
владелец системы — той же кнопкой в профиле любого бота, в том числе системного.

Имя — до 64 символов, одной строкой. /setname mybot - сбрасывает его, и бот снова подписан @именем.

@имя задаётся при создании бота и закреплено за ним навсегда, в том числе после удаления бота.

Bot API

Каждый запрос бот подписывает своим токеном в заголовке Authorization: Bearer <токен_бота>.

Метод	Путь	Действие
GET	`/api/v1/bot/me`	Профиль бота
GET	`/api/v1/bot/channels`	Каналы и темы, где бот состоит, и их id
POST	`/api/v1/bot/send`	Отправить сообщение
PUT	`/api/v1/bot/messages/:message_id`	Изменить своё сообщение
GET	`/api/v1/bot/updates`	Забрать новые сообщения (опрос с курсором)
POST	`/api/v1/bot/read/:channel_id/:message_id`	Отметить прочитанным (двигает курсор `updates`)
DELETE	`/api/v1/bot/messages/:message_id`	Удалить сообщение — если бот админ этого канала
POST	`/api/v1/bot/slack/:channel_id`	Slack-совместимый входящий вебхук (см. «Интеграции и вебхуки»)

Бот пишет и читает в тех каналах, где состоит участником. Добавьте его в нужный канал вручную — после этого отправка заработает. Список каналов и тем бота (вместе с их id для отправки) отдаёт GET /api/v1/bot/channels.

Получение сообщений ботом

Бот забирает новые сообщения опросом: периодически вызывает GET /api/v1/bot/updates. Ответ приходит сразу, поэтому темп опроса выбирает сам бот (обычно раз в секунду-две).

В выдачу попадают сообщения всех каналов и тем, где бот состоит участником, кроме его собственных. За один запрос отдаётся не больше 100 сообщений на канал.

Курсор двигает сам бот. У каждого канала свой указатель прочитанного, и updates отдаёт всё, что идёт после него: пока бот не подтвердил приём, те же сообщения придут снова. Подтверждение — POST /api/v1/bot/read/<channel_id>/<message_id> с id последнего обработанного.

Порядок работы: получить пачку → обработать → подтвердить последний id → повторить.

Сообщения остаются обычной перепиской канала: они живут в истории по правилам хранения канала. updates — это курсор по истории канала. Когда новых сообщений нет, updates приходит пустым списком ([]).

Кнопки под сообщениями

Бот может прислать сообщение с кнопками (POST /api/v1/messages/inline) и обработать нажатие (POST /api/v1/messages/:id/callback) — так делают меню, подтверждения и быстрые опросы.

Возможности бота в группе

Бот читает сообщения каналов, где он состоит, и пишет в них. Этого хватает для оповещений, дежурных помощников и приёма заявок.

Бот-модератор. Если владелец канала назначит бота админом канала (сведения канала → участники → сделать админом), бот получает право удалять любые сообщения этого канала — метод DELETE /api/v1/bot/messages/<id>. Так делают автоматическую чистку: бот видит сообщение в updates, разбирает его своей логикой и снимает спам, вредоносные ссылки или нарушение правил. Удаляется всё вместе с вложениями и из поиска, у всех сразу — как при удалении человеком.

Права считаются по каналу: бот-модератор работает в той группе, где его назначили админом; в остальных он остаётся обычным участником. У сообщения в теме админство берётся у родительского канала.

Состав участников ведут люди: приглашает владелец канала или его админ.

Формат сообщения бота

Разметка. content рендерится как Markdown: **жирный**, *курсив*, код в обратных кавычках, блоки кода в тройных обратных кавычках, списки, таблицы, цитаты > и ссылки [текст](адрес). Перенос строки — обычный \n в JSON.

Цветная полоса. Необязательное поле color красит полосу слева у сообщения — так поток раскладывают по категориям: авария, предупреждение, успех. Принимаются #RRGGBB и слова good/warning/danger/info (и green/yellow/red/blue). Нераспознанное значение оставляет сообщение без полосы.

Слово	Цвет	Для чего обычно
`danger`	красный	авария, упавшая сборка, инцидент
`warning`	жёлтый	предупреждение, порог на грани
`good`	зелёный	восстановление, успешный деплой
`info`	синий	нейтральное уведомление

Переводы. Необязательное поле translations — карта «код языка → текст»: {"en": "...", "pt-br": "..."}. Приложенные переводы уезжают вместе с сообщением, и каждый читатель сразу видит вариант на языке своего интерфейса; читатель, чьего языка в карте нет, читает оригинал и переводит его средствами своего сервера. Так новостной канал публикует один пост на любом числе языков. Коды языков — строчные, по ISO, при необходимости с регионом или письмом: en, fil, pt-br, zh-hans. Один перевод — до 20 000 знаков, вся карта — до миллиона. Правка сообщения снимает старые переводы; переводы новой версии прикладываются тем же полем в PUT.

Пример: авария с разметкой и красной полосой.

{
  "channel_id": 42,
  "color": "danger",
  "content": "**db-1 недоступен**\n\n| Проверка | Значение |\n|---|---|\n| Порт 5432 | закрыт |\n| Пинг | 3 потери из 3 |\n\nsystemctl status postgresql → inactive (dead)\n\n[Открыть дашборд](https://grafana.example.com/d/db)"
}

ИИ-контекст: реакция ассистента

У POST /api/v1/bot/send есть необязательное поле ai_context — служебная подсказка для ИИ. Если владелец канала включил «ИИ Интеграцию» (настройки канала → «ИИ советник»), то на сообщение бота с непустым ai_context отреагирует личный ИИ-секретарь: разберёт ситуацию по инструкциям из подключённых вики-папок, при необходимости выполнит действия от лица владельца канала (задача на доске, сообщение в канал, привлечение людей) и прикрепит отчёт к сообщению бота блоком «ИИ интеграция».

Пример:

{
  "channel_id": 42,
  "color": "danger",
  "content": "**Error:** превышено время ожидания при связи с БД (db-1)",
  "ai_context": "Ошибка при связи с БД. Сервер db-1, доступ по SSH порт 22. Действуй по регламенту «Инциденты БД» из вики."
}

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

Под сообщением с ai_context появляется плашка «Вызов ИИ» — она разворачивается и показывает переданный текст. Плашка и отчёт видны сотрудникам канала. Настройка — на странице «Личный ИИ-секретарь».

Частота запросов

Запросы к Bot API ограничены по частоте: если бот обращается слишком часто, сервер просит подождать и подсказывает, через сколько повторить. Порог задаёт администратор; для обычных ботов он незаметен.

Смежные страницы: «Интеграции и вебхуки», «Мини-приложения».