Funciones de WhatsApp

Lo que haces con tus números de WhatsApp después del primer uso —administrarlos, atender una conversación, grupos, plantillas, formularios, Conversions API y costos de Meta—.

Lo que es de Funnelchat —tus contactos, etiquetas, tableros, automatizaciones, difusiones, campañas y tu cuenta— está en Funciones de Funnelchat.

¿Lo vas a integrar? Toca : tu IA recibe todos los campos, los errores y los ejemplos.

Administrar tus números

Mira, edita, desconecta o borra tus números, conéctalos por QR desde tu sistema, revisa su salud, su historial de conexión y su cola de mensajes, y entérate cuando algo cambia.

Cómo funciona

  • Con el id de un número ves todos sus datos: su alias, si está conectado, cómo se conectó y qué puede hacer por la API.
  • También ves el estado de su sesión de WhatsApp. Esa llamada nunca te da el código QR: para conectar o reconectar un número está el link de alta o, si es por QR, «Ver el QR de un número» (abajo).
  • Desconectar un número es lo mismo que «Desconectar» en el panel: deja de mandar y recibir, pero no se borra. Conserva su lugar en tu plan y su historial.
  • Para volver a usarlo, lo reconectas con un link o, si es por QR, pidiendo su QR: es el mismo número y no ocupa otro lugar (Conectar un número).
  • Si el número es oficial de WhatsApp, puedes ver su salud: si puede mandar mensajes y lo último que informó Meta.

Ten en cuenta

  • Lo que da el control de un número o no se deshace pide que tu clave tenga Números de WhatsApp → Crear, conectar y borrar: crear un número, ver su QR, anular un link de alta, desconectar, reiniciar la sesión, borrar un número y vaciar su cola. Es una casilla aparte: Números de WhatsApp → Editar no la incluye.
  • Editar un número, actualizar su salud, reservar un nombre de usuario y sacar mensajes de la cola piden Números de WhatsApp → Editar. Todo lo que solo mira, Números de WhatsApp → Ver.
  • Para recibir los eventos de tus números, Números de WhatsApp → Ver y, para crear el webhook, Avisos (webhooks) → Administrar.
  • Si desconectas un número oficial que estaba conectado, te llega el webhook de número desconectado, con el motivo «lo desconectó alguien de la cuenta».
  • La salud es solo de números oficiales, y muestra lo último que se guardó: no le pregunta a Meta en el momento. Para pedírselo, «Actualizar la salud de un número oficial» (abajo).

No se puede deshacer

Cierra la conexión del número, que deja de mandar y recibir hasta que lo vuelvas a conectar: uno por QR, escaneando un código QR nuevo; uno oficial, con el alta oficial. Conserva su lugar en el plan y su historial.

No se puede deshacer

Borra la información del número conectado en ese lugar (por QR u oficial), igual que «Borrar datos» en el panel, para conectar ahí un número distinto. El lugar en el plan sigue ocupado y se conserva el alias; para conectar el número nuevo hay que pedir un QR o hacer el alta oficial.

No se puede deshacer

El número se borra de la cuenta y libera su lugar en el plan. Para volver a usar ese teléfono hay que crear un número nuevo y conectarlo otra vez.

No se puede deshacer

Descarta todos los mensajes en la cola del número, sin dejar registro de lo descartado.

Conectar por QR desde tu sistema

  • Además del link de alta (Conectar un número), puedes mostrar tú el código QR en tu propio sistema: primero «Crear un número para conectar por QR» y después «Ver el QR de un número», hasta que se escanee con WhatsApp en el celular, en Dispositivos vinculados.
  • El código cambia cada pocos segundos y uno viejo no sirve: pídelo de nuevo cada expires_in segundos (hoy 5), muestra siempre el último y no lo guardes ni lo reenvíes. Cuando el número queda conectado, connected es true y te llega el webhook de número conectado.
  • Manda en country el país del teléfono que va a escanear (dos letras, por ejemplo "mx"): si no lo mandas se usa Colombia, y WhatsApp puede rechazar la vinculación si la sesión se abre desde otro país.
  • Ocupa un lugar de tu plan, como un número conectado con el link. Cada workspace puede tener un solo número por QR que nunca se conectó (la cuenta entera, si no usa workspaces): conéctalo o bórralo antes de crear otro.
  • Para volver a conectar uno de tus números por QR que se desconectó, también pides su QR: es el mismo número, en el mismo lugar.
  • Ves los links de alta de tu workspace, del más nuevo al más viejo, y filtras por estado (pending, completed, failed, expired o revoked) o por tu external_reference.
  • Con el id de un link ves en qué quedó y, si no se completó, por qué (error_code). Ni la lista ni un link traen la URL: aparece solo al crearlo.
  • Anulas un link pendiente que ya no quieres que se use, por ejemplo si lo mandaste a quien no correspondía. Si la página ya había creado un número que todavía no se conectó, ese número se borra.

