Funnelchat APIIntroducción
Con la API de Funnelchat armás tu propio sistema sobre WhatsApp, con tus flujos, tus tiempos y tu lógica. Qué es, qué hace nuestra capa por vos y qué tenés que saber antes de integrar.
Con la API de Funnelchat armás tu propio Funnelchat sobre WhatsApp: tus flujos, tus tiempos, tu lógica. Nosotros nos ocupamos de la parte difícil.
Estado: v0 en desarrollo.
Qué es y qué no es
Es un conjunto de piezas para hacer desde tu código lo que se hace en WhatsApp: mandar y recibir mensajes, saber si llegaron, manejar grupos y números, y guardar los datos de tus contactos. Las combinás a tu manera: si no te gustan los tiempos de espera de un flow, armás el tuyo con las piezas y decidís vos cuándo y qué responder.
No es una forma de manejar Funnelchat por control remoto. Si ya usás nuestros flows, campañas o difusiones, también podés consultarlos desde la API (Funciones de Funnelchat), pero no los necesitás para armar lo tuyo.
Qué hace nuestra capa por vos
- Un formato para todos los números. Oficiales de Meta o por QR, la misma llamada. Qué puede hacer cada número lo dice su ficha (
capabilities): Números. - Las reglas de WhatsApp, aplicadas. La ventana de 24 horas, los frenos contra spam y el ritmo por número, antes de que Meta rechace un mensaje o marque tu número. No se pueden apagar: Reglas de WhatsApp.
- Entrega, colas y reintentos. Las sesiones, los números y la entrega los opera Funnelchat: no mantenés servidores de WhatsApp.
- Todo lo que pasa, avisado. Webhooks firmados, con reintentos e historial, para mensajes, estados, grupos y números.
Las piezas
| Pieza | Hoy |
|---|---|
| Mensajes | Recibir y enviar texto, archivos por URL, botones, listas, plantillas, formularios de WhatsApp, tarjetas, reacciones y reenvíos: disponible, con conversations:send y las reglas de WhatsApp. |
| Estados de mensaje | En cola, enviado, entregado, leído y falló: disponible. |
| Grupos | Leer grupos y participantes, y los avisos de lo que pasa adentro: disponible. |
| Números | Estado, salud, conexión por QR y qué puede hacer cada número (capabilities): disponible. |
| Contactos y datos | Contactos, etiquetas, campos y notas: disponible. |
| Eventos | Webhooks firmados con reintentos e historial: disponible. |
Por dónde seguir
- Primeros pasos: la URL base, la clave, un ejemplo de lista y de paginación, los errores comunes y los límites de llamadas.
- Guía rápida: clave, primera llamada, suscripción a un evento y verificación de la firma, en cuatro pasos.
- Armá tu propio flujo: el principio en la práctica, de un mensaje que entra a una respuesta con tus tiempos.
- Autenticación y permisos: el formato de la clave, los permisos, qué está abierto a claves y los errores.
- Webhooks y el catálogo de eventos: cómo suscribirte, la firma con código probado, los reintentos y qué eventos existen.
- Referencia: cada endpoint, con las piezas primero y prueba en vivo con tu clave.
- llms.txt y llms-full.txt: todo esto en Markdown, para que tu IA programe contra la API.
- Procedencia: de qué commit y a qué hora salió cada especificación.
Las áreas
La API tiene una sola URL base, https://api.funnelchat.com, y está organizada en tres áreas, cada una con su propia especificación. Los eventos de las tres se suscriben en un solo lugar, /api/v1/webhooks. Para lo básico —la URL, la clave, un ejemplo de lista y los errores comunes— empezá por Primeros pasos.
| Área | Qué cubre | Instantánea | Operaciones | Eventos construidos |
|---|---|---|---|---|
| Conversations | Contactos, etiquetas, campos personalizados, conversaciones, mensajes, flujos, plantillas, tableros y webhooks de mensajes. | 68cce1b4e · 2026-10-22 16:30 (-03:00) | 152 | 14 |
| Communities | Campañas de grupos de WhatsApp, sus grupos y participantes, envíos programados a grupos, estadísticas y webhooks de grupos. | 6f32f0b4 (árbol con cambios sin commitear) · 2026-10-22 09:46 (-03:00) | 53 | 22 |
| Accounts | La cuenta, sus números de WhatsApp (devices), sus alertas operativas y sus dominios propios. | 300cc8435 · 2026-10-22 09:46 (-03:00) | 68 | 12 |
Cómo armar la URL
La URL de una llamada es la URL base + la ruta completa que muestra el portal. Las rutas del portal son completas: todas empiezan con /api/v1/ y se pegan a la URL base tal cual, sin agregar ni quitar nada.
| Área | Ruta completa (ejemplo) | URL completa | Lo mismo en su especificación: servers + paths |
|---|---|---|---|
| Conversations | GET /api/v1/contacts | https://api.funnelchat.com/api/v1/contacts | https://api.funnelchat.com/api/v1 + /contacts |
| Communities | GET /api/v1/webhooks | https://api.funnelchat.com/api/v1/webhooks | https://api.funnelchat.com/api + /v1/webhooks |
| Accounts | GET /api/v1/me | https://api.funnelchat.com/api/v1/me | https://api.funnelchat.com/api/v1 + /me |
- No combines la URL base del portal con el
serversde una especificación. Saldría…/api/api/v1/…o…/api/v1/api/v1/…, que responden404. - Las especificaciones parten la misma URL en otro lugar: su
serversya incluye parte de la ruta y suspathsson relativos a eso (última columna). Si generás un cliente desde una especificación, usá suserverscon suspaths; si escribís las llamadas a mano, usá la URL base + la ruta completa. Las dos formas dan la misma URL.
Antes de integrar
Lo que tenés que saber de la v0
- La v0 cambia sin aviso. No es una API escrita aparte: la clave entra por las rutas que ya usa el producto, así que rutas, campos y respuestas pueden cambiar sin aviso previo. Generá tu cliente desde la especificación y tolerá campos nuevos. (D7)
- Hay una sola URL base:
https://api.funnelchat.com, igual para las tres áreas. La URL de cada llamada es la URL base + la ruta completa (/api/v1/…): ver Cómo armar la URL. Los hosts internos de cada área ya no se publican y las claves van a dejar de funcionar contra ellos. - Algunas respuestas exponen identificadores internos (
user_id,owner_id,device_iden conversations). Se aceptan en v0 y no son estables: no los guardes como identificadores de tu cuenta. De esos, los eventos de mensajes traen solodevice_id: el número por el que entró o salió el mensaje, el mismo con el que mandás. (enmienda C1/D5 del 04-10) - Revocar una clave corta también los webhooks atados a ella: los que creó o a los que les cambió la URL. Dejan de recibir eventos en el acto, pasan a
status: disabledcondisabled_reason: key_revokedy no se pueden volver a habilitar; para seguir, creá una suscripción nueva. Las creadas desde el panel que ninguna clave redirigió no cambian. Ver Webhooks. (enmienda C3 del 04-10, E18, E19) - La revisión de seguridad del portero cubre hasta la v0.3. La revisión única que pide el contrato se hizo el 11-09 sobre la v0.3 y corrigió tres fallos; los cambios posteriores (desde la lista
operatey el guard explícito de la v0.4) todavía no se revisaron. El portero es la capa que valida la clave, el permiso y, en accounts y communities, el tope diario en cada llamada. (C1, D15) - La especificación de Communities (instantánea 6f32f0b4 (árbol con cambios sin commitear)) ya no dice que las claves estén pendientes. Confirmalo con una llamada real antes de depender de eso. En communities, una clave lee; enviar y operar no habilitan ninguna operación en v0. (Q32, enmienda C1 del 04-10)
- Los webhooks son un solo sistema, en
/api/v1/webhooks, con los permisoswebhooks:readywebhooks:writemás el permiso de lectura del área de cada evento. El sistema anterior de accounts (/api/v1/webhooks/endpoints…) sigue andando, solo para los eventos de la cuenta y sus números. Ver Webhooks y el sistema anterior. - Enviar pide el permiso
conversations:sendy pasa por las reglas de WhatsApp: la ventana de 24 horas, los frenos contra spam y el ritmo por número (Reglas de WhatsApp). Un envío aceptado vuelve en cola (queued): qué pasó después lo cuenta Estados de mensaje. (Q19, que cierra D21) - Todavía no registramos bajas. Si un contacto te pide que no le escriban más, respetalo vos en tu sistema: la API no frena los envíos a ese contacto. Ver Bajas. (Q9)
- No hay sandbox: todo es real. Lo que hagas con una clave actúa sobre los datos y los números reales de tu cuenta. (D17)
Sobre las instantáneas de esta versión
Las instantáneas salieron de árboles de trabajo con cambios sin commitear (Communities 6f32f0b4). El SHA indica la base del árbol, no el contenido exacto que se documentó. Ver Procedencia.
Conocido en v0, se corrige en las specs de los dominios
Diferencias entre lo que dicen las especificaciones y lo que responde la API hoy. Ya están identificadas; mientras se corrigen, esto es lo que conviene hacer.
POST /api/v1/contacts/update-or-create(conversations) responde201o200.201cuando crea el contacto y200cuando ya existía, con el mismoid; la especificación documenta solo200. Busca el contacto por teléfono, con o sin+(+5491100000099y5491100000099dieron el mismo contacto). Mientras tanto: tratá200y201como éxito. En los dos casos el cuerpo es el contacto, sin envoltoriodata.- Las especificaciones no listan todos los
403que pueden llegar. El portero puede responder403en cualquier ruta (permission_deniedoroute_not_available, conerrorymessage). Algunas rutas no documentan403, comoGET /api/v1/contactsen conversations yGET /api/v1/groupsen communities, y donde está documentado el esquema trae solomessage. Mientras tanto: esperá un403en cualquier ruta y decidí porerrorcuando viene. Ver Errores. - No hay una ruta para que una clave consulte qué permisos tiene.
GET /api/v1/me(accounts) pideaccounts:ready, según su especificación, devuelve los datos de la cuenta, no los permisos de la clave. Las rutas de claves responden403 route_not_availablea cualquier clave. Mientras tanto: guardá la lista de permisos al crear la clave. Ver Qué permisos tiene tu clave.
Observado con llamadas reales el 04-10 entre las 19:40 y las 20:00 (-03:00), contra conversations beb716dd7 y accounts 1d6501b4, y en las especificaciones de esa hora y de las instantáneas de Procedencia. La paginación de GET /api/v1/contacts, que figuraba acá, se volvió a probar el 05-10: con clave siempre pagina y links conserva perPage y los filtros, como dice su especificación.