API pipeline: Connect your Telegram bot as an oracle

Index: API pipelines — index

Goal: your own Telegram bot (made with @BotFather) answers people under an agenda you choose. Cabi.Chat hosts it: no server of yours is needed, and its conversations land in your inbox.

Steps

1. Create.

POST /v0/my/oracles
Idempotency-Key: oracle-shopbot-1
{"kind": "telegram_bot", "title": "Shop bot", "bot_token": "123456789:AAE…",
 "agenda": "<agenda nonce>", "project": "<project nonce>"}
→ {"nonce": "470000000000000002", "card_type": "oracle", "kind": "telegram_bot", "status": "STOPPED", …}

• bot_token: exactly as @BotFather gives it (<id>:<secret>). It is stored as a key and never shown again; to change it, delete the oracle and create it again.
• agenda: required; what the bot answers under (an agenda you own or may execute): API pipeline: Write an agenda for your oracles

2. Start.

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

3. Talk. People who open your bot in Telegram and write to it get answers under the agenda. Each person is one room: GET /v0/my/rooms. Supervise them: 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

4. Stop or delete. POST …/stop → {"success": true, "status": "STOPPED"}; DELETE /v0/my/oracles/{nonce} stops the bot and removes its stored token.

Behind

• While the bot runs, Cabi.Chat receives its messages and answers them; when it is stopped, it does not answer.
• A bot can only answer people who wrote to it first (a Telegram rule).
• Each answer is an AI run; its cost shows in your AI spend: API pipeline: See your AI spend. Prices: link

Rules

• Running needs a Pro project (you own it or hold x on it) or your one free oracle slot. A second free one → 400 your free oracle slot is used by … — stop it, or make this oracle's project Pro.
• No agenda → 400 a platform-hosted oracle needs an agenda; a malformed token → 400 bot_token must look like <id>:<secret>.
• Create needs Idempotency-Key; a repeat with the same key is refused, not replayed.
• start / stop need w on the oracle (404 otherwise).
• PATCH /v0/my/oracles/{nonce} changes title, agenda, project.

API surface