Editar, reiniciar o borrar un número

  • Editar: cambias su alias, su color, su imagen o tu external_reference (con null la borras). Lo que no mandas no cambia.
  • Reiniciar la sesión es «Borrar datos» en el panel: borra la información del número conectado en ese lugar, por QR u oficial, para conectar ahí un número distinto. El lugar sigue ocupado y se conserva el alias. Si solo quieres cortarlo y volver a conectar el mismo número, eso es «Desconectar».
  • Borrar quita el número de la cuenta y libera su lugar en el plan. Para volver a usar ese teléfono hay que crear un número nuevo y conectarlo otra vez. Uno oficial sigue registrado en Meta, pero Funnelchat deja de recibir sus mensajes; a uno por QR se le cierra la sesión.
  • Al borrar un número te llega el evento device.deleted. Al reiniciar uno oficial que estaba conectado, el de número desconectado, con el motivo «lo desconectó alguien de la cuenta».

Su nombre de usuario

  • Un número oficial puede tener un nombre de usuario de WhatsApp: ves el que tiene, le pides sugerencias a Meta y reservas uno.
  • El nombre de usuario va de 3 a 35 caracteres: letras minúsculas, números, puntos y guiones bajos. Lo reserva Meta: si lo rechaza (por ejemplo, porque ya está tomado), la respuesta dice por qué.

La salud de un número oficial y sus eventos

  • «Actualizar la salud de un número oficial» le pregunta a Meta en el momento y te responde lo mismo que «Ver la salud de un número oficial», más si de verdad se consultó: si se actualizó hace menos de 60 segundos, o ya hay otra actualización en curso, te da lo último guardado.
  • Te enteras de lo que cambia en tus números oficiales: device.health_changed (si puede mandar: available, limited, blocked o unknown), device.quality_changed (la calidad que le da Meta: GREEN, YELLOW o RED), device.messaging_limit_changed (su límite de mensajes por día) y device.display_name_reviewed (Meta aprobó o rechazó su nombre visible).
  • Llegan una vez por cambio real. Si Meta no informa un cambio, Funnelchat lo detecta en su revisión periódica y el evento puede llegar con unos minutos de demora.
  • Si la calidad baja, conviene frenar los envíos de ese número antes de que Meta lo limite.

Su historial de conexión

  • Ves cuándo se conectó y se desconectó un número, de lo más reciente a lo más viejo.
  • Para saber si anda bien, mira su estado y, si es oficial, su salud.

La cola de mensajes de un número

  • Ves los mensajes que esperan en la cola del número y cuántos son, sacas algunos o la vacías entera.
  • Vaciar la cola descarta todos los mensajes encolados sin dejar registro de lo descartado: no se puede deshacer.
  • Para recibir en tu servidor los mensajes y sus estados, usa los webhooks.

Un ejemplo

Los datos de un número:

curl https://api.funnelchat.com/api/v1/devices/dev_Ac7Ku7iIZDXJTjdCu0UB1mX \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Su estado:

curl https://api.funnelchat.com/api/v1/devices/dev_Ac7Ku7iIZDXJTjdCu0UB1mX/status \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Desconectarlo:

curl -X POST https://api.funnelchat.com/api/v1/devices/dev_Ac7Ku7iIZDXJTjdCu0UB1mX/clean \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Crea un número para conectar por QR y pide su código, con el id que te dio (repite la segunda llamada cada expires_in segundos hasta que connected sea true):

curl -X POST https://api.funnelchat.com/api/v1/devices \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: alta-cliente-42" \
  -d '{"connection": "qr", "alias": "Ventas", "external_reference": "cliente-42", "country": "mx"}'

