Pipeline de API: leer y responder tus conversaciones

Índice: Pipelines de API — índice

Objetivo: leer y responder tus conversaciones en vivo: listar salas, leer el historial, enviar texto y archivos, responder, editar, borrar, reaccionar, fijar y marcar como leído.

Una sala es una tarjeta (card_type: room). talk.kind indica qué es: native (sala entre proyectos en Cabi.Chat), telegram_oracle (una conversación de tu oráculo de Telegram con una persona en Telegram) o widget (un chat con un widget de IA). En las salas native hablas como uno de tus proyectos; en las conversaciones de tu oráculo, lo que envías le llega a la persona en Telegram como tu oráculo.

Las conversaciones de tu oráculo de Telegram son Unlisted: solo tú, y quienes reciban una conversación por enlace o concesión, pueden abrirlas.

Pasos

1. Listar salas.

GET /v0/my/rooms?limit=50&offset=0
→ {"rooms": [{"nonce": "470000000000000300", "card_type": "room",
              "i18n": [{"lang": "en", "title": "Project: Green Bakery", …}],
              "talk": {"kind": "native", …}, "role": "owner", "unread": 2,
              "permissions": {"send_messages": true, "send_media": true, "pin": true, …}, …}],
   "total": 14, "has_more": false}

unread por sala; permissions es lo que puedes hacer en ella.

2. Abrir una sala. GET /v0/my/rooms/{nonce|@handle}?scene=30 → la sala, su estado (member_count, pinned, settings), unread y los últimos 30 mensajes en scene.

Notas del asistente. En las conversaciones de tu oráculo, la sala lleva llm_memory: lo que el oráculo guarda sobre esta conversación y ve en su prompt (texto plano). Es de solo lectura: solo el oráculo la escribe. La recibe quien puede leer la sala por completo: tú y las personas o agendas con las que compartes la sala; si está vacía, no aparece. El texto de la sala (content) sigue siendo tus notas.

3. Leer el historial.

GET /v0/my/rooms/470000000000000300/talk?limit=50
→ {"messages": [{"id": "<event id>", "seq": 812, "kind": "text", "text": "Do you deliver on Sundays?",
                 "sender": {"name": "Green Bakery", "is_self": false, …}, "timestamp": 1760540000000,
                 "reply_to": null, "edited": false, "deleted": false,
                 "reactions": [{"key": "👍", "count": 1, "mine": true}], …}]}

• Páginas anteriores: before_seq=<smallest seq you have> (el seq más pequeño que tengas). Un hilo: thread_id=<thread root id>. timestamp va en ms.
• id es lo que usan editar, borrar, reaccionar, fijar y responder.

4. Enviar.

POST /v0/my/rooms/470000000000000300/talk/send
{"text": "Yes, 8:00 to 14:00.", "reply_to": "<event id>"}
→ {"event_id": "<event id>"}

Opcional: formatted_body (versión HTML del texto), thread_id (con hilos activados), reply_to.

5. Enviar un archivo. POST …/talk/send-media, multipart: file (obligatorio, hasta 25 MB), text (pie), thread_id → {"event_id": …}.

6. Cambiar mensajes.

POST …/talk/edit    {"event_id": "<id>", "text": "Yes, 8:00 to 15:00."}
POST …/talk/delete  {"event_id": "<id>"}
POST …/talk/react   {"event_id": "<id>", "key": "👍"}            add; "remove": true takes it back
POST …/talk/pin     {"event_id": "<id>", "pinned": true}          false unpins

Reacción: "remove": true la quita; "pinned": false desfija.

7. Estado de lectura. POST …/talk/mark-read {"last_event_id": "<id>"} (sin él: hasta el último) → 204, pone unread a cero. POST …/talk/typing {"typing": true} → 204 muestra que estás escribiendo.

Actualizaciones en vivo. GET /v0/my/sse (con tu token) es un flujo de server-sent events. Cada mensaje nuevo en cualquiera de tus salas llega así:

event: talk_message
data: {"kind": "talk_message", "room": "470000000000000300", "event_id": "<id>", "seq": 813, …}

Después vuelve a leer el historial de esa sala. Los comentarios keep-alive mantienen el flujo abierto. Los flujos abiertos por cuenta son limitados: uno nuevo por encima del límite cierra el más antiguo.

En segundo plano

• En las conversaciones de tu oráculo de Telegram, enviar, editar, borrar y reaccionar salen en Telegram como el oráculo y Telegram puede rechazarlos (por ejemplo, una espera por flood: … (retry in <n>s)). Hasta que la persona escriba primero, enviar responde … wait for an inbound message.

Reglas (400)

• text must not be empty; file field is required; empty file; file exceeds 25MB.
• no permission to send in this room (igual para editar, borrar, reaccionar, fijar); not a participant of this room; threads are disabled in this room.
• Una sala en la que no estás: 404.

Superficie de la API