API-пайплайн: управлять разговорами ваших оракулов — выключать и включать слушателя, закрывать хендофф, задавать агенду комнаты, просить оракула продолжить

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

Цель: держать под контролем разговоры, которые ваши оракулы ведут в Telegram: остановить или возобновить оракула для одного человека, закрыть запрос на живого человека, дать одному разговору свою агенду и попросить оракула продолжить (или посмотреть, что он скажет).

Кто может это делать: владелец оракула комнаты (as_oracle: true на комнате). Для личной агенды нужен ещё w на комнату, её оракула и, для разговора из кампании, на кампанию.

Шаги

1. Найдите разговор.

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}

Читать: GET /v0/my/rooms/{room}/talk?limit=50. {room} принимает nonce или хэндл. Чтение и ответы в целом: API-пайплайн: читать разговоры и отвечать в них

2. Слушатель выкл / вкл для этого человека.

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

Выключен: оракул перестаёт отвечать этому человеку; его сообщения по-прежнему приходят в комнату, и вы можете ответить сами: POST …/talk/send {"text": "…"} уходит через оракула. Оракул может и сам выключить слушателя (например, после спама или ясного «нет»); включите его обратно здесь.

3. Закрыть хендофф. Оракул ставит talk.handoff, когда просит, чтобы разговор подхватил человек. Когда вы с этим разобрались:

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

4. Личная агенда для этого разговора: она заменяет агенду кампании на все следующие ходы здесь; история не меняется; собеседник её никогда не видит.

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

{"swag": "<агенда из assignable>"} задаёт её; {"swag": null} очищает и возвращает агенду кампании. source: room | campaign | default. Агенда, которую вы не можете открыть, показывается без nonce. Если позже вы потеряете доступ к заданной агенде, снова действует агенда кампании.

5. Продолжить разговор. Оракул делает ход с вашей заметкой; ничего из написанного вами человеку не показывается.

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" или время в ISO (UTC); по умолчанию "1 minute".
• Сначала посмотреть: {"note": "…", "draft": true} выполняет ход сейчас, задерживая все отправки, и отвечает {"draft": {"text": "…", "parts": ["…"]}, "done_reason": "…"}; до человека ничего не доходит. Отправьте его сами через …/talk/send или сначала отредактируйте.

За кадром

• Продолжение и просмотр — запуски ИИ; их стоимость видна в ваших расходах на ИИ: API-пайплайн: ваши расходы на ИИ. Цены: link

Правила

• Слушатель, хендофф, продолжение: только разговор Telegram-оракула, только владелец его оракула и только после того, как человек написал хотя бы раз; иначе 400 (only the oracle owner can …, no correspondent bound yet — wait for an inbound message).
• note: 1–500 символов; at в прошлом или нечитаемый → 400 со списком допустимых форматов.
• Личная агенда: только из вашей собственной сессии или PAT; агенда должна быть вашей или доступной вам на выполнение (иначе 400); разговор из кампании, которую вы не можете редактировать → 403.

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