curl https://api.funnelchat.com/api/v1/devices/dev_Ac7Ku7iIZDXJTjdCu0UB1mX/qr \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Cuándo se conectó y se desconectó:

curl https://api.funnelchat.com/api/v1/devices/dev_Ac7Ku7iIZDXJTjdCu0UB1mX/connection-history \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Atender una conversación

Respóndele a un contacto por su id, marca como leído lo que te escribió, muestra «escribiendo…», reacciona a sus mensajes, reenvía un mensaje y compártele una tarjeta de contacto.

Cómo funciona

  • Marcas como leído un mensaje que te mandó un contacto: ve el doble check azul y, en Funnelchat, la conversación queda leída.
  • Le muestras «escribiendo…» mientras preparas la respuesta.
  • Reaccionas con un emoji a uno de sus mensajes, o quitas tu reacción.
  • Le respondes con «Mandar un mensaje a un contacto», con su id: un texto o un archivo, desde uno de tus números (abajo). Para mandarle un formulario de WhatsApp, mira Formularios de WhatsApp.

Según el tipo de número

Número oficialNúmero por QR
Marcar como leídoSíSi el número lo permite
«Escribiendo…»SíNo
ReaccionarSí, hasta 24 horas después del último mensaje del contactoSi el número lo permite

Cuando el número no lo permite, la API responde 422.

Ten en cuenta

  • Marcar como leído, «escribiendo…» y reaccionar piden que tu clave tenga Contactos y conversaciones → Enviar, porque el contacto ve lo que haces.
  • Marcar como leído y «escribiendo…» no mandan ningún mensaje ni cuentan para el ritmo de envío.
  • «Escribiendo…» dura hasta que respondes o 25 segundos, y también le muestra al contacto el doble check azul: pídelo solo cuando vas a responder.
  • La reacción no queda en el momento: la API la acepta y la aplica cuando WhatsApp la confirma. Si al final no se aplica, te llega el evento message.reaction_failed.

Responder, reenviar y compartir un contacto

  • Le mandas un mensaje a un contacto que ya tienes, con su id: un texto o un archivo, desde uno de tus números.
  • ¿Por su id o por su teléfono? Si ya tienes el contacto —te escribió, o lo encontraste en tus contactos—, usa «Mandar un mensaje a un contacto»: nunca crea un contacto, y si ese id no existe responde 404 sin mandar nada. Si tienes un teléfono, que quizás todavía no es tu contacto, usa «Mandar un mensaje» (Mandar mensajes): crea el contacto si hace falta.
  • Reenvías un mensaje de una conversación a hasta 5 contactos, eligiendo por cuál de tus números sale a cada uno. La respuesta trae el resultado de cada destino.
  • Le compartes a un contacto hasta 5 tarjetas de contacto en una llamada, de otros contactos tuyos que tengan teléfono: sale un mensaje por tarjeta.
  • Las tres piden Contactos y conversaciones → Enviar y siguen las reglas de Mandar mensajes: por un número oficial, solo dentro de las 24 horas desde el último mensaje del contacto (fuera de ellas, una plantilla), con el mismo ritmo y el mismo antibloqueo. Salen en cola: el resultado de cada mensaje te llega con message.status_changed.

Un ejemplo

Marca como leído el mensaje que te mandó el contacto (con el id del contacto y el del mensaje):

curl -X POST https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/messages/msg_ADyPfpgQyD89BoEabkSQkV1/read \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Muéstrale «escribiendo…» por uno de tus números oficiales, justo antes de responderle:

curl -X POST https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/typing \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX"}'

Reacciona a su mensaje:

curl -X PUT https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/messages/msg_ADyPfpgQyD89BoEabkSQkV1/reaction \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emoji": "👍"}'

Respóndele con «Mandar un mensaje a un contacto»: su id va en la ruta y también en contact_id:

curl -X POST https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/message \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": "ctc_ABViuUDF93I2VL1tInstRDG", "device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX", "text": "Gracias, ya lo reviso."}'

Reenvía su mensaje a otro contacto, por el mismo número:

