Pipeline de API: supervisar las conversaciones de tus oráculos: desactivar o activar el oyente, cerrar un handoff, fijar la agenda de una sala, pedir al oráculo que continúe

Índice: Pipelines de API — índice

Objetivo: mantener el control de las conversaciones que tus oráculos llevan en Telegram: parar o reanudar el oráculo para una persona, cerrar una petición de atención humana, dar a una conversación su propia agenda y pedir al oráculo que continúe (o ver antes lo que diría).

Quién puede hacerlo: el dueño del oráculo de la sala (as_oracle: true en la sala). La agenda personal requiere además w sobre la sala, su oráculo y, en una conversación de campaña, la campaña.

Pasos

1. Encuentra la conversación.

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}

Léela: GET /v0/my/rooms/{room}/talk?limit=50. {room} acepta el nonce o un handle. Leer y responder en general: Pipeline de API: leer y responder tus conversaciones

2. Oyente desactivado / activado para esta persona.

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

Desactivado: el oráculo deja de responder a esta persona; sus mensajes siguen llegando a la sala y puedes responder tú: POST …/talk/send {"text": "…"} sale a través del oráculo. El oráculo también puede desactivar el oyente por sí mismo (p. ej. tras spam o un «no» claro); vuelve a activarlo aquí.

3. Cerrar un handoff. El oráculo pone talk.handoff cuando pide que una persona tome el relevo. Cuando lo hayas atendido:

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

4. Agenda personal para esta conversación: sustituye la agenda de la campaña en todos los turnos siguientes de aquí; el historial no cambia; la otra persona nunca la ve.

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": "<agenda de assignable>"} la fija; {"swag": null} la quita y vuelve a la agenda de la campaña. source: room | campaign | default. Una agenda que no puedes abrir aparece sin su nonce. Si más tarde pierdes el acceso a la agenda que fijaste, vuelve a aplicarse la de la campaña.

5. Continuar la conversación. El oráculo hace un turno con tu nota; nada de lo que escribes se le muestra a la persona.

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"}

En segundo plano

Reglas

Superficie de la API

Endpoint Para qué FE IA / oráculo
GET /v0/my/rooms, GET /v0/my/rooms/{room}/talk Conversaciones y sus mensajes sí sí
POST /v0/my/rooms/{room}/talk/listener Oráculo activado / desactivado para esta persona sí (Oyente: activar / desactivar) sí
DELETE /v0/my/rooms/{room}/talk/handoff Marcar un handoff como atendido sí (Handoff: marcar atendido) sí
GET / PATCH /v0/my/rooms/{room}/talk/swag Agenda personal de la conversación sí (Agenda personal) la IA propia del usuario
POST /v0/my/rooms/{room}/talk/trigger Continuar ahora / más tarde, o ver un borrador sí (Continuar conversación) sí
POST /v0/my/rooms/{room}/talk/send Escribir tú a través del oráculo sí sí
POST /v0/my/rooms/{room}/talk/callback Pulsar un botón bajo un mensaje, como el oráculo sí rara vez

Mentioned