Funciones de Funnelchat
Lo que haces con Funnelchat después del primer uso —tus contactos, etiquetas, tableros, tickets, automatizaciones, difusiones, campañas de grupos, ventas y tu cuenta—.
- Tu CRM: Contactos y conversaciones, Etiquetas y campos personalizados, Notas de un contacto, Tableros, Tickets, Respuestas rápidas.
- Automatizaciones y envíos: Automatizaciones y carpetas de flujos, Difusiones.
- Grupos: Campañas de grupos, Envíos programados, Estadísticas de tus grupos.
- Ventas: Puntaje de tus contactos, Ventas.
- Tu cuenta: Dominios propios, Tu cuenta y tu equipo, Alertas, Más sobre tus webhooks.
Lo que es de WhatsApp —tus números, atender una conversación, grupos, plantillas, formularios y Meta— está en Funciones de WhatsApp.
Contactos y conversaciones
Busca tus contactos y los de cada número, créalos o actualízalos por su teléfono, edítalos o bórralos, mira su ventana de 24 horas, lee y cuenta tus conversaciones, márcalas todas como leídas o no leídas y entérate cuando algo cambia.
Cómo funciona
- Buscas tus contactos por nombre, teléfono, email, país, etiquetas o campos personalizados, y abres uno para ver todos sus datos.
- Creas un contacto con su teléfono. Si no sabes si ya existe, lo creas o actualizas por su teléfono: así no queda repetido.
- Al crearlo, o al crearlo o actualizarlo, le pones también los valores de sus campos personalizados.
- Editas sus datos: nombre, email, teléfono, notas.
- Lees los mensajes que tienes con un contacto y ves la lista de tus conversaciones, con filtros como «sin leer».
- Un webhook te dice cuándo se crea o cambia un contacto, y cuándo una conversación se asigna o se cierra: para tener tu CRM al día sin preguntar a cada rato.
Ten en cuenta
- Leer pide que tu clave tenga Contactos y conversaciones → Ver; crear y editar, Contactos y conversaciones → Editar. Para recibir los eventos, Contactos y conversaciones → Ver y, para crear el webhook, Avisos (webhooks) → Administrar.
- Para mandarle un mensaje no hace falta crear el contacto: el envío por teléfono lo crea (Mandar mensajes).
- Crear o actualizar un contacto que ya existe le cambia el nombre y el email por los que mandes. Crear uno que ya existe te devuelve el que estaba, sin cambiarlo.
- Los valores de los campos personalizados van como texto, en el formato de su tipo (una fecha es
AAAA-MM-DD): si uno no cumple, la API responde422y no crea ni cambia nada (Etiquetas y campos personalizados). - Si el teléfono ya es contacto de otro de tus workspaces, la API responde que no lo encuentra (Workspaces).
- Las listas vienen por páginas, de hasta 100 a la vez.
Los contactos de un número y su ventana de 24 horas
- Ves los contactos de uno de tus números, por páginas.
- Antes de escribirle a un contacto por un número oficial, miras si su ventana de 24 horas está abierta en ese número: si está abierta, le mandas un mensaje libre; si no, una plantilla (Mandar mensajes).
- Las dos piden Contactos y conversaciones → Ver. La especificación no describe uno por uno los datos de la ventana: mira lo que llega antes de depender de uno.
Borrar contactos
- Borras uno o varios contactos de una vez, con la lista de sus
id. - Pide Contactos y conversaciones → Editar.
- La especificación no dice si se puede deshacer ni qué pasa con sus mensajes. El cuerpo acepta también
ally filtros como los de buscar contactos, pero la especificación no describe qué borran: usa solo la lista deid. - Al borrar un contacto no llega
contact.tag_removedpor sus etiquetas.
Contar y marcar tus conversaciones
- Cuentas todas tus conversaciones, las abiertas, las cerradas o las sin leer, por ejemplo para un tablero. Pide Contactos y conversaciones → Ver.
- Marcas todas como leídas, o todas como no leídas, de una vez, con los mismos filtros que al contar. Pide Contactos y conversaciones → Editar.
- Marcar todas como no leídas tiene un tope: la respuesta dice cuántas marcó y si llegó al tope. La especificación no dice cuál es.
- La especificación no dice si el contacto ve algo al marcar todas como leídas. Para que vea el doble check azul en un mensaje, usa «Marcar un mensaje como leído» (Atender una conversación).
- Para marcar una conversación como favorita, asignarla a alguien de tu equipo o marcarla sin leer, usa «Editar un contacto»: acepta esos datos.
Un ejemplo
Busca un contacto por su teléfono:
curl "https://api.funnelchat.com/api/v1/contacts?phone=5491122334455" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Créalo o actualízalo, con el nombre y el email que deben quedar y el valor de un campo personalizado:
curl -X POST https://api.funnelchat.com/api/v1/contacts/update-or-create \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone": "5491122334455", "name": "Ana Pérez", "email": "ana@example.com", "custom_fields": [{"id": "fld_Ar7McDNiFfizqFzTybtrwHL", "value": "Mayorista"}]}'Los mensajes que tienes con él, con su id:
curl https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/messages \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Mira si la ventana de 24 horas de un contacto está abierta en tu número oficial:
curl "https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/meta-window?device_id=dev_Ac7Ku7iIZDXJTjdCu0UB1mX" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Cuenta tus conversaciones sin leer:
curl https://api.funnelchat.com/api/v1/conversations/count/unread \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Etiquetas y campos personalizados
Ve, arma y borra tus etiquetas y tus campos personalizados, agrégales o quítales etiquetas a tus contactos, guárdales tus propios datos y entérate cuando un contacto recibe o pierde una etiqueta.
Cómo funciona
- Etiquetas: ves las de tu cuenta, creas una nueva, le cambias el nombre, la descripción o el color, y ves qué contactos tienen una y qué etiquetas tiene un contacto.
- Etiquetar a tus contactos: agregas o quitas etiquetas a uno o a varios contactos, hasta 200 por vez: mandas una lista de contacto y etiqueta.
- Campos personalizados: creas los datos propios que quieres guardar en tus contactos (un plan, una ciudad, una fecha), y para cada contacto lees, pones o quitas su valor.
- Poner un valor sirve para muchos contactos a la vez: mandas una lista de contacto, campo y valor. También se los pones al crear un contacto, o al crearlo o actualizarlo (Contactos y conversaciones).
- Un webhook te dice cuándo un contacto recibe o pierde una etiqueta.
Ten en cuenta
- Leer pide que tu clave tenga Contactos y conversaciones → Ver; crear, editar, quitar etiquetas y poner o quitar valores, Contactos y conversaciones → Editar. Agregar etiquetas pide Contactos y conversaciones → Enviar, porque puede arrancar una automatización que manda mensajes. Para recibir los eventos de etiquetas, Contactos y conversaciones → Ver y, para crear el webhook, Avisos (webhooks) → Administrar.
- Agregar una sola etiqueta a un solo contacto arranca, como en el panel, la automatización que empieza con «Tag agregado» de esa etiqueta. Si en la misma llamada van varias, a uno o a varios contactos, no arranca ninguna. Quitar una etiqueta no arranca nada.
- Agregar y quitar etiquetas no te dicen qué cambió: para confirmarlo, mira las etiquetas del contacto.
- El tipo de un campo se elige al crearlo y después no se cambia: al editarlo cambias su nombre y su descripción.
- Al poner valores, la respuesta trae un resultado por cada elemento de la lista: revisa cada uno.
Los tipos de campo
Cada campo tiene un tipo, que eliges al crearlo (type, de 0 a 4) y dice cómo escribir su valor:
type | Tipo | Cómo va el valor | Ejemplo |
|---|---|---|---|
0 | Texto | Cualquier texto. | "Cliente mayorista" |
1 | Numérico | Un número, con punto decimal y sin separador de miles; puede llevar - adelante. | "1500", "99.90" |
2 | Fecha | AAAA-MM-DD, una fecha que exista. | "2026-11-30" |
3 | URL | La dirección completa, con https:// o http://. | "https://ejemplo.com/pedido/123" |
4 | Alfanumérico | Pensado para códigos con letras y números; acepta cualquier texto. | "AB1234" |
- El valor va siempre como texto, también un número o una fecha:
"1500", no1500. - Cuando lo pones con tu clave, la API lo valida contra el tipo: un campo numérico, de fecha o de URL solo acepta su formato. Si no lo cumple, responde
422con el formato que espera y no lo guarda. Texto y alfanumérico aceptan cualquier texto. - Un valor que no puso tu clave (desde el panel, una automatización o una importación) puede tener otro formato.
Borrar etiquetas y campos
- Borras una o varias etiquetas, o uno o varios campos personalizados, con la lista de sus
id. - Piden Contactos y conversaciones → Editar.
- La especificación no dice si se puede deshacer, ni qué pasa con los contactos que tenían esa etiqueta o un valor en ese campo.
- Borrar una etiqueta no manda
contact.tag_removed, y borrar un campo no mandacontact.updated. - En esta lista, la especificación declara los
idcomo texto:["7"].
Un ejemplo
Agrega una etiqueta a un contacto (el id de la etiqueta está en tus etiquetas):
curl -X POST https://api.funnelchat.com/api/v1/contacts/add-tags \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '[{"contactId": "ctc_ABViuUDF93I2VL1tInstRDG", "tag": {"id": "tag_AIJEDzSFQ6oDXbab3DubTEG"}}]'Tus campos personalizados, para tener sus id:
curl https://api.funnelchat.com/api/v1/custom-fields \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Pon un valor en un contacto (un campo de fecha, en AAAA-MM-DD):
curl -X POST https://api.funnelchat.com/api/v1/contacts/attach-custom-field \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '[{"customFieldId": "fld_AGxYus0ZuS8ViUElnapfBA0", "contactId": "ctc_ABViuUDF93I2VL1tInstRDG", "value": "2026-11-30"}]'Borra una etiqueta que ya no usas (con su id):
curl -X POST https://api.funnelchat.com/api/v1/tags/delete \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tagIds": ["7"]}'Notas de un contacto
Lee las notas que tu equipo dejó sobre un contacto, agrega una nueva o borra la que ya no sirve.
Cómo funciona
- Ves las notas de un contacto, con quién las escribió y cuándo, y buscas por texto.
- Agregas una nota, por ejemplo para dejar en la ficha del contacto algo que pasó en tu sistema: una llamada, una compra, un reclamo.
- Borras una nota que quedó vieja o se cargó por error.
Ten en cuenta
- Ver las notas pide que tu clave tenga Contactos y conversaciones → Ver; agregar y borrar, Contactos y conversaciones → Editar.
- Una nota va hasta 2000 caracteres. La API no edita notas.
- Estas notas son una lista aparte, con autor y fecha. El contacto también tiene un campo
notes, que cambias con «Editar un contacto»: la especificación no dice si tienen relación.
Un ejemplo
Agrega una nota a un contacto:
curl -X POST https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/notes \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"body": "Llamó para pedir la factura de octubre."}'Tableros
Arma tus tableros y sus etapas, mira qué contactos hay en cada etapa, muévelos o sácalos, y entérate cada vez que un contacto cambia de etapa.
Tus tableros
- Ves tus tableros, ves uno con todas sus etapas, creas uno, lo editas o lo borras.
- Un tablero es por etapas (
modestages: le das sus etapas por nombre) o por etiquetas (modetags: cada columna es una de tus etiquetas). Hasta 15 en los dos. - Al editarlo cambias su nombre, su descripción, su ícono, su vista o sus etiquetas. Las etapas se cambian con sus propias llamadas.
Las etapas
- Creas una etapa y eliges después de cuál va; le cambias el nombre, o cambias el orden de todas mandando sus
iden el orden nuevo. - Borras una etapa y, con
reassign_to_stage_id, eliges a qué etapa pasan sus contactos.
Los contactos del tablero
- Ves los contactos de una etapa, con filtros: nombre, mensajes leídos o sin leer, fechas (de entrada al tablero, de alta o de última actividad), asesor, valor, estancados, etiquetas, puntaje y seguimiento.
- Ves la etapa en la que está un contacto en cada uno de tus tableros.
- Con «Ver si unos contactos están en un tablero» le pasas una lista de contactos y te dice cuáles están en ese tablero.
- Mueves un contacto a una etapa, o hasta 200 a la misma etapa en una llamada; sacas a uno del tablero, o hasta 200 a la vez.
Enterarte cuando un contacto cambia de etapa
contact.stage_changedllega por cada contacto que entra a un tablero, pasa de una etapa a otra, sale del tablero o se reubica porque su etapa se borró.- Solo en tableros por etapas, y no llega si el contacto ya estaba en esa etapa.
- No dice quién movió al contacto, y la especificación no deja afuera los cambios que haces tú: si tu sistema mueve y escucha, prepáralo para recibir también los suyos.
Ten en cuenta
- Ver tableros, etapas y contactos pide que tu clave tenga Contactos y conversaciones → Ver; crear, editar, borrar, ordenar, mover y sacar, Contactos y conversaciones → Editar. Para recibir el evento, Contactos y conversaciones → Ver y, para crear el webhook, Avisos (webhooks) → Administrar.
- Usa tableros por etapas para mover contactos: la especificación no dice qué hace mover a un contacto en uno por etiquetas.
- Mover y sacar no te dicen cómo quedó: para confirmarlo, mira los contactos de la etapa o las etapas del contacto.
- La especificación no dice qué pasa con los contactos cuando borras un tablero, ni a qué etapa van los de una etapa borrada si no eliges una.
- Las listas vienen por páginas, de hasta 100 a la vez.
Un ejemplo
Un tablero con sus etapas, para tener el id de cada una:
curl https://api.funnelchat.com/api/v1/kanban-settings/knb_AD77AjVHX9JMsZN827QxGh9 \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Mueve un contacto a una etapa de ese tablero:
curl -X POST https://api.funnelchat.com/api/v1/kanban-settings/knb_AD77AjVHX9JMsZN827QxGh9/move-contact \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contact_id": "ctc_ABViuUDF93I2VL1tInstRDG", "stage_id": "stg_AFQNmQUExx0MW4DNcQd3h0a"}'Tickets
Abre tickets sobre tus contactos, dáselos a alguien de tu equipo, edítalos, ciérralos y vuelve a abrirlos.
Cómo funciona
- Abres un ticket sobre un contacto, con un título y una descripción, y se lo das a una persona de tu equipo.
- Ves tus tickets, filtrados por estado o por persona, y uno con todos sus datos.
- Le cambias el título y la descripción, se lo pasas a otra persona, lo cierras cuando el caso se resolvió y lo vuelves a abrir si hace falta.
Ten en cuenta
- Ver tickets pide que tu clave tenga Contactos y conversaciones → Ver; crear, editar, asignar, cerrar y reabrir, Contactos y conversaciones → Editar.
- Al crearlo van los cuatro datos: la persona (
userId), el contacto (contactId), el título (hasta 191 caracteres) y la descripción. Al editarlo, el título y la descripción, los dos. - La especificación no dice de qué lista sale el
userIdde la persona: confírmalo antes de crear tickets desde tu sistema. - La lista se filtra por estado (
status):1trae los tickets abiertos y2los cerrados. Si no lo mandas vale0, que trae los contactos que todavía no tienen un ticket: para ver tus tickets, manda1o2. - Un ticket no trae un campo de estado: está abierto si su
deadlineestá vacío (null). Al cerrarlo,deadlineguarda los minutos que estuvo abierto; al reabrirlo, vuelve anull. - La API no borra tickets.
Un ejemplo
Abre un ticket sobre un contacto y dáselo a una persona de tu equipo:
curl -X POST https://api.funnelchat.com/api/v1/tickets \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"userId": "usr_AdaVCroxOubVJxQ0exvtano", "contactId": "ctc_ABViuUDF93I2VL1tInstRDG", "title": "Factura sin llegar", "description": "Pidió la factura de octubre y todavía no le llegó."}'Tus tickets abiertos:
curl "https://api.funnelchat.com/api/v1/tickets?status=1" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Ciérralo, con el id que te devolvió:
curl -X POST https://api.funnelchat.com/api/v1/tickets/tkt_AF55AkRPf2n0s11MKuItMb0/close \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Respuestas rápidas
Mira las respuestas rápidas de tu equipo, crea nuevas, edítalas o bórralas.
Cómo funciona
- Ves las respuestas rápidas de tu cuenta, con búsqueda por texto, y una con todo: su nombre, su mensaje, su archivo, su tipo, su visibilidad y qué agentes la tienen.
- Creas una con un nombre corto (hasta 30 caracteres) y su mensaje (hasta 2500), y eliges su visibilidad.
- La editas, o la borras cuando ya no se usa.
Ten en cuenta
- Ver pide que tu clave tenga Contactos y conversaciones → Ver; crear, editar y borrar, Contactos y conversaciones → Editar.
- El tipo (
type) y la visibilidad (visibility) son obligatorios al crear y al editar. El tipo es el del mensaje:0texto,1imagen,2video,3documento o6audio, según el archivo que lleva. La visibilidad:1la ven tú y todo tu equipo,2solo los agentes que elijas (agent_ids) y3solo la cuenta principal. - En la lista, un agente ve las de visibilidad
1y las2que tiene asignadas; la cuenta principal ve las1y las3, pero no las2. - Al editarla mandas otra vez el nombre, el tipo y la visibilidad.
- La especificación no describe qué va en
fileni la forma deagents.
Un ejemplo
Busca tus respuestas rápidas por texto:
curl "https://api.funnelchat.com/api/v1/quick-replies?search=horario" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Automatizaciones y carpetas de flujos
Mira tus flujos y sus pasos, qué automatizaciones se corrieron sobre un contacto y quiénes están en curso o pausados en cada flujo, cancela una ejecución, pausa las automatizaciones de un contacto, ordena tus flujos en carpetas y entérate cuando una termina o falla.
Cómo funciona
- Ves el historial de un contacto: cada vez que un flujo corrió sobre él, si sigue en curso, si terminó o si se canceló.
- Ves en qué flujos está un contacto y si alguno sigue corriendo.
- Ves tus flujos y, de cada uno, su configuración, sus pasos y los contactos que pasaron por él.
- Cuentas y ves los contactos que están ahora en curso en un flujo, y los que están pausados.
- Cancelas una ejecución que sigue en curso, o pausas las automatizaciones de un contacto.
- Un webhook te dice cuándo un flujo termina para un contacto y cuándo falla.
Ten en cuenta
-
Ver pide que tu clave tenga Contactos y conversaciones → Ver, también para recibir los dos eventos; cancelar una ejecución y pausar a un contacto, Contactos y conversaciones → Editar. Para crear el webhook, además, Avisos (webhooks) → Administrar.
-
Solo cancelar y pausar cambian algo: las demás llamadas solo leen.
-
No hay evento cuando un contacto entra a un flujo ni cuando se cancela una ejecución: llegan solo cuando termina bien y cuando falla.
-
Cancelar solo sirve con una ejecución que sigue en curso: si ya terminó, o no existe, la API responde
422y no cambia nada. -
Para cancelar, el id de la ejecución sale del historial del contacto (el
idde cada una) o de los contactos de un flujo (contact_flow_id). -
Pausar te devuelve el contacto, que trae cuándo se pausó (
paused_at). Una pausa no vence ni se levanta sola, y la API no tiene una llamada para reanudarla: pausa solo si es lo que quieres. -
Los pasos y la configuración de un flujo llegan tal como están guardados: la especificación no describe qué es cada tipo de paso ni su configuración.
Carpetas de flujos
- Ves tus carpetas y, de cada una, sus subcarpetas y cuántos flujos tiene. Puedes buscar una por su nombre.
- Creas una carpeta, o una subcarpeta dentro de otra.
- Le cambias el nombre a una carpeta o la mueves dentro de otra.
- Borras una carpeta que ya no usas.
- Para ver los flujos de una carpeta, filtras tus flujos por esa carpeta (arriba).
- Ver pide que tu clave tenga Contactos y conversaciones → Ver; crear, editar y borrar, Contactos y conversaciones → Editar.
- Estas llamadas arman las carpetas: no mueven flujos de una carpeta a otra.
- La especificación no dice qué pasa con los flujos y las subcarpetas de una carpeta que borras.
Un ejemplo
El historial de automatizaciones de un contacto, solo las que siguen en curso:
curl "https://api.funnelchat.com/api/v1/contact-flows/ctc_ABViuUDF93I2VL1tInstRDG?status_group=en_curso" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Un webhook para enterarte cuando un flujo termina o falla:
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": ["flow.completed", "flow.failed"]}'Cuántos contactos están ahora en curso en un flujo (con su id, el de tus flujos):
curl https://api.funnelchat.com/api/v1/flows/flw_AHRNv5zDGiU72BDvJYbeGRy/active-contacts \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Crea una carpeta de flujos:
curl -X POST https://api.funnelchat.com/api/v1/folders \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Ventas"}'Los flujos de una carpeta, con su id:
curl "https://api.funnelchat.com/api/v1/flows?folder_id=fdr_AcPR1j7N9cs1PrbzZmC0ZiK" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Difusiones
Mira tus difusiones, a quién llegan, sus estadísticas, su costo y el resultado con cada contacto, cancela una que quedó pausada, borra una que todavía no salió y ordénalas en carpetas.
Tus difusiones y su audiencia
- Ves tus difusiones y las buscas por nombre, número, estado, carpeta, si salen en el momento o programadas, o entre dos fechas de envío. Con su
idves una entera: el número, la plantilla, la carpeta y los filtros de su audiencia (etiquetas, países, tablero y etapas, puntaje, campos personalizados). - Buscas los contactos que entrarían en una difusión con esos mismos filtros, o solo cuentas cuántos son.
- La API no crea, no lanza, no pausa ni reanuda difusiones: no hay llamada para eso. Ves las que ya tienes, las cancelas, las borras y las ordenas.
Sus resultados: estadísticas, costo, contactos y mensajes
- Las estadísticas de una difusión: entregados, leídos, respondidos, fallidos, pendientes, en cola, cancelados y omitidos (cuántos por cada motivo), y los clics en cada botón.
- Su costo: lo que se estimó antes de mandarla y lo calculado de lo que salió, por mercado, y si el dato todavía es parcial. Aparte, ves los tramos de costo y cuándo se actualizaron las tarifas.
- Sus contactos y el resultado con cada uno: el estado de su mensaje, el error si falló, si se omitió y por qué, y cuándo salió.
Cancelar y borrar
- Cancelas una difusión que está saliendo o que quedó pausada, para que no siga: se cierra para siempre, con fallos parciales, y te llega
broadcast.finishedcon el motivocancelled. En cualquier otro estado —también si está programada— la API responde409. - Una difusión programada no se cancela: se borra, mientras no llegue su hora de envío. Una que ya se envió o que está saliendo no se borra: la API responde
422.
Carpetas
- Ves tus carpetas de difusiones, con cuántas difusiones tiene cada una; creas una, le cambias el nombre o la borras.
- Mueves hasta 100 difusiones a una carpeta en una sola llamada.
Enterarte cuando una termina o se pausa
broadcast.finished: una difusión llegó a su final —enviada, fallida o con fallos parciales—, con el motivo y sus conteos. Llega una sola vez por difusión.broadcast.paused: una difusión se pausó sola, porque bajó la calidad del número, porque Meta pausó, desactivó o rechazó la plantilla, por un problema de pago de la cuenta de WhatsApp Business o porque Meta rechazó demasiados envíos. Si se reanuda y se vuelve a pausar, llega otro.- Cuando se pausa porque Meta rechazó demasiados envíos, el número además queda frenado (7 días, si no se configuró otro plazo): no puede crear, ejecutar ni reanudar difusiones, ni mandar plantillas a quien no le escribió en las últimas 24 horas.
Ten en cuenta
- Ver tus difusiones, sus resultados, su costo y sus carpetas pide que tu clave tenga Contactos y conversaciones → Ver. Buscar y contar contactos para una difusión, cancelar, borrar, y crear, editar o borrar carpetas y mover difusiones a una, Contactos y conversaciones → Editar (buscar y contar también piden Editar, no Ver). Para recibir los eventos, Contactos y conversaciones → Ver y, para crear el webhook, Avisos (webhooks) → Administrar.
- Para ver los mensajes de una difusión por resultado, usa
tab:all(todos),delivered(entregados),read(leídos),replied(respondidos),failed(fallidos) oskipped(omitidos). No filtres porstatus[]: es un filtro anterior, que además devuelve omitidos donde no los esperas. - El estado de una difusión viene como un número (
status):0pendiente (o programada),1saliendo,6terminada con fallos parciales (también una cancelada) y9pausada. Los demás no están descritos. - El conteo de contactos y los tramos de costo no tienen su respuesta descrita: lee lo que llega antes de depender de un campo.
- Las listas vienen por páginas, de hasta 100 a la vez.
Un ejemplo
Tus difusiones programadas:
curl "https://api.funnelchat.com/api/v1/broadcasts?send_type=scheduled" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Las estadísticas de una, con su id:
curl https://api.funnelchat.com/api/v1/broadcasts/bcs_A5b6U3qLB7DSV2TZUayo5Qr/statistics \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Los contactos que entrarían en una difusión a una etapa de un tablero:
curl -X POST https://api.funnelchat.com/api/v1/broadcasts/contacts \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kanban_setting_id": "knb_AD77AjVHX9JMsZN827QxGh9", "kanban_stage_ids": ["stg_AFQNmQUExx0MW4DNcQd3h0a"], "only_with_phone": true}'Campañas de grupos
Mira tus campañas de grupos, sus grupos, quién entra y quién sale, y cómo van sus pipelines y planes de operación.
Cómo funciona
- Ves tus campañas y abres una para ver su configuración: a dónde redirige, cómo reparte a las personas entre sus grupos, sus límites y sus condiciones.
- Ves los grupos de una campaña, con su estado y si su administrador está conectado, y los grupos de tu cuenta que se le pueden sumar.
- Ves el registro de entradas y salidas de toda la campaña: quién entró o salió, de qué grupo y cuándo.
- Sigues sus pipelines y sus planes de operación: cuántas acciones hay programadas, en curso, terminadas o con error.
- Ves las acciones que se corrieron sobre sus grupos y en qué grupos se aplicó cada una.
- Un webhook te dice cuándo una campaña se activa o se pausa (
campaign.status_changed), cuándo se queda sin grupos para las personas que entran por su link (campaign.no_groups_available) y cuándo termina un pipeline (pipeline.finished).
Ten en cuenta
- Todo esto pide que tu clave tenga Grupos y campañas → Ver, también para recibir los eventos. Para crear el webhook, además, Avisos (webhooks) → Administrar.
- Estas llamadas solo leen: no crean ni cambian campañas, pipelines ni planes, no las activan ni las pausan, y no suman grupos a una campaña.
- Con tu clave ves solo los grupos del workspace de la clave, y los totales de una campaña cuentan solo esos.
- La tasa de lectura de una campaña o de un grupo es solo del panel de Funnelchat: con tu clave no viene.
- Las listas vienen por páginas, de hasta 100 a la vez; las acciones de una campaña, de a 15.
Un ejemplo
Tus campañas:
curl "https://api.funnelchat.com/api/v1/campaigns?perPage=25" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Los grupos de una campaña, con su id:
curl https://api.funnelchat.com/api/v1/campaigns/cmp_A6RMvAOjr0mHuLr08RpcwWu/groups \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Envíos programados
Mira tus envíos programados a grupos, sus grupos, cómo salió cada uno en cada grupo, cada vez que salió uno que se repite, cuántos lo leyeron y qué respondieron, y entérate cuando termina o falla.
Cómo funciona
- Ves tus envíos programados, por carpeta o por estado, y abres uno para ver sus mensajes, su fecha, su audiencia y si se repite.
- Ves a qué grupos va y cómo salió en cada grupo: su estado, los intentos, quién lo mandó, los clics y si se editó. Con un envío que se repite, ves cada vez que salió —con cuántos grupos salió bien y con cuántos falló— y cómo salió en cada grupo esa vez.
- Ves cuántos lo leyeron o escucharon, las respuestas a sus encuestas y eventos, y las etiquetas que pone a quien responde.
- Un webhook te dice cuándo un envío termina (
scheduled_message.finished), cuándo falla en un grupo (scheduled_message.group_delivery_failed) y cuándo alguien responde una encuesta o un evento (scheduled_message.response_received).
Ten en cuenta
- Cada envío trae dos identificadores: su
id(smg_…), que es el que va en la ruta de las demás llamadas, y suuuid, que es el que traen los eventos. Para ir de un evento a su envío, busca en tus envíos el que tiene eseuuidy usa suid. - Por la API, los envíos programados solo se leen: no se pueden crear, editar ni cancelar. Para mandarle un mensaje a un grupo ahora, está Grupos.
- Todo esto pide que tu clave tenga Grupos y campañas → Ver, también para recibir los eventos. Para crear el webhook, además, Avisos (webhooks) → Administrar.
- Las listas vienen por páginas, de hasta 100 a la vez; los grupos de un envío, de a 3.
Un ejemplo
Tus envíos programados:
curl "https://api.funnelchat.com/api/v1/scheduled-messages?perPage=25" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Cómo salió uno en cada grupo, con su id:
curl https://api.funnelchat.com/api/v1/scheduled-messages/smg_Ap5avHiKWWEBpqsQuJLOBCt/group-messages \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Estadísticas de tus grupos
Mira cuántas personas entran y salen de tus grupos y campañas, cuántas están activas, tus grupos por estado, los clics en tus links y de qué países son.
Cómo funciona
- Ves las entradas y salidas de participantes por hora, día o mes, de tus grupos o de tus campañas.
- Ves cuántos participantes están activos e inactivos, y cuántos grupos tienes en cada estado a lo largo del tiempo.
- Ves los clics en los links de tus grupos y campañas, y el registro de cada clic: país, dispositivo, navegador y de dónde vino.
- Ves las métricas por país: contactos, clics, entradas, tasa de entrada y salidas, de cada país y en total.
- Un webhook te manda cada día el reporte de tu cuenta, con los clics, las entradas y las salidas (
daily_report.generated).
Ten en cuenta
- Todo esto pide que tu clave tenga Grupos y campañas → Ver, también para recibir el evento. Para crear el webhook, además, Avisos (webhooks) → Administrar.
- Con tu clave, las estadísticas por período (entradas y salidas, activos, grupos por estado y clics) piden
start_dateyend_dateen formatoAAAA-MM-DD, con hasta 366 días entre las dos. Si falta una o el rango es mayor, la API responde422. - El registro de clics puede traer el teléfono, el email y el nombre de quien hizo clic: son datos personales.
- Las estadísticas solo leen: no cambian nada.
Un ejemplo
Las entradas y salidas de tus grupos por día, en octubre:
curl "https://api.funnelchat.com/api/v1/stats/participants?start_date=2026-10-01&end_date=2026-10-31&unit=day" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Puntaje de tus contactos
Mira el puntaje de tus contactos y cómo se reparte, ajusta el de uno y configura cómo se calcula.
Cómo funciona
- En la API, el puntaje se llama lead score:
lead_scoreen los campos y filtros,lead-scoreen las rutas. - Cada contacto tiene un puntaje y una categoría: caliente (
hot), tibio (warm), frío (cold) o sin datos suficientes (insufficient_data). - Ves el de un contacto: su puntaje, su categoría, cuántas señales lo explican, si está descalificado y por qué, y las señales que lo movieron. También ves cómo se reparte en tu cuenta: cuántos contactos hay en cada categoría y con qué umbrales.
- Ajustas a mano el de un contacto, sumando o restando hasta 100 puntos, con un motivo.
- Ves cómo se calcula —los umbrales de cada categoría, las señales mínimas, el decaimiento con los días y las reglas— y lo configuras. Y filtras por puntaje tus contactos, tus conversaciones, los contactos de una etapa y la audiencia de una difusión.
Ten en cuenta
- Ver el puntaje, cómo se reparte y cómo se calcula pide que tu clave tenga Contactos y conversaciones → Ver; configurarlo y ajustar el de un contacto, Contactos y conversaciones → Editar.
- «Configurar el puntaje» reemplaza toda la configuración de una vez: mandas todos sus datos, también los que no cambian. Solo lo hace la clave del titular de la cuenta.
- Los umbrales van de 0 a 100, y el de tibio tiene que ser menor que el de caliente. Las señales mínimas, de 1 a 20; el margen para cambiar de categoría (
hysteresis), de 0 a 25; y hasta 5 pasos de decaimiento, cada uno con sus días (de 1 a 365, cada paso más que el anterior) y los puntos que resta (de -100 a -1). - Cada regla dice qué señal suma o resta puntos (una etiqueta agregada o quitada, avanzar de etapa, responder una difusión o un mensaje, una palabra clave, entrar o salir de un grupo, una reacción o un voto en un grupo, un clic en un link o una automatización completada), cuántos (de -100 a 100), con qué tope por día y si descalifica al contacto.
- Los filtros por puntaje van de 0 a 100.
- El puntaje de un contacto trae
next_cursoryhas_more, pero la especificación no dice cómo pedir las señales siguientes.
Un ejemplo
El puntaje de un contacto:
curl https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/lead-score \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Súmale 10 puntos, con el motivo:
curl -X POST https://api.funnelchat.com/api/v1/contacts/ctc_ABViuUDF93I2VL1tInstRDG/lead-score/adjustments \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"delta": 10, "reason": "Pidió una demo por teléfono"}'Ventas
Mira las ventas que registran tus plataformas de pagos, sus métricas, el embudo de conversaciones a compras, las ventas por plataforma y los productos de cada una.
Cómo funciona
- Ves tus ventas una por una: cuándo, de qué plataforma, qué producto, de qué tipo, el monto y la moneda, el comprador y la atribución.
- Ves sus métricas: compradores distintos, la tasa de recompra y lo vendido por moneda.
- Ves el embudo: conversaciones, contactos calificados y compras.
- Ves las ventas por plataforma, con cuáles están conectadas, y los productos de una plataforma.
- Todo en una ventana (
window) de los últimos7,30o90días, contando hoy, y filtrado por tipo de evento: aprobada, pendiente, rechazada, cancelada, reembolsada, contracargo o carrito abandonado.
Ten en cuenta
- Todo pide que tu clave tenga Contactos y conversaciones → Ver. Estas llamadas solo leen: la API no conecta plataformas de pagos ni registra ventas.
- Si no mandas la ventana, son 30 días; otro valor que no sea
7,30o90responde422. Los días se cuentan en la zona horaria de tu cuenta. - Los montos vienen como enteros en la unidad menor de su moneda (
amount_minor,total_minor): centavos, salvo en las monedas sin decimales, como el peso chileno o el colombiano, donde son unidades. Cada monto trae su moneda, y los totales vienen por moneda, sin convertir. Un reembolso es una venta aparte, negativa. - La especificación no dice qué valores acepta la plataforma de «Ver los productos de una plataforma de pagos».
- No hay eventos de ventas: para enterarte de las nuevas, consulta la lista cuando lo necesites.
Un ejemplo
Tus ventas de la ventana de 30:
curl "https://api.funnelchat.com/api/v1/sales?window=30" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"El embudo de la misma ventana:
curl "https://api.funnelchat.com/api/v1/sales/funnel?window=30" \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Dominios propios
Usa un dominio tuyo, como go.mimarca.com, para el servicio de redirección de Funnelchat: lo registras, creas en tu DNS los registros que te indica, lo verificas y lo borras cuando ya no lo usas.
Cómo funciona
- Registras el dominio y la respuesta te da los registros que tienes que crear en su DNS, con lo que hace cada uno, y una pista de dónde está tu DNS.
- Funnelchat comprueba el dominio solo, cada tanto. Si ya creaste los registros, lo verificas en el momento.
- Su estado va de
PENDING_DNSaPENDING_SSLyACTIVE, oFAILEDsi algo no anda. - El certificado se valida por
HTTP, cuando el registro del dominio ya apunta. Si todavía no puede apuntar, lo cambias aTXTy creas también el registro TXT. - Ves tus dominios con su estado y sus registros, y borras uno cuando ya no lo usas.
Ten en cuenta
- Ver pide que tu clave tenga Números de WhatsApp → Ver; registrar, verificar y cambiar la validación, Números de WhatsApp → Editar; borrar, Números de WhatsApp → Crear, conectar y borrar.
- El dominio se guarda en minúsculas y sin
https://ni ruta:https://Go.MiMarca.com/landingygo.mimarca.comson el mismo. Uno que ya está registrado no se registra otra vez. - La verificación puede tardar unos minutos: si todavía no está
ACTIVE, vuelve a verificar más tarde. - Borrar un dominio lo deja sin funcionar en el momento. Para volver a usarlo hay que registrarlo de nuevo.
No se puede deshacer
El dominio propio se borra y deja de usarse de inmediato.
Un ejemplo
Registra tu dominio y, después de crear en tu DNS los registros que te dio, verifícalo con su id:
curl -X POST https://api.funnelchat.com/api/v1/custom-domains \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"hostname": "go.mimarca.com"}'
curl -X POST https://api.funnelchat.com/api/v1/custom-domains/dom_Av1pnwIr4tBmDHX5FCLBVpq/verify \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Tu cuenta y tu equipo
Mira tu cuenta y su plan, tu consumo de contactos activos y las personas de tu equipo, y entérate de tus cobros, tu suscripción y tu límite de contactos activos.
Cómo funciona
- Ves la cuenta dueña de tu clave: su nombre, su plan y sus límites, cuántos números y agentes tiene el workspace de tu clave y el cupo de números que se le aplica cuando creas uno. Si el workspace paga su propio plan, el plan, sus límites y el saldo de contactos activos son los de ese workspace; si no, los de la cuenta.
- Ves tu consumo de contactos activos del ciclo: cuántos llevas, tu límite, cuántos te quedan y el porcentaje. También la lista de tus contactos activos y su historial.
- Ves las personas de tu equipo, con búsqueda por nombre, y los datos de una.
- Un webhook te dice cuándo llegas al 80 % (
mac.usage_80) o al 100 % (mac.usage_100) de tus contactos activos, cuándo hay contactos activos por vencer (mac.expiring) y cuándo la cuenta se bloquea (account.blocked). - Otros te dicen lo de tu suscripción: un cobro que se acerca (
billing.upcoming_charge), un pago que falló (billing.payment_failed), el final de la prueba (subscription.trial_ending) o de la pausa de tu cuenta (subscription.dormant_ending), una cancelación confirmada (subscription.cancellation_confirmed) o una cancelación que se revirtió (subscription.reactivated).
Ten en cuenta
- Ver tu cuenta pide que tu clave tenga Números de WhatsApp → Ver; tus contactos activos y tu equipo, Contactos y conversaciones → Ver. Para recibir estos eventos, Números de WhatsApp → Ver y, para crear el webhook, Avisos (webhooks) → Administrar.
- Con tu clave, tu cuenta no trae el email, el teléfono ni las fechas de inicio de sesión de su dueño, ni datos de cobro, ni datos de otros workspaces.
- Si agotas tus contactos activos del ciclo, tienes 24 horas de gracia. Si no se regulariza, la cuenta se bloquea y, mientras dura el bloqueo, los envíos con tu clave se rechazan.
- Algunos eventos de cobro y de suscripción llegan solo con ciertas formas de pago: lo dice cada uno en Webhooks.
- La facturación no está en la API: no se paga ni se cambia el plan con una clave.
Un ejemplo
Tu cuenta y tu consumo de contactos activos:
curl https://api.funnelchat.com/api/v1/me \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"
curl https://api.funnelchat.com/api/v1/mac/status \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Un webhook para enterarte cuando te acercas al límite de contactos activos y si la cuenta se bloquea:
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": ["mac.usage_80", "mac.usage_100", "account.blocked"]}'Alertas
Mira las alertas de tu operación y los teléfonos y webhooks que las reciben, elige qué alerta le llega a cada uno, y configura el horario de silencio y el reporte diario.
Cómo funciona
- Ves las alertas que hay: de tus números, tus contactos activos, tus cobros y tu suscripción, tus campañas, grupos y difusiones, cada una con su nombre, su explicación y si es crítica.
- Ves los destinos de tus alertas —los teléfonos y los webhooks que las reciben—, con las alertas que tiene prendidas cada uno.
- Para cada destino prendes o apagas cada alerta, una por una.
- Pones un horario de silencio (puede cruzar la medianoche) y configuras el reporte diario: si sale, a qué hora y con qué campañas.
Ten en cuenta
- Ver pide que tu clave tenga Números de WhatsApp → Ver; prender o apagar alertas y configurar el silencio y el reporte, Números de WhatsApp → Editar.
- Con tu clave ves los destinos del workspace de la clave, y el teléfono de cada uno sale tapado: solo ves sus últimos cuatro dígitos (
****1234). - Por la API no se crean, editan, verifican ni borran destinos: ves los que hay y eliges qué alertas les llegan. Para prender alertas en un teléfono, tiene que estar verificado.
- El horario de silencio y el reporte diario son uno solo para toda la cuenta. Las campañas que puedes elegir para el reporte son las del workspace por defecto, y con una clave esa llamada solo la usa una clave de ese workspace.
- Las alertas no son los webhooks de Funnelchat: lo que llega a un destino webhook tiene otro formato y otra configuración. Para recibir eventos en tu servidor, crea un webhook.
Un ejemplo
Tus destinos, con las alertas que tiene prendidas cada uno:
curl https://api.funnelchat.com/api/v1/alerts/destinations \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Prende una alerta en un destino, con su id y el module y la action que copias de «Ver las alertas que hay»:
curl -X PUT https://api.funnelchat.com/api/v1/alerts/destinations/ald_Atlwq6tfM6G0SC3Hu6slnUc/settings \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"module": "device", "action": "disconnected", "enabled": true}'Más sobre tus webhooks
Mira uno de tus webhooks y sus entregas, edítalo o páusalo y consulta los tipos de evento que hay.
Cómo funciona
- Crear un webhook, ver los tuyos, probarlo y borrarlo están en Webhooks, con la tabla de todos los eventos. Con «Ver los tipos de evento» los consultas por la API, con un ejemplo del cuerpo de cada uno.
- Con «Ver un webhook» ves su dirección, sus eventos, su estado y cuándo fue su última entrega y la última que salió bien. El secreto no vuelve a aparecer.
- Con «Editar un webhook» le cambias la dirección, los eventos o la descripción, y lo pausas o lo reactivas.
- Con «Ver las entregas de un webhook» ves cada intento, del más nuevo al más viejo: si salió bien, qué respondió tu servidor y cuánto tardó. Así sabes por qué no te llega algo.
Ten en cuenta
- Ver un webhook y sus entregas pide que tu clave tenga Avisos (webhooks) → Ver; editarlo, Avisos (webhooks) → Administrar. Además, para cada uno de sus eventos, el permiso de lectura de su área (Números de WhatsApp → Ver, Contactos y conversaciones → Ver o Grupos y campañas → Ver): si le falta uno, la API responde
403y no cambia nada. «Ver los tipos de evento» pide Números de WhatsApp → Ver. - Editar reemplaza la dirección, los eventos, la descripción y los filtros (
filters): mándalos todos como tienen que quedar, no solo lo que cambia. - Si cambias la dirección con tu clave, el webhook queda atado a esa clave: si la revocas, deja de recibir eventos y no se puede reactivar; tienes que crear uno nuevo.
- Si las entregas fallan varias veces seguidas, el webhook se deshabilita solo. Arregla tu servidor, reactívalo editándolo y pruébalo. El secreto se rota desde el panel.
- Mientras está pausado o deshabilitado, lo que estaba por llegarle se descarta, también los reintentos: al reactivarlo no se manda. En sus entregas lo ves como pausado o deshabilitado.
- Un webhook puede tener un filtro por campañas de grupos: los eventos de salud, calidad, límite y nombre visible de tus números no le llegan, porque no son de ninguna campaña.
Un ejemplo
Las últimas entregas de uno de tus webhooks, con su id:
curl https://api.funnelchat.com/api/v1/webhooks/$WEBHOOK_ID/deliveries \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"Páusalo: léelo y mándalo igual que estaba, con status en paused:
curl https://api.funnelchat.com/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY"
curl -X PUT https://api.funnelchat.com/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $FUNNELCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://tu-servidor.example/funnelchat", "events": ["message.received", "message.status_changed"], "description": "Mi CRM", "filters": {}, "status": "paused"}'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—.
Límites y errores
Cuántas llamadas puedes hacer por día y por minuto, qué hacer ante cada 429 y los errores que comparte toda la API.