curl -X POST https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/messages/msg_ADyPfpgQyD89BoEabkSQkV1/forward \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targets": [{"contact_id": "ctc_AHm3Qe7TzLw0Xb9Nc2YpVdK", "device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX"}]}'

Grupos y sus acciones

Ve los grupos de tu workspace y sus participantes, crea grupos, suma y saca personas, cambia sus datos y su link, responde a las solicitudes para unirse y entérate de lo que pasa adentro.

Tus grupos y sus datos

  • Ves los grupos que ya están en tu workspace, con filtros por número, por nombre o los que no son de ninguna campaña, y abres uno para ver lo que Funnelchat sabe de él: administradores, participantes, link y si está lleno.
  • Lees en el momento, desde WhatsApp, el nombre, la descripción, la foto, el link y los administradores de un grupo.
  • Ves los envíos programados que incluyen un grupo (Envíos programados).
  • Ves los canales y los grupos de anuncios de un número, sin pasar por una campaña.

Lo que pasa en tus grupos

Participantes y administradores

  • Ves los participantes de un grupo, con filtros por teléfono o por si son administradores, y el registro de quién entró y salió, con su fecha y su país.
  • Sumas o sacas personas por su teléfono, hasta 20 por pedido.
  • Haces administradores a otros participantes o les quitas ese rol, también hasta 20 por pedido. Si un teléfono que haces administrador no estaba en el grupo, primero se suma.
  • El resultado dice, persona por persona, cómo salió: que el pedido termine no quiere decir que todas hayan salido bien.

Crear un grupo y cambiar sus datos

  • Creas un grupo desde uno de tus números, con su nombre, su descripción y hasta 20 participantes.
  • Le cambias el nombre (hasta 100 caracteres), la descripción (hasta 2048; vacía, la borra) o la foto (la dirección https de una imagen jpg, jpeg o png).
  • Eliges si en el grupo escriben todos o solo los administradores. Si escriben solo ellos, también son los únicos que editan los datos del grupo.

Cómo salió una acción

  • Lo que le pides a un grupo no se hace dentro de la llamada: la API lo acepta, te da un action_id y lo hace después, al ritmo de tu número.
  • Con ese action_id ves si sigue en cola, si se está haciendo, si terminó o si falló, y su resultado. Al crear un grupo, el uid del grupo nuevo llega ahí cuando termina.
  • O te llega el webhook: group_action.completed cuando termina y group_action.failed cuando falla entera.
  • También ves las acciones que se corrieron sobre un grupo.

Según el tipo de número

Número por QRNúmero oficial
Crear un grupoSíSí, y puede pedir aprobación para entrar
Sumar participantesSí, entran directoPor invitación: cada persona recibe la plantilla de invitación que eligió tu cuenta
Sacar participantesSíSí
Hacer o quitar administradoresSíNo
Cambiar la fotoSíNo
Elegir quién escribeSíNo
Ver y renovar el link de invitaciónSíSí
Ver las solicitudes para unirseNoSí
Aprobar o rechazar solicitudesNoSí, cuando el número lo permite

Con un número oficial, las acciones de grupo necesitan que tu cuenta tenga habilitados los grupos de la API oficial de WhatsApp; su grupo admite hasta 8 participantes y su descripción no se puede borrar. Cuando el número no permite una acción, la API responde 422.

Ten en cuenta

  • Leer pide que tu clave tenga Grupos y campañas → Ver; pedir una acción, Grupos y campañas → Administrar grupos. Esa casilla no incluye Ver: para pedir una acción y ver cómo salió, marca las dos. Para recibir los eventos, Grupos y campañas → Ver y, para crear el webhook, Avisos (webhooks) → Administrar.
  • El número que hace la acción tiene que ser administrador del grupo. En las rutas, el grupo va por su uid (por ejemplo 120363000000000001@g.us).
  • Cada pedido acepta hasta 20 teléfonos, y cada número puede tener hasta 50 acciones sin terminar. Hasta 30 pedidos de acciones por minuto, y hasta 30 lecturas en el momento por minuto (el link y las solicitudes).
  • Sumar participantes se hace de a uno, y entre la creación de un grupo y la siguiente hay una espera: es el ritmo de las campañas del número y no se puede acelerar.
  • Las acciones no tienen clave de idempotencia: si repites un pedido, se hace dos veces.
  • Renovar el link con un número por QR no lo cambia: vuelve a leer el vigente. Con un número oficial, el link anterior deja de servir.

