API pipeline: Set up a Cabi.Chat widget that Cabi.Chat's AI runs

Index: API pipelines — index

Goal: a Cabi.Chat widget answers people in its Cabi.Chat rooms under your agenda. Cabi.Chat runs it; no server and no token of yours. What a widget is and who can reach it: Cabi.Chat Oracles — Cabi.Chat widget

Steps

1. Have an agenda with the widget's instructions: API pipeline: Write an agenda for your oracles

2. Create.

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" is the default and may be left out.
• agenda: required; an agenda you own or may execute.
• visibility, publicity, permissions: who may talk to it. Private by default (only you); Unlisted and Public need permissions, Public also publicity (Ecosystem = signed-in users, Everyone = also visitors who are not signed in). Give read only. Change later with PATCH /v0/my/oracles/{nonce} (owner only).
• topics_in_private: true by default: a person's chat with the widget can hold threads (topics), like «Threaded mode» in @BotFather; false keeps it one plain thread. Change it later with PATCH (owner only).
• The answer carries no token: Cabi.Chat keeps the widget's token and uses it itself.

3. Start.

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

4. A person opens a conversation with it, signed in. They speak as their first project, so they need at least one project:

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

The room is the person's own private chat with the widget, with threads when topics_in_private is on. The same call returns the existing room when there is one. Then they write with POST /v0/my/rooms/{ident}/talk/send {"text": "…"}, and the widget answers in the room. Reading and answering rooms: API pipeline: Read and answer your conversations

5. Follow along. Every room of your widget is in GET /v0/my/rooms. You can post in it yourself: as your own project when the person on the other side is one of your projects, otherwise as the widget: API pipeline: Supervise conversations your oracles hold: turn the listener off/on, clear a handoff, set a room's agenda, ask the oracle to continue

Rules

• A widget the caller cannot read answers 404 on step 4, the same as one that does not exist. Rooms follow the widget: while someone cannot read it, its rooms leave their list and every room call answers 404 for them; they come back when the access does.
• No agenda → 400 a platform-hosted oracle needs an agenda.
• Unlisted and Public need project: a card is never more visible than its project.
• Running needs a Pro project or your one free oracle slot; a second free one → 400 that names the oracle holding the slot.
• Create needs Idempotency-Key; a repeat with the same key is refused, not replayed. A widget is created from the web app or with your own personal access token, not from an app you connected (403).
• Each answer is an AI run paid from the agenda owner's balance; when it cannot pay, the widget does not answer: API pipeline: See your AI spend
• POST /v0/my/oracles/{nonce}/regenerate-token (owner only) gives the widget a new token: the answer carries only token_preview, Cabi.Chat keeps the token, the previous one stops working.
• DELETE /v0/my/oracles/{nonce} stops the widget and removes its token.

API surface