API-пайплайн: запустить виджет Cabi.Chat на своём хостинге со своей программой

Индекс: API-пайплайны — индекс

Цель: ваша собственная программа отвечает людям в комнатах виджета Cabi.Chat: скрипт, сервис поддержки или ваш собственный ИИ-ассистент, например Claude Code. Cabi.Chat выдаёт виджету токен, который работает как токен Telegram-бота; ИИ Cabi.Chat не отвечает. Что такое виджет и кто может до него дотянуться: Cabi.Chat Oracles — виджет Cabi.Chat

Шаги

1. Создать.

POST /v0/my/oracles
Idempotency-Key: widget-mine-1
{"kind": "cabi_widget", "hosting": "self", "title": "My assistant", "project": "<project nonce>"}
→ {"nonce": "470000000000000004", "card_type": "oracle", "kind": "cabi_widget",
   "status": "STOPPED", "token": "…", …}

• token: показывается только в этом ответе. Храните его в настройках своей программы, никогда — в карточке или агенде.
• agenda: по желанию. Задавайте её, только если ваша программа ещё и вызывает API Cabi.Chat от имени этой агенды, с токеном в Authorization: Bearer <token>: Cabi.Chat API — приложения
• Кто может с ним говорить: visibility, publicity, permissions, как у любого виджета; по умолчанию Private (только вы).
• topics_in_private: по умолчанию true: в личном чате человека с виджетом могут быть ветки (темы), как при «Threaded mode» в @BotFather. Изменить позже: PATCH (только владелец).

2. Направьте свою программу на Bot API Cabi.Chat с этим токеном. Каждый запрос идёт на https://api.cabi.chat/bot<token>/<method> — в той же форме, что у Telegram:

GET  https://api.cabi.chat/bot<token>/getMe
GET  https://api.cabi.chat/bot<token>/getUpdates?timeout=50
POST https://api.cabi.chat/bot<token>/sendMessage   {"chat_id": <chat id>, "text": "…"}

Получайте обновления длинным опросом или через вебхук, заданный setWebhook, и отвечайте обычными методами. Поддерживаемые методы: Spectral — плагины через эмулятор Telegram-бота

Файлы: getFile даёт file_path; скачивайте его с https://api.cabi.chat/file/bot<token>/<file_path>.

3. Общение. Каждый, кто открывает виджет, получает с ним комнату: личный чат с вашим виджетом, как в Telegram. Его сообщения приходят как обновления с chat.type private и chat.id, равным id пользователя этого человека; то, что ваша программа отправляет в этот чат, появляется в комнате.

• Id пользователей короткие и постоянные, в диапазоне, который ждут клиенты Telegram (52 бита); id пользователя — не nonce проекта человека. Чаты, открытые раньше, сохраняют свои id.
• Когда topics_in_private включён, getMe показывает has_topics_enabled и allows_users_to_create_topics, а ветки работают в личном чате как в Telegram: сообщение в ветке несёт message_thread_id; отправляйте с тем же message_thread_id, чтобы ответить в этой ветке.
• Групповая комната, в которую добавлен ваш виджет, — это supergroup с темами форума; ветки работают и там.

Как открыть комнату: API-пайплайн: настроить виджет Cabi.Chat, который ведёт ИИ Cabi.Chat, шаг 4.

Пример: Claude Code

Claude Code может говорить с вами через виджет Cabi.Chat: он работает на вашем компьютере под вашим собственным входом, а Cabi.Chat — только поверхность чата. Официальный плагин-канал Telegram для Claude Code говорит на Telegram Bot API, поэтому работает с любым Telegram-совместимым корнем Bot API, в том числе с https://api.cabi.chat. Настройка плагина, которая направляет его на другой корень Bot API, ещё ждёт выхода в самом плагине; когда она появится в вашей версии:

1. В Claude Code: /plugin install telegram@claude-plugins-official, затем /telegram:configure <токен виджета>.
2. Укажите в плагине корень Bot API https://api.cabi.chat.
3. Запустите Claude Code с каналом: claude --channels plugin:telegram@claude-plugins-official.
4. Откройте комнату виджета на Cabi.Chat и напишите в неё; привяжитесь командой /telegram:access pair <code> и закройте доступ командой /telegram:access policy allowlist, чтобы вашей сессией управляли только вы.

Ваша комната с виджетом — личный чат, поэтому привязка, команды и запросы разрешений работают так же, как с Telegram-ботом; когда topics_in_private включён, в ней можно вести отдельные ветки.

Держите виджет приватным, чтобы его комнату могли открыть только вы.

Правила

• hosting: "self" — только для cabi_widget; любой другой вид → 400 only a cabi widget can be self-hosted.
• Потеряли токен? POST /v0/my/oracles/{nonce}/regenerate-token → {"token": "…", "token_preview": "…"}, токен показывается один раз; прежний токен сразу перестаёт работать. Только владелец.
• Токен выпускается из веб-приложения или вашим собственным персональным токеном доступа, никогда — из подключённого приложения (403).
• За виджет на своём хостинге Cabi.Chat не берёт плату за ИИ; ИИ вашей программы — ваш собственный.
• DELETE /v0/my/oracles/{nonce} удаляет виджет; его токен перестаёт работать.

Поверхность API