Un ejemplo

Crea un grupo desde tu número, con un participante:

curl -X POST https://api.funnelchat.com/api/v1/groups \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX", "name": "Clientes de noviembre", "participants": ["5491122334455"]}'

Suma dos personas a un grupo, con su uid (tu número es administrador):

curl -X POST https://api.funnelchat.com/api/v1/groups/120363000000000001@g.us/participants \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX", "phones": ["5491122334455", "5491155667788"]}'

Las dos responden con un action_id. Con él, mira cómo salió:

curl https://api.funnelchat.com/api/v1/groups/actions/00000000-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Plantillas de Meta

Crea, revisa y edita tus plantillas de WhatsApp, mira sus métricas, bórrala de un número y entérate cuando Meta cambia su estado.

Cómo funciona

  • Creas una plantilla de WhatsApp: su nombre, su idioma, su categoría (utilidad, marketing o autenticación), su texto y, si quieres, un encabezado, un pie y hasta 3 botones.
  • La creas en uno de tus números oficiales: queda en la cuenta de WhatsApp Business de ese número, y Meta la revisa.
  • Ves una plantilla, con su estado de aprobación, y la editas.
  • Ves sus métricas de Meta, día por día y en total: enviados, entregados, leídos y clics en cada botón.
  • La borras de uno de tus números.
  • Un webhook te dice cuándo Meta cambia el estado de una plantilla: por ejemplo, cuando la aprueba o la rechaza.
  • Para ver todas tus plantillas, traer las que creaste en Meta y mandar una, mira Mandar mensajes.

Ten en cuenta

  • Ver una plantilla y sus métricas pide que tu clave tenga Contactos y conversaciones → Ver; crear, editar y borrar, Contactos y conversaciones → Editar. Para recibir el evento, Contactos y conversaciones → Ver y, para crear el webhook, Avisos (webhooks) → Administrar.
  • Al crearla, la respuesta llega enseguida con la plantilla pendiente (PENDING): Meta la aprueba o la rechaza después. Si el número no tiene una cuenta de WhatsApp Business, termina rechazada. El nombre con su idioma no se repite dentro de una misma cuenta de WhatsApp Business.
  • No siempre se puede editar una plantilla: si en ese momento no se puede, la API responde 400 y te dice por qué. Al editarla no mandas el nombre ni el idioma.
  • Las métricas son solo de plantillas de números oficiales y tienen que estar activadas en el Administrador de WhatsApp de la cuenta. Funnelchat no las activa por ti: Meta no permite desactivarlas después.
  • Muestran hasta 90 días (sin fechas, los últimos 7). Meta registra las lecturas y los clics solo en los 7 días después del envío, y los clics solo en plantillas de marketing o de utilidad.
  • Funnelchat le consulta a Meta hasta 60 veces por hora por cuenta para las métricas; lo que ya leyó lo guarda 15 minutos y no cuenta otra vez.
  • El evento template.status_changed trae el estado anterior y el nuevo, y el motivo cuando Meta rechaza una plantilla recién creada.

Un ejemplo

Las métricas de una plantilla en los primeros días de noviembre (con su id, el de «Ver tus plantillas»):

curl "https://api.funnelchat.com/api/v1/templates/tpl_AlgBF7nTNqV0atiwNuKFmT8/metrics?from=2026-11-01&to=2026-11-10" \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Un webhook para enterarte cuando Meta cambia el estado de una plantilla:

curl -X POST https://api.funnelchat.com/api/v1/webhooks \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://tu-servidor.com/funnelchat", "events": ["template.status_changed"]}'

Formularios de WhatsApp

Arma tus formularios de WhatsApp, publícalos en tus números oficiales, mándaselos a tus contactos, cámbialos con versiones nuevas y lee sus respuestas y sus métricas.

