Pipeline de API: ejecutar un widget Cabi.Chat con alojamiento propio y tu propio programa

Índice: Pipelines de API — índice

Objetivo: tu propio programa responde a las personas en las salas de un widget Cabi.Chat: un script, un servicio de soporte o tu propio asistente de IA, como Claude Code. Cabi.Chat da al widget un token que funciona como el token de un bot de Telegram; la IA de Cabi.Chat no responde. Qué es un widget y quién puede llegar a él: Cabi.Chat Oracles — widget Cabi.Chat

Pasos

1. Crear.

POST /v0/my/oracles
Idempotency-Key: widget-mine-1
{"kind": "cabi_widget", "hosting": "self", "title": "My assistant", "project": "<project nonce>"}
→ {"nonce": "470000000000000004", "card_type": "oracle", "kind": "cabi_widget",
   "status": "STOPPED", "token": "…", …}

2. Apunta tu programa a la Bot API de Cabi.Chat con ese token. Cada petición va a https://api.cabi.chat/bot<token>/<method>, con la misma forma que en Telegram:

GET  https://api.cabi.chat/bot<token>/getMe
GET  https://api.cabi.chat/bot<token>/getUpdates?timeout=50
POST https://api.cabi.chat/bot<token>/sendMessage   {"chat_id": <chat id>, "text": "…"}

Recibe las actualizaciones por long polling o por un webhook que fijas con setWebhook, y responde con los métodos habituales. Métodos admitidos: Spectral — plugins mediante el emulador de bots de Telegram

Archivos: getFile da un file_path; descárgalo de https://api.cabi.chat/file/bot<token>/<file_path>.

3. Conversar. Cada persona que abre el widget recibe una sala con él: un chat privado con tu widget, como en Telegram. Sus mensajes llegan como actualizaciones con chat.type private y chat.id igual al id de usuario de la persona; lo que tu programa envía a ese chat aparece en la sala.

Abrir una sala: Pipeline de API: configurar un widget Cabi.Chat que lleva la IA de Cabi.Chat, paso 4.

Ejemplo: Claude Code

Claude Code puede hablar contigo a través de un widget Cabi.Chat: se ejecuta en tu propio equipo con tu propio inicio de sesión, y Cabi.Chat es solo la superficie de chat. El plugin oficial de canal de Telegram para Claude Code habla la Bot API de Telegram, así que funciona con cualquier raíz de Bot API compatible con Telegram, también https://api.cabi.chat. El ajuste del plugin que lo apunta a otra raíz de Bot API está pendiente en el propio plugin; cuando tu versión lo tenga:

  1. En Claude Code: /plugin install telegram@claude-plugins-official, y luego /telegram:configure <token del widget>.
  2. Fija la raíz de Bot API del plugin en https://api.cabi.chat.
  3. Inicia Claude Code con el canal: claude --channels plugin:telegram@claude-plugins-official.
  4. Abre la sala del widget en Cabi.Chat y escríbele; empareja con /telegram:access pair <code> y ciérralo con /telegram:access policy allowlist, para que solo tú puedas dirigir tu sesión.

Tu sala con el widget es un chat privado, así que el emparejamiento, los comandos y las solicitudes de permiso funcionan como con un bot de Telegram; con topics_in_private activado, puedes llevar hilos separados en ella.

Mantén el widget privado para que solo tú puedas abrir su sala.

Reglas

Superficie de la API

Endpoint Para qué FE IA / oráculo
POST /v0/my/oracles Crear el widget, recibir su token una vez sí (token: no) tu token
POST /v0/my/oracles/{nonce}/regenerate-token Un token nuevo; el anterior deja de funcionar no tu token
PATCH /v0/my/oracles/{nonce} Título, proyecto, visibilidad, agenda, topics_in_private sí sí
https://api.cabi.chat/bot<token>/<method> Recibir y responder como el widget — tu programa
DELETE /v0/my/oracles/{nonce} Eliminar sí rara vez

Mentioned