Conectá un bot a Puentes

Puentes es un chat tipo WhatsApp donde las personas conviven con bots: Claude y GPT vienen preintegrados, y vos podés sumar los tuyos. Un bot es un participante más: entra a grupos, tiene chat 1 a 1, se lo menciona con @Nombre y, si lo publicás, aparece en el catálogo para que otros lo agreguen.

Actualizada el 12 de octubre de 2026. La API no tiene versión en la URL: los cambios suman campos y rutas, nunca rompen las que hay; lo que cambia se anota acá. GET /api/version dice qué build está corriendo.

Conceptos

Todo chat es un grupo (kind: "group", con link de invitación) o un chat directo (kind: "direct", exactamente dos participantes, sin invitación). Al crear un bot se crea solo su chat directo con vos. Los mensajes de cualquier bot llevan senderType: "bot"; los de personas, "user"; los avisos del sistema, "system".

Autenticación

Todas las rutas viven bajo https://app.puentes.ai/api y hablan JSON. La credencial va en el header Authorization: Bearer <token>:

• pk_… API key personal: se crea en la web de escritorio, en Creadores → «Bots externos y API» (Creadores aparece con el perfil de desarrollador completo, desde Ajustes → «Ser desarrollador»). Actúa como vos: crea bots, lee y escribe en tus chats, reacciona, vota. Lo que no hace es administrar la cuenta (sesiones, API keys, emails, teléfonos, claves de modelo, formas de entrar): eso es de la app (403). Cada ruta dice en la referencia si la acepta.
• pb_… token de bot: lo devuelve POST /api/bots (o en Creadores → «Nueva IA», eligiendo «Externo»). Actúa como el bot: lee y escribe en los chats donde está. No entra a ningún chat por su cuenta (ni por link de invitación: alguien del grupo lo agrega) y no puede tocar la cuenta del dueño.

Los dos se muestran una sola vez y se guardan hasheados. Si perdés el token de un bot, generá otro (POST /api/bots/:id/token); el anterior deja de funcionar al instante. Los errores vuelven como { "error": "mensaje", "code"? } con el status HTTP que corresponde: error es una frase en castellano para mostrar, y code, cuando viene, es estable para que tu programa decida (ver Errores).

curl https://app.puentes.ai/api/me -H "Authorization: Bearer pk_…"
# { "id": "…", "name": "Mauro", "color": "#65aadd", "bot": false, … }

# Python 3, sin dependencias
import json, os, urllib.request
req = urllib.request.Request('https://app.puentes.ai/api/me', headers={'Authorization': f"Bearer {os.environ['PUENTES_TOKEN']}"})
print(json.load(urllib.request.urlopen(req)))

Crear un bot

POST /api/bots con tu API key. Devuelve el bot, su chat directo con vos y, si es externo, el token.

curl -X POST https://app.puentes.ai/api/bots \
  -H "Authorization: Bearer pk_…" -H "Content-Type: application/json" \
  -d '{
    "runtime": "api",
    "name": "Alertas",
    "description": "Avisos del datacenter",
    "webhookUrl": "https://mi-servidor.com/puentes",
    "public": false
  }'
# { "bot": { "id": "…", "name": "Alertas", "runtime": "api", "tokenPrefix": "pb_ab12cd…", "webhookSecret": "…", … },
#   "token": "pb_…",            <- guardalo: no se vuelve a mostrar
#   "group": { "id": "…", "direct": true, "peer": { "name": "Alertas" }, … } }

Un bot AI creado por API es igual al que se crea desde la app: un "Pirata" con systemPrompt: "Hablás como pirata" y public: true queda en el catálogo para todos.

Bots con herramientas (MCP)

Un bot ai con mcp recibe las herramientas del servidor en cada respuesta y Puentes ejecuta las que el modelo pide (hasta 6 rondas, 30 s por herramienta, 90 s por respuesta; cada respuesta descuenta de la cuota gratis de quien le habla lo que cuesta su nivel, una vez, sin importar cuántas rondas use). La credencial es siempre la del dueño: si el servidor autentica por OAuth, el dueño lo conecta desde el chat (el bot publica una tarjeta mcp_connect en vez de responder) o con POST /api/bots/:id/mcp/connect, que devuelve la url de autorización; al volver, el server guarda los tokens cifrados. Quien pueda usar el bot ejecuta las herramientas con la cuenta del dueño: cada respuesta lleva el rastro en attachments[].type = 'tools' y el socket avisa ai:tool { groupId, aiId, tempId, tool, label, phase: 'start' | 'end', ok } mientras la llama (y phase: 'cards' cuando ya terminó de escribir y está preparando las tarjetas que devolvieron las herramientas: el texto ya está completo y message:new llega enseguida, antes que ai:done). Solo disponible si GET /api/config trae mcpEnabled: true. Un servidor en una red privada no es alcanzable (Puentes corre en la nube): Home Assistant, por ejemplo, con Nabu Casa o un túnel. Fotos y archivos: el bot ve en su contexto el link público de cada foto, video o archivo del chat, y si una herramienta recibe una URL (un menú, un ticket, un PDF) se lo pasa como argumento; el archivo en sí no viaja, tu servidor lo descarga de esa URL si lo necesita.

Para quien escribe un servidor MCP: quién habla y cómo avisar después

Cada tools/call lleva _meta.puentes con el autor del mensaje que disparó al bot: { userId, userName, senderType: 'user' | 'ai' | 'bot', groupId, callbackUrl?, postUrl?, country?, tz? }. Sirve para guardar algo por persona o por chat en vez de por bot (un carrito por chat, una cuenta de Google por persona). Es una afirmación de Puentes, no una prueba: lo que identifica a Puentes es la credencial del bot; si habló otra AI, userId va vacío. country (ISO 3166-1 de dos letras: el país que la persona eligió en su perfil, si no el de su teléfono verificado, si no desde dónde escribió) y tz (zona horaria IANA: la del perfil o del dispositivo de la persona, si no la del chat) son pistas para ordenar resultados y mostrar horas («River» para alguien de Uruguay es el de Montevideo primero); llegan solo cuando se conocen.

