Pipeline de API: configurar un widget Cabi.Chat que lleva la IA de Cabi.Chat

Índice: Pipelines de API — índice

Objetivo: un widget Cabi.Chat responde a las personas en sus salas de Cabi.Chat según tu agenda. Cabi.Chat lo ejecuta; no necesitas servidor ni token propios. Qué es un widget y quién puede llegar a él: Cabi.Chat Oracles — widget Cabi.Chat

Pasos

1. Ten una agenda con las instrucciones del widget: Pipeline de API: escribir una agenda para tus oráculos

2. Crear.

POST /v0/my/oracles
Idempotency-Key: widget-bakery-1
{"kind": "cabi_widget", "hosting": "platform", "title": "Bakery desk",
 "agenda": "<agenda nonce>", "project": "<project nonce>",
 "visibility": "Public", "publicity": "Ecosystem",
 "permissions": {"read": true, "write": false, "execute": false}}
→ {"nonce": "470000000000000003", "card_type": "oracle", "kind": "cabi_widget", "status": "STOPPED", …}

• hosting: "platform" es el valor por defecto y puede omitirse.
• agenda: obligatoria; una agenda tuya o que puedas ejecutar.
• visibility, publicity, permissions: quién puede hablar con él. Private por defecto (solo tú); Unlisted y Public necesitan permissions, Public además publicity (Ecosystem = usuarios con sesión, Everyone = también visitantes sin sesión). Da solo read. Cámbialo después con PATCH /v0/my/oracles/{nonce} (solo el dueño).
• topics_in_private: true por defecto: el chat de una persona con el widget puede tener hilos (temas), como «Threaded mode» en @BotFather; false lo deja en un solo hilo. Cámbialo después con PATCH (solo el dueño).
• La respuesta no trae token: Cabi.Chat guarda el token del widget y lo usa él mismo.

3. Iniciar.

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

4. Una persona abre una conversación con él, con sesión iniciada. Habla como su primer proyecto, así que necesita al menos un proyecto:

POST /v0/my/rooms/widget
{"widget": "470000000000000003"}
→ {"nonce": "470000000000000700", "card_type": "room", …}

La sala es el chat privado de esa persona con el widget, con hilos cuando topics_in_private está activado. La misma llamada devuelve la sala existente si ya la hay. Luego escribe con POST /v0/my/rooms/{ident}/talk/send {"text": "…"}, y el widget responde en la sala. Leer y responder salas: Pipeline de API: leer y responder tus conversaciones

5. Sigue las conversaciones. Todas las salas de tu widget están en GET /v0/my/rooms. Puedes escribir en ellas tú mismo: como tu propio proyecto cuando al otro lado está uno de tus proyectos, si no, como el widget: 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

Reglas

• Un widget que quien llama no puede leer responde 404 en el paso 4, igual que uno que no existe. Las salas siguen al widget: mientras alguien no pueda leerlo, sus salas salen de su lista y cualquier llamada sobre ellas le responde 404; vuelven cuando vuelve el acceso.
• Sin agenda → 400 a platform-hosted oracle needs an agenda.
• Unlisted y Public necesitan project: una tarjeta nunca es más visible que su proyecto.
• Para funcionar hace falta un proyecto Pro o tu única plaza gratuita de oráculo; un segundo gratuito → 400 que nombra al oráculo que ocupa la plaza.
• Crear requiere Idempotency-Key; una repetición con la misma clave se rechaza, no se repite. Un widget se crea desde la app web o con tu propio token de acceso personal, no desde una app que conectaste (403).
• Cada respuesta es una ejecución de IA pagada con el saldo del dueño de la agenda; si no alcanza, el widget no responde: Pipeline de API: ver tu gasto en IA
• POST /v0/my/oracles/{nonce}/regenerate-token (solo el dueño) da al widget un token nuevo: la respuesta trae solo token_preview, Cabi.Chat guarda el token y el anterior deja de funcionar.
• DELETE /v0/my/oracles/{nonce} detiene el widget y elimina su token.

Superficie de la API