Armar un formulario

  • Empiezas de un modelo: hay uno para armar desde cero (blank) y otros listos. El catálogo es el mismo para todas las cuentas.
  • Lo creas en uno de tus números oficiales (y, si quieres, en otros): queda como borrador, con el id de esa versión y el family_id del formulario.
  • Guardas su contenido: las pantallas, con sus preguntas. Lo incompleto se guarda igual, y la respuesta te dice qué falta corregir antes de publicar.
  • El modelo blank no viene vacío: trae una pantalla que termina el formulario. Lo más simple es reemplazar todas las pantallas por las tuyas.
  • Ves una versión con su contenido, o el contenido vigente del formulario.
  • Cada pantalla tiene elementos de texto (títulos, párrafos, una imagen, un enlace) y preguntas (texto, número, email, teléfono, texto largo, fecha, lista, opción única, opción múltiple y aceptación).

Publicarlo y cambiarlo

  • Antes de publicarlo, puedes validarlo en Meta sin publicarlo.
  • Publicar es inmediato. Si el contenido tiene errores, o no tiene ninguna pregunta, no se publica.
  • Un formulario en borrador (draft) se edita. Uno publicado (published) no se edita ni se borra: creas una versión nueva, la editas y la publicas. El form_id con el que lo mandas no cambia: sale la versión publicada vigente.
  • Ves todas sus versiones, con su estado, cuál es la vigente y cuántas respuestas recibió cada una.
  • Borrar es solo para un borrador.

Sus números

  • Un formulario vive en uno o más de tus números oficiales. El primero es con el que lo creaste, y ese no se saca.
  • En los demás números se publica en segundo plano: ves el estado de cada uno y reintentas los que fallaron.
  • Sumas otro número, o sacas uno: deja de mandarse por él.
  • Para mandarlo por un número, tiene que estar publicado en ese número.

Mandarlo a un contacto

  • Le mandas a un contacto un formulario publicado, para que lo complete sin salir del chat: solo por un número oficial, y hasta 24 horas después del último mensaje del contacto a ese número. Si el número no lo permite, la API responde 422.
  • Lo eliges con «Ver tus formularios»: form_id es su family_id, no su id (ese es el de una versión). Tiene que estar publicado en el número por el que lo mandas.
  • Mandarlo pide Contactos y conversaciones → Enviar; «Ver tus formularios», Contactos y conversaciones → Ver.

Sus respuestas y sus métricas

  • Lo que contesta cada contacto te llega en el momento con whatsapp_form.completed: una respuesta por pregunta.
  • También lees las respuestas de un formulario, de la más reciente a la más antigua, con filtros por fecha, versión, contacto o estado (completada, pendiente, sin enviar o sin terminar), y cada una completa: lo que contestó y lo que se hizo con eso.
  • Las métricas te dicen cuántos se enviaron, cuántos se abrieron y cuántos se completaron, con sus porcentajes.

Ten en cuenta

  • Solo con números oficiales de WhatsApp: los conectados por QR no sirven para formularios.
  • Leer formularios, sus versiones, sus números, sus respuestas y sus métricas pide que tu clave tenga Contactos y conversaciones → Ver; armar, guardar, validar, publicar, crear versiones, borrar borradores y sumar, reintentar o sacar números, Contactos y conversaciones → Editar. Mandar uno pide Contactos y conversaciones → Enviar, que incluye las otras dos: una clave para mandar formularios también puede armarlos y publicarlos.
  • Un formulario tiene un id que no cambia (family_id: el que usas para mandarlo y para leer sus respuestas) y un id por versión (id: el que usas para editarlo, publicarlo y manejar sus números). No los confundas.
  • Hasta 5 pantallas, y por pantalla hasta 50 elementos, 3 imágenes y 2 enlaces. Las preguntas que guardan la respuesta en un campo personalizado o ponen una etiqueta necesitan que ese campo y esa etiqueta ya existan: el formulario no los crea.
  • Cada clave puede hacer hasta 120 lecturas y 60 escrituras por minuto en formularios; validar, publicar y tocar números tienen además un tope de 30 por minuto para toda la cuenta.
  • La clave de un agente trabaja con los formularios del titular de la cuenta y solo ve las respuestas de los contactos que ese agente puede ver.

Un ejemplo

Crea un formulario desde cero en tu número oficial:

curl -X POST https://api.funnelchat.com/api/v1/forms \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_key": "blank", "device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX"}'