callbackUrl viene solo cuando habló una persona y vale 24 horas: es la forma de que el bot retome solo más tarde. Si tu herramienta no puede terminar ahí (necesita que la persona ingrese en tu página, o el trabajo tarda), contestá con lo que la persona tiene que hacer (un link) y guardate la URL; cuando termine, hacé POST callbackUrl con JSON { "text": "Ana conectó su cuenta. Retomá lo que estaba pidiendo." } (hasta 500 caracteres). Puentes responde 202, publica ese texto como mensaje de sistema en el chat y despierta al bot obligado a responder: con la conversación a la vista, vuelve a llamar a la herramienta que había quedado a medias. 404 si el token venció o el bot ya no está en ese chat. La URL es una capacidad (quien la tenga hace hablar al bot en ese chat hasta que venza): guardala cifrada o dentro de un token firmado, y no la loguees.

Para quien escribe un servidor MCP: cargar el servidor no es usarlo (dos credenciales)

Quien registra un conector y quien lo usa son personas distintas, y Puentes manda dos credenciales que no se mezclan. La clave del servidor la pone quien carga el conector (Creadores › Conectores) y dice «esto es Puentes», nada más. La cuenta es de cada persona: la conecta ella desde el chat (OAuth, o una clave que pega) y Puentes la guarda cifrada por persona; un conector puede trabajar con la de cada uno (person), con una por chat (chat) o con la de su creador (owner).

Con OAuth, cada llamada de una persona lleva su token en Authorization: Bearer … y la clave del servidor en X-Api-Key. Sin nadie detrás (el «Probar» de quien carga el conector, o un chat donde todavía nadie conectó su cuenta) llega solo X-Api-Key: con eso tu servidor debería dejar hacer initialize y tools/list, y nunca abrir la cuenta de alguien, nombre el chat que nombre _meta.puentes. Cuando Puentes quiere saber cómo entra cada persona, sondea con la clave del servidor como bearer y sin token: contestá 401 con WWW-Authenticate: Bearer resource_metadata="…" y lo lee como OAuth.

Herramientas que no necesitan cuenta. Buscar un precio o listar las ofertas del día no son de nadie. Marcalas en su definición con _meta: { puentes: { account: false } }: Puentes las llama igual en un chat sin cuenta conectada (con la clave del servidor sola), y solo cuando la IA va a usar una de las otras le muestra a la persona el botón para conectar. Sin la marca, toda herramienta de un conector sin cuenta pide conectarla primero. Solo cuenta false explícito.

El nombre de una cuenta (puentes_account). Una persona puede tener varias cuentas en tu servicio (la del trabajo y la personal; o, si para vos «la cuenta» es un archivo, una por archivo). Para que en «Mis cuentas» no se llamen todas igual, sumá una herramienta reservada puentes_account, sin argumentos, que responda _meta: { puentes: { account: { "label": "Recetas · d…@gmail.com" } } } (hasta 60 caracteres): Puentes la llama una vez, apenas la cuenta se conecta, y usa ese nombre. Toda herramienta cuyo nombre empieza con puentes_ es de Puentes: nunca se le ofrece al modelo ni se le lista a una persona. Primer uso: el conector «Planilla de Google» (puentesai-mcp-google, /planilla/mcp), donde conectar es elegir un archivo del Drive (scope drive.file + el selector de Google) y ese archivo es la cuenta.

Herramientas que leen, que cambian algo y que piden confirmación

Puentes lee de tu tools/list una sola anotación: annotations.readOnlyHint: true dice que la herramienta solo lee (buscar, listar). Toda herramienta sin esa marca se trata como que cambia algo (changes: agrega al carrito, manda, borra), y así se la muestra a la persona. destructiveHint, idempotentHint y openWorldHint se ignoran.

Quien registra el conector puede, para cada herramienta (toolLabels en POST /api/connectors): ponerle un nombre para personas (label), marcarla como que cambia algo aunque el servidor diga que solo lee (changes: true, nunca al revés), esconderla del todo (hidden: true) y hacer que pida confirmación antes de correr (confirm: true). Esa es la única forma de que una herramienta pregunte: las anotaciones nunca lo hacen. En la ficha pública de un conector cada herramienta viaja como { name, label, changes?, confirm? }.

Para quien escribe un servidor MCP: hablar por tu cuenta (postUrl)

Tu servidor solo contesta cuando lo llaman. Para decir algo cuando a vos te pasa algo («salió tu pedido», una alarma, un carrito que cambió del lado de la tienda) no hace falta un segundo bot ni un token: cada tools/call trae _meta.puentes.postUrl, una dirección de ese bot en ese chat. Guardala por groupId y, cuando quieras, hacé POST postUrl con JSON { "text"?, "card"?, "pin"? }: text y card salen como un mensaje del bot (una burbuja, con su notificación; la tarjeta es cualquiera de las de abajo, con la misma limpieza), y pin pone, actualiza o saca un fijado. Responde 202; 400 si no trae nada, 404 si la dirección ya no vale, 429 pasados los 30 mensajes por minuto del bot.

No vence por tiempo: vale mientras el bot siga en ese chat (si lo sacan, muere, y volver a sumarlo da una dirección nueva en la próxima llamada). Viene también cuando habló otra AI. No despierta a la IA ni le cobra a nadie: es el bot hablando. La diferencia con callbackUrl: aquella es de una persona, dura 24 horas, publica una línea de sistema y hace que la IA retome (un login que terminó); postUrl es del chat, dura lo que dure el bot ahí y solo publica. Las dos son capacidades: quien las tenga hace hablar al bot en ese chat, así que guardalas cifradas y nunca las loguees.

Para quien escribe un servidor MCP: escribirle a alguien en nombre de la persona (send)

«El lunes escribile a Flor que llevo el postre»: tu herramienta no manda nada, se lo pide a Puentes. Solo se atiende cuando la herramienta la usa el asistente «Puentes»: con cualquier otra IA el pedido se ignora, porque nadie más escribe en nombre de una persona. En el resultado de tools/call sumá _meta.puentes.send = { "to": "Flor", "text": "Llevo el postre", "when"?: "lunes 9:00" }. to es un nombre en palabras (un contacto o un grupo): Puentes lo busca entre los chats de quien estaba hablando, y tu servidor nunca ve esa lista; si hay varias coincidencias o ninguna, el chat le pregunta a la persona. when usa la gramática de los programados (una vez, todos los días, días de semana, día del mes) y sin él sale ya. Opcionales: via ("whatsapp" | "telegram") cuando la persona nombró el canal, y ref (el número con código de país, o el usuario de Telegram): entonces no sale por Puentes; a esa hora la persona recibe un botón que abre ese chat con el texto listo y lo manda ella. Por WhatsApp sin número, Puentes le contesta a tu herramienta que lo pida. El mensaje sale como un mensaje de la persona, con una marca de «enviado por un asistente», así que un @Bot adentro despierta a ese bot.

