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

Index: API pipelines — index

Goal: stay in charge of the conversations your oracles hold in Telegram: stop or resume the oracle for one person, clear a request for a human, give one conversation its own agenda, and ask the oracle to continue (or preview what it would say).

Who may do this: the owner of the room's oracle (as_oracle: true on the room). The personal agenda also needs w on the room, its oracle and, for a campaign conversation, the campaign.

Steps

1. Find the conversation.

GET /v0/my/rooms?limit=50&offset=0
→ {"rooms": [{"nonce": "470000000000000010", "card_type": "room",
              "talk": {"kind": "telegram_oracle", "listener": "enabled", "handoff": null, …},
              "as_oracle": true, "unread": 1, …}], "total": 120, "has_more": true}

Read it: GET /v0/my/rooms/{room}/talk?limit=50. {room} takes the nonce or a handle. Reading and answering in general: API pipeline: Read and answer your conversations

2. Listener off / on for this person.

POST /v0/my/rooms/470000000000000010/talk/listener
{"enabled": false}
→ {"listener": "disabled"}

Off: the oracle stops answering this person; their messages still arrive in the room and you can answer yourself: POST …/talk/send {"text": "…"} goes out through the oracle. The oracle may also switch the listener off itself (e.g. after spam or a clear «no»); turn it back on here.

3. Clear a handoff. The oracle sets talk.handoff when it asks for a person to take over. When you have handled it:

DELETE /v0/my/rooms/470000000000000010/talk/handoff
→ 204

4. Personal agenda for this conversation: it overrides the campaign's agenda for every later turn here; history is unchanged; the other person never sees it.

GET /v0/my/rooms/470000000000000010/talk/swag
→ {"room": "…", "source": "campaign", "effective": {"nonce": "…", "title": "Warm follow-up", "owned": true},
   "room_swag": null, "campaign_swag": {…}, "assignable": [{"nonce": "…", "title": "…", "owned": true}, …]}

PATCH /v0/my/rooms/470000000000000010/talk/swag
{"swag": "<agenda from assignable>"}       set
{"swag": null}                             clear: back to the campaign's agenda

source: room | campaign | default. An agenda you cannot open shows without its nonce. If you later lose access to the agenda you set, the campaign's agenda applies again.

5. Continue the conversation. The oracle takes a turn with your note; nothing you write is shown to the person.

POST /v0/my/rooms/470000000000000010/talk/trigger
{"note": "ask whether Friday works", "at": "20 minutes"}
→ {"id": "…", "at": "2026-10-15T21:10:00Z", "note": "ask whether Friday works"}

• at: "20 minutes", "2 hours", "tomorrow 10:00", "in 3 days" or an ISO time (UTC); default "1 minute".
• Preview first: {"note": "…", "draft": true} runs the turn now with every send held and answers {"draft": {"text": "…", "parts": ["…"]}, "done_reason": "…"}; nothing reaches the person. Send it yourself with …/talk/send, or edit it first.

Behind

• Continue and preview are AI runs; their cost shows in your AI spend: API pipeline: See your AI spend. Prices: link

Rules

• Listener, handoff, continue: only a Telegram oracle conversation, only its oracle's owner, and only after the person has written at least once; else 400 (only the oracle owner can …, no correspondent bound yet — wait for an inbound message).
• note: 1–500 characters; at in the past or unreadable → 400 with the accepted formats.
• Personal agenda: from your own session or PAT only; the agenda must be one you own or execute (400 otherwise); a campaign conversation you cannot edit → 403.

API surface