Что можно интегрировать
Три способа связать Calab с вашими системами — боты и интеграционный API, вход через Calab по OAuth 2 / OIDC, SSO и каталог AD.
Calab — голосовой мессенджер для команд: пространства, комнаты, звонки, доски задач, календарь. Всё, что видят люди в приложении, доступно программам через три открытых интерфейса. Эта документация — для разработчиков интеграций и администраторов пространств.
| Что нужно | Чем пользоваться | Раздел |
|---|---|---|
| Программа пишет в комнаты, отвечает на команды, ведёт задачи, заходит в голос | Бот и его REST API + gateway | Боты и интеграционный API |
| Ваш сервис пускает людей «через Calab» и узнаёт, кто они | OAuth 2 / OpenID Connect — Calab как провайдер | OAuth 2 / OIDC |
| Люди входят в Calab корпоративной учётной записью, состав команды — из AD | SSO по OIDC и каталог LDAPS | SSO и каталог |
Боты — интеграционный API
Бот в Calab — это обычный участник пространства с флагом «бот». Он ходит в тот же REST API и тот же realtime-gateway, что и приложение, и может ровно то, что разрешают его роли — как человек. Отдельного «урезанного» API нет: CRM, которая создаёт задачи на доске, мониторинг, который пишет алерты в комнату, голосовой ассистент в звонке — всё это боты.
- Быстрый старт — бот, токен и первое сообщение за пять минут.
- Токен и права — что бот может и чего не может никогда.
- Gateway и вебхуки — как получать события.
OAuth 2 / OIDC
Каждое пространство — отдельный OpenID-провайдер со своим issuer. Вы регистрируете клиента в настройках пространства, а ваше приложение получает по Authorization Code + PKCE подтверждённую личность участника: id, имя, почту. Подходит для внутренних порталов, CRM, вики — для всего, где нужен вход «как в Calab». Подробно — в разделе OAuth 2 / OIDC.
SSO и каталог
Администратор пространства подключает корпоративный OpenID Connect — Microsoft Entra ID, AD FS или любой совместимый провайдер — и решает, обязателен ли вход через него. Каталог LDAPS сверяет участников с группами Active Directory: уволенный сотрудник теряет доступ автоматически. Подробно — в разделе SSO и каталог.
Базовые адреса
В примерах используются условные адреса — подставьте свои.
| Адрес | Что там | Пример |
|---|---|---|
Адрес приложения (APP_HOST) | REST API (/api/…), gateway (/gateway), ссылки на задачи | https://app.example.com |
Публичный origin identity (IDENTITY_PUBLIC_ORIGIN) | OIDC-провайдер пространств (/oidc/workspaces/{id}/…), адреса возврата SSO | https://id.example.com |
На многих установках оба адреса совпадают: identity обслуживается тем же сервером, что и API. Узнать точные значения для своего сервера можно у его оператора; для облака Calab это адрес, по которому вы открываете веб-версию.
Версии
- REST не версионируется в пути: контракт только расширяется — новые поля добавляются, старые не меняют смысл. Неизвестные поля запроса сервер игнорирует, поэтому клиент должен так же спокойно пропускать незнакомые поля ответа.
- Gateway подключается с явной версией протокола:
wss://app.example.com/gateway?v=1. - Версия сервера —
GET /api/versionбез авторизации. Подробно — Версия API.
Где взять токены
| Токен | Где получить | Подробно |
|---|---|---|
Токен бота calab_bot_… | «Настройки пространства → Боты → Создать бота» — показывается один раз | Токен и права |
client_id / client_secret OAuth-клиента | Настройки пространства → OAuth | Регистрация клиента |
| Access / refresh-токены OAuth | Выдаёт token endpoint после согласия пользователя | Токены и сроки |
Все форматы собраны в справочнике токенов.
Лимиты
Боту доступно 30 запросов в секунду и 20 сообщений в минуту — этого хватает для интеграций, но не для рассылок. Полная таблица — Лимиты. Превышение даёт 429 с заголовком Retry-After.
Типы и контракт
Все тела запросов и ответов — сообщения protobuf в JSON (protojson): поля в lowerCamelCase, перечисления полным именем ("ROOM_TYPE_VOICE"), uint64 — строками, время — RFC 3339. Схемы лежат в открытом репозитории github.com/itrcz/calab в каталоге proto/; из них же генерируются типы для TypeScript и Go. Для Node.js есть готовый SDK.
Поддержка
Вопросы и ошибки — в issues репозитория github.com/itrcz/calab. Если вы нашли уязвимость, не публикуйте её в issue — напишите владельцам сервера напрямую.