Las reglas: solo vale cuando la persona misma lo pidió, y siempre a su nombre (no desde un callbackUrl, un programado u otra IA: ahí se descarta en silencio). En su chat directo con el bot se programa; en un grupo, Puentes le muestra a esa persona sola una tarjeta «¿Lo mando en tu nombre?» y no sale nada hasta que toca «Mandar» (en un grupo no hay contactos de afuera ni lista de chats). No hay un permiso aparte que conceder: lo que lo mantiene honesto es que Puentes lo dice al programarlo, lo dice en el chat al salir, y la persona lo ve y lo cancela desde Ajustes › Mensajes programados. Topes: texto de hasta 2000, 5 envíos programados a la vez y 10 mensajes por día por persona, nada más seguido que una vez por día. El modelo recibe una nota con lo que pasó (programado, esperando la tarjeta, no encontré a quién) para que se lo cuente a la persona.

Para quien escribe un servidor MCP: una lista para elegir (tarjeta options)

Cuando la respuesta es "¿cuál de estos?" (varios productos, varios horarios), la herramienta puede mostrarla como tarjeta en vez de texto: en el resultado de tools/call, además del content de siempre (que es lo que lee el modelo), mandá _meta.puentes.card:

{ "type": "options", "title": "Yerba Playadito", "multi": false,
  "items": [ { "id": "00186014", "title": "Yerba Playadito 500 g", "subtitle": "Con palo", "detail": "$3.186",
               "was": "$4.000", "badge": "20% OFF",
               "image": "https://…/foto.jpg", "url": "https://…/producto" } ] }

Hasta 50 ítems (el chat muestra 10 y un botón «Ver más» despliega el resto sin pasar por el modelo); id (64) y title (120) son obligatorios, subtitle (160), detail (40, va a la derecha: un precio, una hora), was (40, el precio anterior, que se dibuja tachado arriba de detail; sin detail se ignora), badge (24, una etiqueta debajo: "20% OFF", "3x2"), image y url (solo https) opcionales. was y badge son para una oferta: poné en detail el precio que la persona paga hoy y en was el de antes, y no uses el tachado para un precio que exige una condición (llevar tres, una tarjeta de socio) — eso va en el subtitle dicho con todas las letras. Puentes copia cada imagen a su propio bucket (JPEG, PNG, WebP o GIF de hasta 1,5 MB; la que no se puede copiar se omite) y pega la tarjeta debajo de la respuesta del bot, con botId. Hasta 3 tarjetas por respuesta. La persona toca un ítem (con multi: true, tilda varios y aprieta "Elegir") y eso sale como un mensaje suyo, "Elegí: …", con un adjunto { "type": "choice", "botId", "ids": ["00186014"], "labels": ["Yerba Playadito 500 g"] } que despierta a ese bot aunque en el grupo nadie lo haya mencionado; el modelo lo lee como [eligió: Yerba Playadito 500 g (id 00186014)] y vuelve a llamar a tu herramienta con ese id. Contá en la descripción de la herramienta qué hacer cuando llega una elección.

Una tira de carteles (2026-09-15): con "layout": "banners" los ítems se dibujan como imágenes anchas que se corren de costado — para cuando la imagen es el mensaje y ya trae su propio texto (los carteles de campaña de un súper, las portadas de algo). Ahí el title es solo la etiqueta que lee un lector de pantalla, y no hace falta detail. La letra chica va en subtitle y el link a las bases en url: el chat los pone detrás de una (i) en la esquina del cartel: tocarla abre un globo con el texto y un "Ver legales" que va a tu url en otra pestaña (con mouse también aparece al pasar por encima). Así no tapa el arte, se puede leer en el celular, y nadie termina en otro sitio por tocar un botón de 22 píxeles. No repitas "ver legales" en el subtitle: el link ya lo dice. La altura la fija el chat y el ancho lo pone cada imagen, así que no se recorta el arte de nadie. Tocar uno manda la misma elección que cualquier lista: tu herramienta recibe el id y contesta con lo que haya detrás (por ejemplo, los productos de esa campaña como carousel).

Una góndola (2026-09-15): con "layout": "carousel" la misma lista se dibuja como tarjetas que se corren de costado, con la foto grande, la etiqueta de descuento encima y el precio anterior tachado debajo del nombre. Es para cuando la foto y el precio son el mensaje (una fila de ofertas) y nadie va a leer diez nombres. En escritorio aparecen flechas al pasar el mouse, porque una rueda de mouse no se mueve de costado. No cambia nada más: los mismos items, la misma elección de vuelta; si los ítems piden cantidad, cada tarjeta suma un botón + que agrega sin abrir nada. En una lista normal el chat muestra 10 y pagina; un carrusel los muestra todos, porque se corre de costado.

Una cantidad (2026-09-15): si lo que sigue a elegir es "cuántos", la tarjeta puede pedir un control en vez de que la persona escriba otro mensaje. Va input en la tarjeta, y un ítem puede traer el suyo para pisarlo:

{ "type": "options", "input": { "label": "Agregar", "min": 1, "max": 30, "step": 1, "default": 1, "unit": "u." },
  "items": [ { "id": "…", "title": "Queso rallado 150 g" },
             { "id": "…", "title": "Queso cremoso x kg",
               "input": { "label": "Agregar", "min": 0.25, "max": 20, "step": 0.25, "default": 1, "unit": "kg" } } ] }

label (24) es el botón y es obligatorio; unit (8) la palabra al lado del número ("kg"), y min / max / step / default el rango (por default 1, 100, 1 y 1; lo que no entra en el rango se acomoda solo). El input del ítem existe para las listas mezcladas: una búsqueda de "queso" trae el rallado en paquete y el cremoso cortado al momento, y el stepper de uno no sirve para el otro. Con input, tocar una fila abre debajo un − [2] + con el botón en vez de mandar la elección en el acto, y la elección sale con la cantidad: { "type": "choice", "botId", "ids": ["00186014"], "labels": […], "values": [2] }, que el modelo lee como [eligió: Yerba Playadito 500 g × 2 (id 00186014)]. Una tarjeta con input (o con un ítem que lo traiga) es siempre de a una fila: multi se apaga, porque una cantidad por fila es un formulario y no una lista de tildes. Decí en la descripción de la herramienta que cuando la elección viene con cantidad no hay que volver a preguntar cuántos.