La respuesta trae la versión en borrador: su id (por ejemplo frv_Ath9bJ3RpAYPhnX0EfcLtHJ) va en las rutas para editarla y publicarla, y su family_id (frm_AyJUGabeXUAk9dbBuWegw4B) es el formulario. Cuando su contenido no tenga errores, publícala:

curl -X POST https://api.funnelchat.com/api/v1/forms/frv_Ath9bJ3RpAYPhnX0EfcLtHJ/publish \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Busca tus formularios publicados y mándale uno a un contacto: el family_id va en form_id, y device_id es el número oficial por el que sale:

curl "https://api.funnelchat.com/api/v1/forms?status=published" \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

curl -X POST https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/message/form \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form_id": "frm_AyJUGabeXUAk9dbBuWegw4B", "device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX"}'

Lee sus respuestas:

curl https://api.funnelchat.com/api/v1/forms/families/frm_AyJUGabeXUAk9dbBuWegw4B/responses \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Conversions API

Prepara y prueba la conexión de tus números oficiales con la Conversions API de Meta: el dataset de cada cuenta de WhatsApp Business y su estado.

Cómo funciona

  • Para un número oficial, configuras el dataset de la Conversions API de su cuenta de WhatsApp Business: si no tiene uno, se crea en Meta; si ya lo tiene, se usa ese. Llamarlo otra vez no crea otro.
  • Pruebas la conexión de un número: comprueba que tenga el permiso de Meta para mandar eventos y que su cuenta tenga dataset, y te da el enlace al Administrador de eventos de Meta.
  • La prueba no manda ningún evento: una compra de prueba quedaría registrada como una venta real.
  • Ves tus datasets: uno por cada cuenta de WhatsApp Business que ya tiene uno, con lo último que se guardó, sin preguntarle a Meta.

Ten en cuenta

  • Ver tus datasets y probar la conexión piden que tu clave tenga Números de WhatsApp → Ver; configurar el dataset, Números de WhatsApp → Editar.
  • Configurar y probar son solo para números oficiales, y solo para el titular de la cuenta.
  • La Conversions API tiene que estar habilitada para tu cuenta; si no, la API responde 403. Tu plan tiene un tope de conexiones.
  • Estas llamadas preparan y prueban la conexión: la API no tiene una llamada para mandarle eventos a Meta.

Un ejemplo

Configura el dataset de tu número oficial y prueba la conexión:

curl -X POST https://api.funnelchat.com/api/v1/devices/dev_Ac7Ku7iIZDXJTjdCu0UB1mX/capi/dataset \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

curl https://api.funnelchat.com/api/v1/devices/dev_Ac7Ku7iIZDXJTjdCu0UB1mX/capi/test \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

Costos de WhatsApp y cuentas de Meta

Mira cuánto te cuesta WhatsApp en un mes y las cuentas de WhatsApp Business de tus números oficiales, con su límite de mensajes por día.

Cómo funciona

  • Ves el resumen de tus costos de WhatsApp de un mes, el actual o el que elijas, de los números del workspace de tu clave.
  • Ves las cuentas de WhatsApp Business a las que pertenecen tus números oficiales, cada una con sus números, o una sola por su id de Meta.
  • Cada cuenta trae el límite de mensajes por día que Meta le da a la cartera comercial dueña de esa cuenta: lo comparten todos sus números. Es lo último que Funnelchat leyó de Meta.
  • Los números por QR no tienen cuenta de WhatsApp Business: no aparecen.

Ten en cuenta

  • Todo esto pide que tu clave tenga Números de WhatsApp → Ver.
  • El mes va como AAAA-MM. Sin mes, o con uno que no es válido, te da el mes en curso.
  • Las cuentas de WhatsApp Business no traen su nombre, su estado de revisión en Meta, la moneda ni la zona horaria.
  • Si cambia el límite de mensajes de un número oficial, te llega el evento device.messaging_limit_changed (Administrar tus números).

Un ejemplo

Tus costos de WhatsApp de octubre de 2026 y tus cuentas de WhatsApp Business:

curl "https://api.funnelchat.com/api/v1/me/whatsapp-costs?month=2026-10" \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

curl https://api.funnelchat.com/api/v1/me/whatsapp-business-accounts \
  -H "Authorization: Bearer $FUNNELCHAT_API_KEY"

En esta página

Esto es lo que se copia para tu IA

Cargando…