Team-Flow для разработчиков — вебхуки, боты, API

Вебхуки каналов

Вебхук — секретная ссылка, по которой внешняя система публикует сообщения в один текстовый канал. Создать: ПКМ по каналу → Настройки канала → Вебхуки (нужно право «Управлять вебхуками», у владельца сервера оно есть всегда). Ссылка выглядит так:

https://team-flow.online/api/webhooks/<id>/<секретный_токен>

Ссылка = пароль. Любой, у кого она есть, может писать в канал. Если ссылка утекла — нажмите «Новый URL» (старая перестанет работать) или удалите вебхук.

Отправка сообщения

POST/api/webhooks/<id>/<token>, тело — JSON (Content-Type: application/json) или форма с полем payload_json.

Поле	Тип	Описание
`content`	string ≤ 2000	Текст. Поддерживается жирный, курсив, `код`, \|\|спойлер\|\|, ссылки.
`username`	string ≤ 32	Имя отправителя вместо имени вебхука.
`avatar_url`	/uploads/… URL	Аватар отправителя — только картинка, загруженная в Team-Flow (внешние адреса игнорируются; по умолчанию — аватар вебхука).
`embeds`	массив ≤ 5	Карточки: `title`, `description`, `url`, `color` (число или "#rrggbb"), `fields[{name,value,inline}]`, `author{name,url}`, `footer{text}`, `image{url}`, `thumbnail{url}`, `timestamp` (ISO 8601).

Ответ: 204 No Content. С параметром ?wait=true — 200 и объект созданного сообщения. Сообщения помечаются тегом БОТ. GET на ту же ссылку возвращает информацию о вебхуке. Slack-совместимый формат ({"text": "…"}) тоже принимается, можно добавить /slack в конец ссылки.

curl -H "Content-Type: application/json" \
  -d '{"username":"Мониторинг","content":"Сервер **api-1** снова доступен ✅",
       "embeds":[{"title":"Uptime","description":"Простой: 3 мин","color":3066993,"url":"https://status.example.com"}]}' \
  https://team-flow.online/api/webhooks/<id>/<token>

GitHub

В репозитории: Settings → Webhooks → Add webhook. Payload URL — ссылка вебхука с /github на конце, Content type — application/json. Поддерживаются события push, pull_request, issues, issue_comment, release, star, fork, create/delete, workflow_run (остальные приходят кратким уведомлением). Ссылка без /github тоже работает — тип события определяется по заголовку X-GitHub-Event.

Боты

Бот — отдельная учётная запись сервера с токеном. Создать может владелец сервера (или администрация сайта): Настройки сервера → Боты → Создать бота. Токен показывается один раз; при утечке нажмите «Новый токен». Бот видит те текстовые каналы, которые может видеть и читать роль @everyone, и пишет только в них.

Токен передаётся в заголовке:

Authorization: Bot tfb.<id>.<секрет>

REST API

База: https://team-flow.online/api/v1. Все ответы — JSON. Ошибки: {"message": "…", "code": …} с HTTP-статусом 4xx.

Метод	Описание
GET`/users/@me`	Информация о боте и его сервере.
GET`/channels`	Текстовые каналы, доступные боту: `[{id, name, topic, type, nsfw}]`.
GET`/channels/:id/messages?limit=50&before=<id>`	Последние сообщения канала (до 100).
POST`/channels/:id/messages`	Отправить: `{content, embeds, message_reference: {message_id}}`.
PATCH`/channels/:id/messages/:mid`	Изменить своё сообщение: `{content, embeds}`.
DELETE`/channels/:id/messages/:mid`	Удалить своё сообщение → `204`.

Объект сообщения:

{ "id": "1759671234567-3fa9c1", "channel_id": "c1a2b3", "content": "Привет!",
  "timestamp": "2026-10-05T12:00:00.000Z", "ts": 1759665600000, "edited": false,
  "author": { "id": "bot:9f0c2e1a7b3d", "name": "Страж", "bot": true }, "embeds": [] }

curl -H "Authorization: Bot $TOKEN" -H "Content-Type: application/json" \
  -d '{"content":"Сборка #42 прошла ✅"}' \
  https://team-flow.online/api/v1/channels/<channel_id>/messages

Шлюз событий (WebSocket)

Подключитесь к wss://team-flow.online/ (тот же адрес, что использует сайт) и первым сообщением отправьте:

{"type": "bot-identify", "payload": {"token": "tfb.<id>.<секрет>"}}

Ответ bot-ready содержит бота и доступные каналы. Дальше приходят события:

{"type": "bot-event", "payload": {"t": "MESSAGE_CREATE", "d": { …объект сообщения… }}}
{"type": "bot-event", "payload": {"t": "MESSAGE_UPDATE", "d": { … }}}
{"type": "bot-event", "payload": {"t": "MESSAGE_DELETE", "d": {"id": "…", "channel_id": "…"}}}

Раз в 30 секунд отправляйте {"type":"ping"} — сервер ответит pong. Отвечать на сообщения нужно через REST API. Ошибка авторизации приходит как bot-error, после чего соединение закрывается. Одновременно — не больше 3 подключений на бота.

Минимальный бот на Node.js 22 (без зависимостей):

const TOKEN = process.env.TF_BOT_TOKEN;
const API = 'https://team-flow.online/api/v1';
const ws = new WebSocket('wss://team-flow.online/');
ws.onopen = () => ws.send(JSON.stringify({ type: 'bot-identify', payload: { token: TOKEN } }));
setInterval(() => ws.readyState === 1 && ws.send('{"type":"ping"}'), 30000);
ws.onmessage = async (ev) => {
  const { type, payload } = JSON.parse(ev.data);
  if (type !== 'bot-event' || payload.t !== 'MESSAGE_CREATE') return;
  const m = payload.d;
  if (m.author.bot || m.content.trim() !== '!пинг') return;
  await fetch(`${API}/channels/${m.channel_id}/messages`, {
    method: 'POST',
    headers: { Authorization: 'Bot ' + TOKEN, 'Content-Type': 'application/json' },
    body: JSON.stringify({ content: 'Понг! 🏓', message_reference: { message_id: m.id } })
  });
};

Аватарки и картинки в embeds принимаются только из загрузок Team-Flow (/uploads/…), внешние адреса картинок игнорируются.

Лимиты

Что	Лимит
Вебхук	5 запросов / 2 с и 30 / мин на вебхук; 60 / мин с одного IP. Тело ≤ 128 КБ, ≤ 5 embeds.
REST API	30 запросов / 10 с на бота. При превышении — `429` с `retry_after` (секунды) и заголовком `Retry-After`.
Количество	до 10 вебхуков на канал, 50 на сервер; до 10 ботов на сервер.

Встроенный «Модератор»

Если на сервере включена модерация, сообщения вебхуков и ботов проверяются теми же правилами, что и сообщения людей (реклама и инвайт-ссылки, запрещённые слова, ссылки, спам). Заблокированное сообщение не публикуется: ответ 400 с {"code": 200000, "message": "…причина…"}. Владелец сервера может добавить вебхук или бота в доверенные (Настройки сервера → Модерация) — тогда проверка не применяется. Личные сообщения модератор не проверяет.

Вопросы и баги — кнопка «Сообщить о баге» на сайте.

Вопросы по API и интеграциям: support@team-flow.online. — Администрация Team-Flow