Cuando resolvés varias cosas de una (tarjeta picks)

"Necesito leche, pan, yerba y tomates" no se contesta con cuatro listas: son cuatro listas para recorrer, y una respuesta admite tres tarjetas. La tarjeta picks es lo contrario de options: en vez de una pregunta con muchas respuestas, son muchas respuestas ya dadas, cada una con sus alternativas a un toque. Resolvé vos (agregar al carrito, reservar los horarios) y mostrá qué hiciste:

Forma nueva (2026-09-24): también se escribe { "type": "options", "layout": "picks", "title", "rows" }, con las mismas rows; las dos formas valen y significan lo mismo. Desde 2026-09-25 Puentes la guarda en la forma nueva: si leés el historial o recibís el webhook, una tarjeta nueva llega como options con layout (las de antes, con su tipo de siempre). Leé las dos.

{ "type": "picks", "title": "Puse 4 de 5 · carrito $21.840",
  "rows": [
    { "id": "leche", "label": "leche", "picked": "00253104", "qty": 1,
      "input": { "label": "Usar", "unit": "u." },
      "items": [ { "id": "00253104", "title": "Leche La Serenisima 1 L", "detail": "$3.060" },
                 { "id": "00251289", "title": "Leche Ilolay 1 L", "detail": "$2.890" } ] },
    { "id": "fideos", "label": "fideos", "note": "No encontré fideos en Coto", "items": [ … ] }
  ] }

Cada renglón es una cosa que te pidieron: id (64) lo identifica, label (60) es cómo lo dijo la persona, picked el id de lo que elegiste entre los items de ese mismo renglón (si apunta a otro lado se ignora), qty la cantidad, input el control para cambiarla y note (120) por qué no pudiste resolverlo. Los items son exactamente los de options (con was, badge, input): es una lista de listas con un elegido, no un formato nuevo. Hasta 10 renglones, 10 alternativas cada uno y 60 en total (cada foto es una copia a nuestro bucket).

Un renglón sin picked se abre solo, con su note: algo que falta en silencio es peor que algo que pide que lo elijan. La persona toca "Cambiar" en los que no le convencen, los cambios se acumulan y sale un solo mensaje con un choice que dice a qué renglón pertenece cada id: { "type": "choice", "botId", "ids": ["00251289"], "rows": ["leche"], "values": [1], "labels": […] }, que el modelo lee como [eligió: leche: Leche Ilolay 1 L (id 00251289)]. La tarjeta entera la lee como [puse "…": leche → Leche La Serenisima 1 L × 1 $3.060 (id …) · fideos → sin resolver]. Decí en la descripción de la herramienta que no repita la lista en el texto: la tarjeta ya la muestra.

Un botón (tarjeta link): cuando la persona tiene que ir a una página tuya (ingresar en tu servicio, autorizar algo), en vez de pegar la URL en el texto mandá _meta.puentes.card = { "type": "link", "label": "Conectar Google", "url": "https://…/conectar?t=…", "title": "Diego, conectá tu cuenta de Google" }: label (40, el botón) y url (https) obligatorios, title (120) opcional, una línea arriba. Se pega debajo de la respuesta del bot y el modelo lo ve como [botón "Conectar Google"], así no repite la URL. Hasta 3 tarjetas por respuesta, contando options y link.

Botones de respuesta rápida, y una lista con secciones

Botones (2026-09-17, como los reply buttons de WhatsApp): con "layout": "buttons" la tarjeta options se dibuja como hasta 4 pastillas debajo de la burbuja, con el título de cada una (40 caracteres). Tocar una manda ese título como mensaje de la persona con el choice de siempre ({ "ids": ["18"], "labels": ["Sí, a las 18"], "cardId": "…" }). Cada persona la contesta una vez (2026-10-09): cardId es el mensaje de la tarjeta, Puentes guarda en ella lo que eligió cada uno (answers: { userId: { ids, msgId, at } }, avisa con message:updated) y quien ya contestó ve su botón marcado y los otros apagados; un segundo toque suyo no se guarda (vuelve su primera respuesta). El mensaje del toque cita la tarjeta (2026-10-12: replyTo es el mensaje de la tarjeta, como una respuesta citada), así con varias tarjetas parecidas se sabe a cuál contestó. En un grupo cada uno contesta lo suyo. Un fijado de bot se puede tocar siempre. Un ítem puede hacer otra cosa en vez de responder, una por botón: url (abre el link, el CTA URL de WhatsApp), copy (64: copia ese texto al portapapeles y avisa, sin mandar nada: un cupón, un código), o ask con "location", "photo", "file" o "contact" (le pide a la persona su ubicación, una foto con la cámara, un archivo o un contacto de su agenda: la respuesta es su mensaje con ese adjunto más el choice del botón, así sabés a cuál contesta; un contacto llega como palabras, «Nombre: número», y donde el navegador no abre la agenda la persona lo escribe en una hojita). El modelo lee la tarjeta como [botones: "Sí" (id 18) · "Pagar" (abre un link) · "Foto" (pide una foto)].

{ "type": "options", "layout": "buttons", "items": [
  { "id": "18", "title": "Sí, a las 18" },
  { "id": "pay", "title": "Pagar la seña", "url": "https://…" },
  { "id": "cup", "title": "Copiar código", "copy": "BIENVENIDO20" },
  { "id": "ubi", "title": "Compartir mi ubicación", "ask": "location" } ] }

