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

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

Цель: виджет Cabi.Chat отвечает людям в своих комнатах Cabi.Chat по вашей агенде. Его запускает Cabi.Chat; ни сервер, ни токен с вашей стороны не нужны. Что такое виджет и кто может до него дотянуться: Cabi.Chat Oracles — виджет Cabi.Chat

Шаги

1. Нужна агенда с инструкциями виджета: API-пайплайн: написать агенду для своих оракулов

2. Создать.

POST /v0/my/oracles
Idempotency-Key: widget-bakery-1
{"kind": "cabi_widget", "hosting": "platform", "title": "Bakery desk",
 "agenda": "<agenda nonce>", "project": "<project nonce>",
 "visibility": "Public", "publicity": "Ecosystem",
 "permissions": {"read": true, "write": false, "execute": false}}
→ {"nonce": "470000000000000003", "card_type": "oracle", "kind": "cabi_widget", "status": "STOPPED", …}

• hosting: "platform" — значение по умолчанию, его можно не передавать.
• agenda: обязательна; агенда, которой вы владеете или которую можете выполнять.
• visibility, publicity, permissions: кто может с ним говорить. По умолчанию Private (только вы); для Unlisted и Public нужен permissions, для Public ещё publicity (Ecosystem — вошедшие пользователи, Everyone — также невошедшие посетители). Давайте только read. Изменить позже: PATCH /v0/my/oracles/{nonce} (только владелец).
• topics_in_private: по умолчанию true: в чате человека с виджетом могут быть ветки (темы), как при «Threaded mode» в @BotFather; false оставляет одну ветку. Изменить позже: PATCH (только владелец).
• В ответе нет token: токен виджета хранит и использует сам Cabi.Chat.

3. Запустить.

POST /v0/my/oracles/470000000000000003/start
→ {"success": true, "status": "ACTIVE"}

4. Человек открывает разговор с ним, войдя в Cabi.Chat. Он говорит от имени своего первого проекта, поэтому нужен хотя бы один проект:

POST /v0/my/rooms/widget
{"widget": "470000000000000003"}
→ {"nonce": "470000000000000700", "card_type": "room", …}

Комната — это личный чат человека с виджетом, с ветками, когда topics_in_private включён. Тот же вызов возвращает существующую комнату, если она есть. Дальше он пишет через POST /v0/my/rooms/{ident}/talk/send {"text": "…"}, и виджет отвечает в комнате. Чтение и ответы в комнатах: API-пайплайн: читать разговоры и отвечать в них

5. Следите за разговорами. Все комнаты вашего виджета есть в GET /v0/my/rooms. Вы можете писать в них сами: от имени своего проекта, если собеседник — один из ваших проектов, иначе от имени виджета: API-пайплайн: управлять разговорами ваших оракулов — выключать и включать слушателя, закрывать хендофф, задавать агенду комнаты, просить оракула продолжить

Правила

• Виджет, который вызывающий не может читать, на шаге 4 отвечает 404 — так же, как несуществующий. Комнаты следуют за виджетом: пока человек не может читать виджет, его комнаты пропадают из списка, а любой вызов по ним отвечает ему 404; они возвращаются вместе с доступом.
• Без агенды → 400 a platform-hosted oracle needs an agenda.
• Для Unlisted и Public нужен project: карточка никогда не видна шире своего проекта.
• Для работы нужен Pro-проект или ваш единственный бесплатный слот оракула; второй бесплатный → 400 с именем оракула, который занимает слот.
• Создание требует Idempotency-Key; повтор с тем же ключом отклоняется, а не повторяется. Виджет создаётся из веб-приложения или вашим собственным персональным токеном доступа, а не из подключённого приложения (403).
• Каждый ответ — запуск ИИ с оплатой с баланса владельца агенды; если баланс не может оплатить, виджет не отвечает: API-пайплайн: ваши расходы на ИИ
• POST /v0/my/oracles/{nonce}/regenerate-token (только владелец) выпускает виджету новый токен: в ответе только token_preview, сам токен хранит Cabi.Chat, прежний перестаёт работать.
• DELETE /v0/my/oracles/{nonce} останавливает виджет и удаляет его токен.

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