Боты и интеграционный API
Бот — участник пространства с токеном; он пользуется тем же REST API и gateway, что и приложение, в пределах прав своих ролей.
Бот в Calab — это пользователь с флагом isBot. Он состоит в пространствах, получает роли, видит комнаты и доски по тем же правилам, что и человек, и ходит в тот же REST API и realtime-gateway, что и приложение. Отдельного «Bot API» с собственной моделью нет: бот делает то, что может человек, в пределах своих прав. Поэтому API ботов — это и есть интеграционный API Calab: всё, что нужно внешней системе, делается от имени бота.
Что умеет бот
| Задача | Как | Глава |
|---|---|---|
| Писать в комнаты и личные сообщения, отвечать, реагировать, закреплять | REST /api/rooms/{id}/messages, /api/messages/{id}/… | Сообщения, Личные сообщения |
| Получать сообщения и события в реальном времени | WebSocket /gateway или HTTPS-вебхук | Gateway, Вебхуки |
Отвечать на /команды и кнопки под сообщениями | регистрация команд, inlineKeyboard | Команды и кнопки |
| Вести доски: задачи, статусы, чек-листы, вехи, формы | REST /api/boards/…, /api/tasks/… | Доски и задачи, Формы |
| Назначать встречи и смотреть занятость | REST /api/workspaces/{id}/events, freebusy | Календарь |
| Заходить в голос, слушать и говорить | POST /api/rooms/{id}/join → LiveKit | Комнаты и голос |
| Управлять пространством: комнаты, роли, приглашения, бейджи | REST по правам ролей | Пространство и участники |
| Загружать файлы и стикеры, искать | REST | Файлы, Стикеры, Поиск |
| Получать уведомления о задачах человека | событие taskNotice | Уведомления о задачах |
Как это устроено
┌───────────────┐ REST https://app.example.com/api/… ┌──────────────┐
│ │ ──────────────────────────────────────▶ │ │
│ Ваш бот │ Gateway wss://…/gateway?v=1 │ Calab │
│ (любой язык) │ ◀─────────────────────────────────────▶ │ сервер │
│ │ Вебхук POST https://bot.example.com │ │
│ │ ◀────────────────────────────────────── │ │
└───────┬───────┘ └──────────────┘
│ голос: url + token из POST /api/rooms/{id}/join
▼
LiveKit (SFU) — бот обычный участник звонка- REST — команды: отправить, изменить, создать, прочитать. Заголовок
Authorization: Bearer <токен бота>. - Gateway — поток событий по WebSocket: сообщения, реакции, голос, задачи. Один сокет на токен.
- Вебхук — те же события сообщений и задач, но сервер сам присылает их POST-запросом на ваш HTTPS-адрес. Удобно для serverless; можно вместе с gateway.
- Голос идёт мимо нашего API: бот получает адрес и токен LiveKit и подключается любым клиентом LiveKit (Node, Python, Go).
Права — как у людей
Бот видит только то, что разрешают VIEW_ROOM и VIEW_BOARD; пишет — если есть SEND_MESSAGES; заходит в голос — с CONNECT. Закрытые комнаты и доски бот видит только через переопределение на самом объекте — личное или по роли. По умолчанию бот получает роль участника: читает и пишет в открытых комнатах, заходит в голос.
Бот с административными правами — администратор: токен с MANAGE_*, INVITE_* или VIEW_JOURNALS храните как пароль администратора. Сервер журналирует каждое административное действие бота вместе с его владельцем.
Чего бот не может никогда
Часть API закрыта для ботов независимо от ролей — на такие маршруты сервер отвечает 403 FORBIDDEN, reason: "BOT_NOT_ALLOWED":
- оплата и тарифы — всё про баланс, платежи, смену тарифа;
- identity — SSO, каталог, OAuth-клиенты и OAuth-провайдер, повторный вход;
- управление ботами — создание, токены, аватары других ботов (даже с
MANAGE_BOTS); - заметки, звонки один на один, push-уведомления;
- аккаунт человека: пароль, почта, сессии, статус, настройки уведомлений;
- создание, поиск и удаление пространств, вступление по приглашению;
- гостевые ссылки на комнаты, веб-приложения пространства, фоны камеры;
- голосование в согласовании задач, нажатие кнопок под сообщениями;
- Диск пространства (пока; см. Диск).
Полный список с решением для каждого маршрута — Маршруты ботов.
С чего начать
- Быстрый старт — создайте бота и отправьте первое сообщение.
- Токен и права — как хранить токен и выдать боту нужные права.
- SDK для Node.js — если пишете на JavaScript/TypeScript; на других языках хватит HTTP и WebSocket.