Una IA también los escribe, con o sin herramientas: si su respuesta termina en una pregunta cerrada puede cerrar con un bloque ```buttons, una respuesta por línea (hasta 4), que Puentes convierte en la tarjeta y saca del texto; una línea Pagar | https://… es un botón que abre ese link, solo si la URL la devolvió una herramienta en esa misma respuesta.

Encuesta (2026-09-24): con "poll": true (y "multi" si se eligen varias) un toque es el voto de esa persona, no un mensaje; todos ven cuántos votos tiene cada fila y quién votó. Los votos los escribe Puentes (votes en el adjunto, por message:updated); no se mandan desde afuera. Cuando votaron todos, una IA que mandó la encuesta recibe el resultado.

Marcar varias (2026-09-24): con "select": { "label": "Quitar" } una lista de filas muestra «Seleccionar»; la persona marca varias y un botón con tu palabra las manda juntas: choice con ids y "action": "Quitar", y el texto «Quitar: Leche, Pan». Sirve para sacar cosas de un carrito, archivar, marcar pagados.

Secciones y lista plegada: la misma options admite "sections": [{ "id", "title", "items": […] }] (hasta 10 encabezados sobre las filas de siempre; se guardan planas con section en cada ítem) y "collapsed": "Elegir horario" (24): con eso la lista no ocupa la burbuja sino que se abre en una hoja al tocar ese botón, como el list message de WhatsApp. Ni un carrusel ni los botones se pliegan.

Un catálogo con carrito (tarjeta catalog)

Forma nueva (2026-09-24): también se escribe { "type": "options", "layout": "catalog", … } con los mismos campos (las sections anidadas como abajo, o planas como en cualquier options); las dos formas valen y significan lo mismo. Puentes la guarda plana, como options con layout: "catalog" (ítems con section y sections como títulos): así llega al historial y al webhook.

Como el mensaje de catálogo de WhatsApp, pero los productos viajan en el mensaje: una burbuja chica (miniatura, título, una línea, un pie y el botón) que abre el catálogo entero para recorrer por secciones, con la ficha de cada producto, una cantidad y un carrito que se mantiene en el dispositivo por chat y bot: cualquier tarjeta de catálogo tuya en ese chat lo abre con lo que ya tenía, y se vacía cuando la persona lo manda. Todo sale en un mensaje: { "type": "choice", "ids": ["l1", "q1"], "values": [2, 0.5], "labels": […], "items": […] } (hasta 30 renglones), que el modelo lee como [eligió: Leche 1 L × 2 (id l1), Queso × 0,5 (id q1)].

{ "type": "catalog", "title": "Ofertas de la semana", "body": "Lácteos, almacén y limpieza…", "footer": "42 productos",
  "thumbnail": "https://…", "label": "Ver catálogo", "basket": "Carrito", "send": "Enviar pedido", "sent": "Pedido",
  "input": { "label": "Agregar", "min": 1, "max": 30 },
  "sections": [ { "id": "lacteos", "title": "Lácteos", "items": [ { "id": "l1", "title": "Leche 1 L", "detail": "$1.750", "image": "https://…" } ] } ] }

Los items son los de siempre (con was, badge, url y su propio input para lo que va por kilo); hasta 10 secciones y 60 productos por tarjeta (cada foto se copia al bucket; sin thumbnail se usa la primera foto). Es genérico a propósito: las cuatro palabras (label, basket, send, sent, 24 cada una) son tuyas, así que el mismo esquema sirve para un conteo de inventario (detail «12 en stock», el input de cada ítem arrancando en el stock actual, send «Guardar conteo») o para pedir repuestos.

Una dirección, o cualquier formulario corto (tarjeta form)

Un botón en la burbuja que abre una hoja con respuestas listas arriba (saved: las direcciones que ya tenés de esa persona, como filas) y hasta 8 campos debajo. Tocar una fila guardada manda su id; completar los campos manda form: { id: valor }. Las dos como un choice, así te despierta a vos.

{ "type": "form", "label": "Elegir dirección", "title": "¿A dónde va el pedido?", "send": "Usar esta dirección",
  "saved": [ { "id": "casa", "title": "Casa · Av. Cabildo 2040", "subtitle": "Belgrano" } ],
  "fields": [ { "id": "calle", "label": "Calle y número", "required": true, "placeholder": "Av. Cabildo 2040" },
              { "id": "cp", "label": "Código postal", "type": "number" },
              { "id": "zona", "label": "Zona", "type": "select", "options": ["Norte", "Sur"] } ] }

Tipos: text (default), number, tel, email, date, textarea, select (con options). Los ids son [a-zA-Z0-9_-] de hasta 32. La vuelta se lee como [eligió: Nueva (id form); calle: Av. Cabildo 2040, cp: 1428] y el texto del mensaje repite «Calle y número: … · Código postal: …». No se valida nada por país: la validación es tuya.

Algo siempre a la vista arriba del chat (un fijado, pin)

Para lo que está en curso y conviene tener a un toque: un carrito, un pedido, un turno, un conteo. Un fijado es una pastilla arriba del chat (una etiqueta, un número, un detalle, un ícono) que al tocarla abre cualquiera de las tarjetas de arriba (options, picks, catalog, form, link) más hasta 4 botones. No es un mensaje: no hace ruido en el chat ni cuenta en el tope de 3 tarjetas por respuesta. Las palabras son tuyas; Puentes no sabe qué es un carrito.

// en el resultado de una herramienta, al lado de `content`
"_meta": { "puentes": { "pin": {
  "id": "cart", "label": "Carrito", "badge": "5", "detail": "$12.345", "icon": "basket",
  "scope": "chat",                       // o "person": solo de quien estaba hablando
  "card": { "type": "options", "title": "Carrito · total $12.345", "items": [ … ] },
  "buttons": ["Finalizar compra", "Actualizar"]
} } }

El último que mandás con un id reemplaza al anterior: devolvelo en cada herramienta que cambie ese estado. { "id": "cart", "remove": true } lo saca. Un toque en la tarjeta o en un botón vuelve como cualquier otro: un mensaje de la persona con un choice para tu bot. Íconos: basket, list, tasks, money, clock, store, food, home, plane, cake, ball, star, bell, file, location, people, form, key. Hasta 4 fijados por bot y por chat. Un bot externo, que no tiene resultados de herramientas, publica lo mismo con su token: PUT /api/groups/:id/pins/:pinId (el mismo cuerpo sin id; forUserId lo hace de esa persona sola) y DELETE para sacarlo. Los clientes los leen con GET /api/groups/:id/pins y los eventos pin:updated / pin:removed.

Meterlo en un chat

• Desde la app: en el grupo, botón Bot (o en la info del grupo, "+ Agregar bot"). Por API: POST /api/groups/:id/bots { "botId": "…" } como miembro del grupo.
• Un bot nunca entra solo: con su token, POST /api/invites/…/join responde 403. Siempre lo suma alguien que ya está en el chat.
• Chat 1 a 1: cualquiera que pueda usar el bot (builtin, público o suyo) hace POST /api/direct/:botId. Entre personas, hay que compartir algún grupo.

Enviar mensajes

curl -X POST https://app.puentes.ai/api/groups/<chatId>/messages \
  -H "Authorization: Bearer pb_…" -H "Content-Type: application/json" \
  -d '{ "text": "🔴 @todos rack 4 sin energía", "replyTo": null }'
# -> el mensaje creado (ver Objetos)

• text hasta 20.000 caracteres. Markdown liviano: **negrita**, _cursiva_, `código`, bloques ```, links.
• @Nombre menciona a una persona o bot del chat (le llega la notificación aunque tenga el chat silenciado); @todos avisa a todo el grupo; @Claude o @AI hace responder a la AI.
• replyTo: id de un mensaje del mismo chat para citarlo.
• attachments: primero subí el archivo con POST /api/upload (multipart, campo file) y pasá lo que devuelve: [{ "type": "image", "url": "…", "name": "…", "mime": "…", "size": 123 }].
• Tarjetas (2026-09-17): un bot puede mandar en attachments las mismas tarjetas que devuelve un servidor MCP (options con cualquier layout, botones, picks, link, catalog, form), hasta 3 por mensaje; Puentes las limpia igual, copia sus fotos al bucket y les pone tu id como botId: lo que la persona toque te llega por el webhook como su mensaje con un adjunto choice (ids, labels, values, form).
• Menú fijo: PATCH /api/bots/:id { "menu": [{ "title": "Ofertas" }, { "title": "Carrito", "text": "Mostrame el carrito" }] } (hasta 6, títulos de 24) pone esos botones arriba del campo de texto en el chat directo con tu bot; tocar uno manda text (o el título) como mensaje de la persona. Es un atajo para escribir: te llega como cualquier mensaje.
• clientId (hasta 60 caracteres): mandalo siempre. Si el request se corta y no sabés si entró, reintentá con el mismo: la respuesta es el mensaje ya guardado y nadie lo recibe dos veces. Reintentá ante un timeout o un 502/503/504; un 4xx es un no.
• linkPreview: false: no armar la ficha del link (la de un mensaje de bot nunca se arma).
• POST /api/groups/:id/typing muestra "está escribiendo…" unos segundos.
• Listas de tareas: POST /api/groups/:id/tasklists { "name", "items": ["…"] }, y sobre ellas POST /api/tasklists/:id/tasks { "text" }, PATCH /api/tasks/:id { "text" }, POST /api/tasks/:id/toggle { "done" }, POST /api/tasks/:id/due { "dueAt" }, DELETE /api/tasks/:id; la lista entera: PATCH /api/tasklists/:id { "name" } y DELETE /api/tasklists/:id. Cada cambio responde con la lista completa (el borrado, con el mensaje que la llevaba) y llega por socket como tasklist:updated (o tasklist:deleted). Una tarea con fecha es un recordatorio: a la hora, todo el grupo recibe la notificación.

Recibir mensajes (polling)

Cada mensaje tiene un seq global creciente. GET /api/me/updates?after=<seq> devuelve lo nuevo en todos los chats del bot (menos lo que escribió él mismo), hasta 100 por llamada. Con timeout=<segundos> (máximo 25) la respuesta espera hasta que haya algo: long-poll, sin gastar llamadas.

# primera vez, sin `after`: solo el cursor actual
curl "https://app.puentes.ai/api/me/updates" -H "Authorization: Bearer pb_…"
# { "messages": [], "next": 1234 }

# después, en loop
curl "https://app.puentes.ai/api/me/updates?after=1234&timeout=25" -H "Authorization: Bearer pb_…"
# { "messages": [ { "seq": 1235, "groupId": "…", "senderType": "user", "senderName": "Ana", "text": "hola bot", … } ], "next": 1235 }

Guardá next y volvé a pedir con ese valor. Para saber si un mensaje viene de un chat directo o de un grupo, y quiénes están, GET /api/groups/:id (cacheable). El historial de un chat: GET /api/groups/:id/messages; con un token de bot y sin parámetros trae los últimos 500, y con ?limit, ?before o ?since va por páginas como para una persona (ver la referencia).

Recibir mensajes (webhook)

Si el bot tiene webhookUrl, Puentes hace POST a esa URL por cada mensaje nuevo en sus chats (menos los propios y los del sistema):

POST https://mi-servidor.com/puentes
Content-Type: application/json
X-Puentes-Event: message
X-Puentes-Signature: sha256=<HMAC-SHA256 hex del body, con el webhookSecret del bot>

{ "event": "message", "ts": 1788924608778,
  "group": { "id": "…", "name": "Soporte", "kind": "group" },
  "message": { "id": "…", "seq": 1235, "groupId": "…", "senderType": "user", "senderId": "…", "senderName": "Ana", "text": "…", "attachments": [], "createdAt": 1788924608700, "replyTo": null } }

Verificá la firma con el webhookSecret (lo ves en la sección IAs, editando el bot, o en la respuesta de POST /api/bots):

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const app = express();
app.post('/puentes', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + createHmac('sha256', process.env.WEBHOOK_SECRET).update(req.body).digest('hex');
  const got = req.get('x-puentes-signature') || '';
  if (got.length !== expected.length || !timingSafeEqual(Buffer.from(got), Buffer.from(expected))) return res.status(401).end();
  const { group, message } = JSON.parse(req.body);
  console.log(`[${group.name}] ${message.senderName}: ${message.text}`);
  res.status(204).end(); // respondé rápido; contestá en el chat con POST /api/groups/:id/messages
});
app.listen(8080);

• Timeout de 5 segundos, sin reintentos. Si necesitás garantía de entrega, usá el polling (o las dos cosas: el webhook para reaccionar rápido, updates para no perder nada).
• Solo https:// y pública: se rechaza http:// y cualquier host privado o local, y una redirección nunca baja a http. Para desarrollar, un túnel (ngrok, cloudflared) te da una https, o webhook.site para ver el payload.
• Las transcripciones de audios llegan después, como actualización del mensaje: no viajan por webhook ni por updates. Si te importan, releé GET /api/groups/:id/messages.

Tiempo real con Socket.io

La app usa Socket.io; un bot puede hacer lo mismo con su token en auth.token. Recibe los mismos eventos que el navegador. Los sockets se reparten entre varios dominios: antes de conectar, pedí GET /api/sockets con tu token y conectá al host que devuelve (null = https://app.puentes.ai); la respuesta trae también la lista completa en hosts. Conectá solo por WebSocket (transports: ['websocket']): el long-polling no funciona detrás del balanceador.

import { io } from 'socket.io-client';
const { host } = await (await fetch('https://app.puentes.ai/api/sockets', { headers: { authorization: `Bearer ${process.env.PUENTES_BOT_TOKEN}` } })).json();
const socket = io(host || 'https://app.puentes.ai', { auth: { token: process.env.PUENTES_BOT_TOKEN }, transports: ['websocket'] });
socket.on('message:new', (m) => console.log(m.groupId, m.senderName, m.text));
socket.on('typing', ({ groupId, name }) => {});
socket.on('group:updated', (g) => {});   // miembros, nombre
socket.on('group:new', (g) => {});       // te sumaron a un chat / alguien abrió un directo con vos
socket.on('ai:tool', (e) => {});         // un bot con herramientas (MCP) está llamando a una: { tool, label, phase, ok }
// Para ESCRIBIR usá HTTP, no el socket: POST /api/groups/:id/messages con un clientId (ver abajo).

Todos los eventos (los de la app que no son de la API no están):

El socket es para recibir. Una conexión larga puede morirse sin avisar (un cambio de red, un proxy que la corta) y seguir diciendo connected unos segundos: lo que se emite en ese rato no llega a nadie. Un request HTTP contesta o falla. Por eso las apps de Puentes mandan todo por HTTP desde septiembre de 2026; socket.emit('message:send', …) sigue funcionando, pero no lo recomendamos. Si tu bot depende de no perderse nada, combiná el socket con GET /api/me/updates al reconectar.

Referencia de rutas

Todas bajo https://app.puentes.ai. Quién sale del código de cada ruta: todos = una sesión, una API key pk_ o un token de bot pb_; persona = sesión o API key, nunca un bot; persona (sesión) = solo la app; miembro = del chat de la ruta; permiso = lo que el grupo deja hacer a cada uno (Admins y permisos). Lo que la ruta chequea además (el dueño de un bot, un admin, una cuenta verificada) va al final. Límite es el de esa ruta, además de los generales (Límites).

Quién soy, config y lo nuevo

Mensajes

Chats y miembros

Listas de tareas

Un bot también las arma y edita. Cada cambio responde con la lista entera y llega por el socket como tasklist:updated (o tasklist:deleted). Una tarea con fecha es un recordatorio: a la hora, todo el grupo recibe la notificación.

Tablas

Una tabla es una tarjeta del chat con columnas tipadas (hasta 8: status, select, person, number, date, text, check) y hasta 200 filas; el server calcula el resumen (cuántas en cada estado, sumas, por persona). Un bot crea filas y las edita; cambiar las columnas, renombrar o borrar la tabla es de quien la armó o de un admin, nunca de un bot. Los cambios llegan como table:updated { groupId, table } y table:deleted.

Programados

Un programado lo crea una IA con un bloque ```schedule (decir algo a una hora, despertarse, o mandar algo en nombre de la persona): por la API se leen, se pausan y se cancelan. Objeto: { id, groupId, botId, botName, createdBy, action: "say" | "wake" | "send", text, rule, tz, nextAt, lastFiredAt, runs, paused, held, onlyFor, targetLabel, createdAt }; rule es { once: "YYYY-MM-DD HH:MM" }, { freq: "daily", time }, { freq: "weekly", days: [0-6], time } o { freq: "monthly", monthDay, time }, a la hora del lugar (tz). Los cambios llegan como schedules:updated { groupId, schedules }.

Fijados

Dos cosas distintas: los mensajes fijados de un chat (hasta 3, como en WhatsApp; los fija una persona) y los fijados de un bot (una pastilla arriba del chat con una tarjeta, ver arriba).

Bots

Bots con herramientas (MCP)

Lo que hace falta para escribir un servidor MCP está arriba; estas son las rutas.

Conectores y cuentas

Un conector es un servidor MCP registrado (por una persona o una organización) que varias IAs pueden usar; una cuenta es la credencial de una persona en ese servicio. Cada IA dice con qué cuenta trabaja cada conector: la de cada persona (person), una por chat (chat) o la de quien la hizo (owner). Solo con connectors: true en /api/config. Nunca vuelven la clave del servidor, los tokens ni la URL de un conector ajeno.

La cuenta de una persona

Lo que la app hace con su propia sesión. Una API key no administra sesiones, claves ni formas de entrar (403).

Solo personas (no para bots)

Las rutas de esta página que un token de bot no puede llamar (403): reaccionar, votar, reenviar, fijar mensajes, crear grupos y bots, invitar, compartir, bloquear, y todo lo de la cuenta.

Contactos, compartir y bloqueo

• No hay libreta de contactos. Podés escribirle a alguien si comparten un chat, si alguien que conoce a los dos lo presentó (tarjeta de contacto en un chat) o si conocés su email verificado. Saber el email de una persona alcanza para escribirle, como el número en WhatsApp.
• Compartir es siempre autenticado. Un bot compartido cede solo el permiso de uso: nunca su token, el secreto del webhook, el prompt ni claves. Una tarjeta de contacto lleva nombre y avatar, nunca email ni teléfono. Las tarjetas (attachments[].type = 'bot' | 'contact' | 'mcp_connect' | 'tools' | 'invite' | 'confirm' | 'forward' | 'cap') las construye el server: un cliente no puede mandarlas; las de un bot (options, picks, link, catalog, form) llevan siempre el botId del bot que las mandó.
• Un bot con herramientas usa la cuenta de su dueño. Compartirlo es dejar que esa gente ejecute sus herramientas (con lo que el servidor MCP permita a esa credencial). El rastro queda en cada respuesta; el dueño puede desconectarlo, quitar accesos o borrarlo.
• Bloqueo. Si A bloquea a B: B no puede abrirle un chat ni sumarlo a grupos nuevos; lo que B escribe en el directo queda solo del lado de B (tilde simple, sin push, sin AI, sin webhook) y nunca aparece en el historial de A, ni al desbloquear. A tampoco puede escribirle hasta desbloquear. B no recibe ningún aviso.
• Un bot y las personas. Un bot privado lo usan el dueño y quienes tengan acceso (bot_access); un bot público, cualquiera. Un bot externo recibe por webhook los mensajes de todos los chats donde está: si lo compartís, tu código va a ver mensajes de esa gente.

Admins y permisos de grupo

• Admins. Quien crea un grupo es su primer admin (members[].role = 'admin'); cualquier admin nombra o quita admins y saca gente. A quien creó el grupo nadie lo saca ni le quita admin mientras esté. Si el último admin se va, la persona más antigua pasa a admin. Un bot nunca es admin: lo agrega y lo saca alguien con permiso.
• Permisos (perms en el chat): editInfo, send, addMembers, shareLink, cada uno 'all' o 'admins', y approve. Un grupo nuevo está abierto. Con send: 'admins' un bot externo recibe 403 al escribir (una AI del grupo sigue contestando a los admins). Con shareLink: 'admins' el chat llega sin inviteToken a quien no puede compartirlo.
• Aprobar nuevos miembros (approve: true): entrar por el link responde 202 { pending: true }; lo que agrega o invita un admin entra directo. Un rechazo no avisa nada.
• Sacar a alguien lo veta: no vuelve por el link ni pidiendo entrar; solo un admin lo deja volver.

Objetos

Los que más se usan, campo por campo. Salen de los mismos schemas que /openapi.json (components.schemas), donde están todos los demás (listas, tablas, programados, conectores…). Un campo opcional viene solo cuando aplica; la descripción dice cuándo.

Message

Chat

ChatBotMember

Bot

Lo que dice «Solo para el dueño» llega solo a quien lo puede editar. Nunca vuelven la clave, los tokens ni la URL de un MCP ajeno.

User

Adjuntos y tarjetas (attachments[])

Se distinguen por type (y las tarjetas options por layout). picks, catalog y confirm llegan con su tipo viejo o como options con ese layout: leé las dos formas. Cada forma, campo por campo, está en /openapi.json (components.schemas).

Ejemplos: un bot eco

Responde citando en sus chats directos y cuando lo mencionan en un grupo. Node 18+, sin dependencias:

const BASE = 'https://app.puentes.ai';
const TOKEN = process.env.PUENTES_BOT_TOKEN;
const api = async (path, opts = {}) => {
  const res = await fetch(BASE + path, { ...opts, headers: { authorization: `Bearer ${TOKEN}`, 'content-type': 'application/json' } });
  if (!res.ok) throw new Error(`${path} ${res.status}`);
  return res.json();
};
const me = await api('/api/me');
const mention = new RegExp(`(^|\\s)@${me.name}(?=$|[\\s.,;:!?])`, 'i');
const chats = new Map();
const chatOf = async (id) => chats.get(id) || (chats.set(id, await api(`/api/groups/${id}`)), chats.get(id));

let { next } = await api('/api/me/updates');
for (;;) {
  const r = await api(`/api/me/updates?after=${next}&timeout=25`).catch(() => ({ messages: [], next }));
  next = r.next;
  for (const m of r.messages) {
    if (m.senderType === 'system') continue;
    const chat = await chatOf(m.groupId);
    if (!chat.direct && !mention.test(m.text || '')) continue;
    await api(`/api/groups/${m.groupId}/messages`, { method: 'POST', body: JSON.stringify({ text: `Eco: ${m.text}`, replyTo: m.id }) });
  }
}

El mismo en Python 3, sin dependencias:

import json, os, re, uuid, urllib.request

BASE, TOKEN = 'https://app.puentes.ai', os.environ['PUENTES_BOT_TOKEN']

def api(path, body=None):
    req = urllib.request.Request(BASE + path, data=json.dumps(body).encode() if body is not None else None,
                                 headers={'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'},
                                 method='POST' if body is not None else 'GET')
    with urllib.request.urlopen(req, timeout=35) as res:
        return json.load(res)

me = api('/api/me')
mention = re.compile(rf"(^|s)@{re.escape(me['name'])}(?=$|[s.,;:!?])", re.I)
chats = {}
nxt = api('/api/me/updates')['next']
while True:
    try:
        r = api(f'/api/me/updates?after={nxt}&timeout=25')
    except Exception:
        continue
    nxt = r['next']
    for m in r['messages']:
        if m['senderType'] == 'system':
            continue
        chat = chats.setdefault(m['groupId'], api(f"/api/groups/{m['groupId']}"))
        if not chat['direct'] and not mention.search(m.get('text') or ''):
            continue
        api(f"/api/groups/{m['groupId']}/messages", {'text': f"Eco: {m.get('text')}", 'replyTo': m['id'], 'clientId': str(uuid.uuid4())})

El de Node, listo para correr: node scripts/example-bot.mjs en el repo.

Límites y buenas prácticas

• Los generales y los de cada ruta están en la tabla de abajo; lo que pasa de un límite recibe 429, con Retry-After (segundos) cuando se sabe cuánto esperar.
• Además, por cuenta y por hora: 60 chats directos, 60 altas de bots en grupos, 30 tarjetas compartidas, 10 bots nuevos, 10 links de bot, 10 restablecimientos de link; por día: 30 grupos, 20/50 invitaciones por email (10 el primer día), 5 reportes. Por IP: 20 links de acceso o handoff cada 10 minutos, 30 entradas por link por hora.
• Bots con herramientas: cada respuesta descuenta de la cuota de quien le habla lo que cuesta su nivel (1, 2 o 3), una vez, use las rondas que use.
• Un bot no ve sus propios mensajes en updates ni por webhook. Sí ve los de otros bots: si respondés a todo, cuidá los loops entre bots.
• Nombres: hasta 40 caracteres; en un grupo no puede haber dos participantes con el mismo nombre.
• Los tildes de entregado/leído solo cuentan personas: un bot nunca "lee".
• Tratá el token como una contraseña. Si se filtró, regeneralo desde la sección IAs, editando el bot, o con POST /api/bots/:id/token.

Errores

Siempre { "error": "una frase para mostrar", "code"?: "estable" }. Decidí por el status y, cuando viene, por code; nunca por el texto de error, que puede cambiar.

Lo que dice /api/config

GET /api/config es público y dice qué tiene prendido este server. Una función que depende de una bandera no existe sin ella: preguntá antes de ofrecerla.

La API y esta página están en castellano. En inglés: todavía no (lo decide Mauro).

¿Dudas o ideas? Escribile a Claude en Puentes 😉.