API de Chakra Chat: guía completa para desarrolladores sobre la automatización de WhatsApp

En resumen: La API de Chakra Chat funciona sobre WhatsApp Cloud API y agrega lo que el acceso directo a Meta no ofrece de forma predeterminada: claves de API con permisos según el rol, un formato de webhook más sencillo junto con el paso directo de todos los datos de Meta, administración integrada de leads y campañas, endpoints para llamadas y una capa más amplia de Platform/CRM (procesos, tareas y usuarios) para crear flujos de trabajo reales, no solo enviar mensajes. Esta guía cubre la autenticación (claves de API, roles y tokens Bearer), las seis áreas de funcionalidades en torno a las que se organiza la API, los límites de frecuencia (200 llamadas/minuto), el funcionamiento de los webhooks entrantes y la validación HMAC, cuándo usar el SDK oficial de TS/JS en lugar de llamadas HTTP directas, y los patrones de integración —sincronización con CRM, activadores de automatización mediante herramientas como n8n, plataformas de comercio electrónico como Shopify y envíos masivos— que abarcan la mayoría de los casos de uso reales. Esta es la guía que debes leer antes de abrir la documentación de la API a nivel de endpoint : explica el porqué y la estructura del sistema, no solo las llamadas individuales.

Introducción

Si estás evaluando la API de Chakra Chat, probablemente ya consultaste directamente la documentación de WhatsApp Cloud API y te preguntas qué aporta realmente una capa BSP. Esta guía responde esa pregunta y luego explica los aspectos prácticos: autenticación, arquitectura, límites de frecuencia, webhooks, el SDK y los patrones de integración que la mayoría de los desarrolladores termina creando. Para obtener detalles a nivel de endpoint (esquemas de solicitud y respuesta, parámetros), consulta la documentación de la API de Chakra junto con esta guía.

Qué permite hacer la API de Chakra frente al uso directo de WhatsApp Cloud API

Cloud API de Meta es la capa fundamental: es lo que realmente envía y recibe mensajes de WhatsApp, administra plantillas y gestiona la infraestructura de números de teléfono. Todos los proveedores de soluciones de WhatsApp Business, incluido Chakra, se basan en ella. Entonces, ¿por qué no integrarse directamente con Meta?

Para algunos equipos, esa es una opción razonable. Pero integrarse directamente implica hacerse cargo de todo lo que Meta no ofrece de forma nativa: la verificación del negocio y el proceso de incorporación, las herramientas para aprobar plantillas, una bandeja de entrada que el equipo pueda usar sin conocimientos técnicos y, algo fundamental para todo lo que vaya más allá de un único flujo automatizado, la lógica empresarial complementaria, como el seguimiento de leads, la administración de campañas y el registro de datos al estilo CRM, conceptos que no existen en la API de Meta.

Lo que la API de Chakra agrega al acceso directo a Cloud API:

• Tanto el paso directo de los datos como un formato de webhook más sencillo. Puedes recibir directamente eventos en el formato original de Meta o usar un formato de eventos normalizado de Chakra, más fácil de manejar. Tú decides según el caso de uso.
• Claves de API con permisos según el rol en lugar de una sola credencial para toda la cuenta, para que cada integración (una sincronización con Shopify, una automatización de n8n o un panel interno) tenga únicamente los permisos que realmente necesita.
• Una capa de Leads y Campaigns : endpoints específicos para crear y actualizar leads y administrar campañas de leads, en lugar de tener que crear tú mismo ese modelo de datos sobre eventos de mensajería sin procesar.
• Una capa de Platform/CRM : Processes, Tasks, Users y Background Jobs, que te brinda recursos genéricos para flujos de trabajo y registro de datos, además de los endpoints específicos de WhatsApp. Son útiles cuando la integración con WhatsApp es una parte de un sistema operativo más amplio.
• Endpoints de la API de llamadas para la capacidad de llamadas de voz de WhatsApp —configuración, permisos y gestión de llamadas— como un área de funcionalidades compatible de forma nativa, en lugar de algo añadido por separado.
• Una bandeja de entrada compartida y herramientas para usuarios sin conocimientos técnicos dentro de la misma cuenta, así que la API no es la única forma de acceder al sistema: los equipos de soporte y marketing trabajan en la misma plataforma con la que se integran tus sistemas.

Cuándo podría tener sentido integrarse directamente con Meta: si estás creando infraestructura a gran escala con un equipo de plataforma dedicado, o si necesitas usar las funciones de Cloud API en cuanto Meta las lance, antes de que cualquier capa BSP las incorpore. Para la mayoría de los equipos de producto y crecimiento —cualquiera que cree automatizaciones, sincronizaciones con CRM o flujos orientados al cliente sin querer hacerse cargo de toda la infraestructura de mensajería—, una API BSP como la de Chakra es una opción más rápida y requiere menos mantenimiento.

Autenticación: claves de API, roles y tokens Bearer

Todas las llamadas a la API de Chakra se autentican con una clave de API, y la configuración está diseñada intencionalmente para aplicar el principio de privilegio mínimo, en lugar de usar una única credencial con acceso total.

Cómo crear una clave de API:

1. Ve a la sección de claves de API de tu cuenta de Chakra Chat.
2. Asígnale un nombre descriptivo : con el tiempo, probablemente tendrás varias claves, y nombrarlas según el caso de uso ("n8n-support-bot", "shopify-order-sync") facilitará mucho su administración más adelante en comparación con los nombres genéricos.
3. Agrega una descripción opcional para incluir más contexto.
4. Asigna un rol de acceso. La clave hereda exactamente los permisos del rol asignado, ni más ni menos.

Cómo usar la clave: una vez creada, abre los detalles de la clave y busca la sección Access Tokens . El token que aparece ahí es el que debes enviar como token Bearer en el encabezado Authorization de cada solicitud a la API:

Authorization: Bearer {your_access_token}

La pauta más importante en la práctica: asigna siempre a las claves el nivel mínimo de permisos que realmente necesite el caso de uso. Algunas prácticas concretas que se desprenden de esto:

• Usa claves separadas para cada integración, no una sola clave compartida para todas las automatizaciones. Si una integración específica se ve comprometida o funciona mal, una clave con permisos limitados restringe el impacto a los permisos de esa integración.
• Ten especial cuidado con las claves expuestas en el frontend. Cualquier clave de API que se use en código del lado del cliente es visible para quien inspeccione el tráfico de red: estas claves deben tener los privilegios mínimos posibles e, idealmente, nunca deben tener permisos de escritura para operaciones sensibles, como la mensajería o los datos de clientes potenciales.
• Revisa periódicamente los roles de las claves, especialmente a medida que evolucionan las integraciones: a veces, una clave creada para un caso de uso inicial limitado asume responsabilidades más amplias con el tiempo, sin que se vuelva a revisar su rol.

Arquitectura de API: las seis áreas de capacidad

La API de Chakra se organiza en torno a seis áreas prácticas de capacidad. Entender esta estructura desde el principio facilita mucho encontrar el endpoint adecuado más adelante, en lugar de tener que buscar cada vez en toda la documentación de referencia.

1. Mensajería — enviar y recibir mensajes reales de WhatsApp. Esto abarca mensajes de sesión (de formato libre, dentro de la ventana de 24 horas), la carga y recuperación de archivos multimedia, la gestión de claves de WhatsApp Flows y la gestión de Groups (crear, listar y administrar participantes y solicitudes para unirse). Aquí están disponibles tanto una ruta de transferencia directa en formato Meta como los endpoints de mensajes nativos de Chakra.

2. Plantillas — crear, listar y actualizar plantillas de mensajes de WhatsApp, además de endpoints específicos para enviar mensajes con plantillas a un número de teléfono determinado o en el contexto de un Process (consulta la sección Plataforma más abajo). El envío de plantillas y la gestión de plantillas están deliberadamente separados en grupos de endpoints distintos, ya que el ciclo de vida de creación y gestión (sujeto al proceso de aprobación de Meta) es diferente del envío de una plantilla que ya fue aprobada.

3. Clientes potenciales — crear y actualizar registros de clientes potenciales por número de teléfono, lo que te ofrece una forma estructurada de dar seguimiento a prospectos y clientes vinculados a conversaciones de WhatsApp, sin tener que crear ese modelo de datos desde cero sobre los datos sin procesar de los chats.

4. Campañas — agregar o quitar números de teléfono de campañas de clientes potenciales, el componente básico para crear secuencias salientes estructuradas (flujos de nutrición de prospectos y segmentos de difusión), en lugar de enviar mensajes puntuales.

5. Llamadas — la interfaz de la API de WhatsApp Calling: consultar y configurar los ajustes de llamadas de un número de teléfono, verificar el estado del permiso para llamar (si un contacto determinado concedió permiso para recibir llamadas iniciadas por una empresa) y administrar llamadas activas.

6. Plataforma/CRM — la capa genérica de flujos de trabajo: Processes (crear, actualizar, listar, realizar operaciones masivas y eliminar; en esencia, registros estructurados configurables), Tasks, Users, Photos y Background Jobs. Esta parte de la API no es específica de WhatsApp: es un conjunto ligero de elementos básicos de CRM y flujos de trabajo que complementa la capacidad de mensajería. Es útil cuando quieres que la integración de WhatsApp y tus datos operativos generales estén en el mismo sistema, en lugar de conectarlos entre herramientas separadas.

Además de estas seis áreas, vale la pena conocer otras dos áreas de apoyo: Chats y mensajes de chat (listar chats y el historial de mensajes de un número de teléfono o una conversación; útil para crear vistas personalizadas de la bandeja de entrada o llevar contexto a otro sistema) y Acceso de socios (creación de Connect Token y gestión de la configuración de complementos de WhatsApp/WABA; relevante si desarrollas sobre Chakra como socio integrado, en lugar de crear una integración para una sola cuenta).

Límites de frecuencia y lo que significan en la práctica

Chakra aplica un límite de 200 llamadas a la API por minuto. Este es el número que debes tener en cuenta al diseñar tu solución, no solo conocerlo.

En la práctica, esto significa lo siguiente:

• Las operaciones masivas requieren lotes, no fuerza bruta. Si sincronizas una lista grande de clientes potenciales o envías una difusión a miles de destinatarios, organiza el trabajo en lotes con pausas incorporadas, en lugar de enviar cada solicitud tan rápido como pueda ejecutarse tu código.
• Implementa el manejo de reintentos con espera progresiva. Cualquier integración que realice llamadas frecuentes debe gestionar correctamente las respuestas de límite de frecuencia: reintenta con una espera progresiva, en lugar de hacer fallar toda la operación o volver a saturar la API inmediatamente después de recibir una respuesta de límite.
• Las arquitecturas basadas en webhooks suelen mantenerse por debajo del límite en la mayoría de los casos de uso, ya que reaccionan a eventos entrantes en lugar de consultar datos periódicamente. Esta es otra razón para preferir los webhooks (que se explican a continuación) a los patrones de consulta periódica en tareas que requieren muchas lecturas, como comprobar si hay mensajes nuevos o actualizaciones de estado.
• Los trabajos de difusión o sincronización de alto volumen deben ejecutarse como trabajos en segundo plano, no dentro de una solicitud dirigida al usuario. Los endpoints de Background Jobs de la capa Plataforma existen, en parte, por esta razón: te permiten dar seguimiento a operaciones por lotes de larga duración sin quedar bloqueado en tiempo real por el límite de 200 llamadas por minuto.

Webhooks: eventos entrantes y qué puedes hacer con ellos

WhatsApp —y, por extensión, la API de Chakra— funciona de forma asíncrona. Cuando envías un mensaje, la API acepta la solicitud y luego publica eventos que indican si se envió, se entregó, se leyó o falló. Los mensajes entrantes de los clientes también se reciben como eventos, no mediante consultas periódicas. Por eso, los webhooks son la base de cualquier integración en tiempo real.

Hay dos tipos distintos de webhook, y es importante elegir el adecuado:

Webhook de eventos de transferencia directa — envía el formato de evento sin procesar de Meta directamente a tu endpoint, sin modificarlo. Incluye mensajes entrantes, eventos de estado, notificaciones de actualización de plantillas y actualizaciones a nivel de cuenta. Configúralo desde la pestaña "Más" de la página Configuración de WhatsApp, en el campo de URL del webhook de transferencia directa. Como el formato coincide exactamente con la documentación de Meta, es la opción adecuada si ya conoces las cargas útiles de Cloud API o necesitas acceder a tipos de eventos que no cubre el formato normalizado.

Webhook de eventos de Chakra — ofrece un formato más sencillo y normalizado para un conjunto seleccionado de tipos de eventos. Se configura desde la misma página Configuración de WhatsApp, activando "Chakra Webhooks" y seleccionando los tipos de eventos que quieres recibir. Los eventos llegan con dos claves coherentes: event (una de message, status, message_echoo smb_message_echo) y payload (los datos correspondientes del mensaje o del estado de entrega). Es la mejor opción predeterminada para la mayoría de las integraciones, ya que no tienes que analizar toda la estructura anidada de eventos de Meta para casos de uso sencillos, como «avísame cuando responda un cliente».

Un ejemplo de evento de mensaje de texto entrante (formato de transferencia directa) permite hacerse una idea de la estructura con la que trabajarás:

{  "object": "whatsapp_business_account",  "entry": [{    "id": "83784929738012",    "changes": [{      "value": {        "messaging_product": "whatsapp",        "metadata": { "display_phone_number": "917259775805", "phone_number_id": "694794789348887" },        "contacts": [{ "profile": { "name": "John" }, "wa_id": "919911223344" }],        "messages": [{          "from": "919911223344",          "id": "wamid.xxxx",          "timestamp": "1756322278",          "text": { "body": "Hi, can you please help me out with an issue" },          "type": "text"        }]      },      "field": "messages"    }]  }]}

Protege tu webhook con la validación HMAC. Como los endpoints de webhook deben ser accesibles públicamente y no cuentan con un requisito de autenticación integrado, es importante verificar que las solicitudes entrantes realmente se hayan originado en Chakra. El proceso es el siguiente:

1. Configura un secreto HMAC en Admin → Team → Secrets en tu cuenta de Chakra. Una vez configurado, cada evento de webhook incluirá un encabezado X-Chakra-Signature-256 .
2. En tu sistema, calcula un hash HMAC-SHA256 de la cadena sin procesar del cuerpo de la solicitud (no de un objeto JSON analizado y vuelto a serializar: muchos frameworks HTTP transforman el cuerpo, lo que invalida la comparación) usando tu secreto como clave.
3. Compara el hash que calculaste con el valor de X-Chakra-Signature-256 (nota: el valor del encabezado no lleva el prefijo sha256= , a diferencia de las convenciones de otros proveedores). Si coinciden, el contenido es auténtico y no ha sido alterado.

💡 Saltarte este paso significa que cualquiera que descubra la URL de tu webhook podría enviarle eventos falsificados. Considéralo un paso obligatorio para cualquier integración en producción, no una medida de seguridad opcional.

El SDK: cuándo usarlo y cuándo hacer llamadas directas a la API

Chakra publica un SDK oficial de TypeScript/JavaScript, @chakrahq/chakra-chat-sdk, que se puede usar en entornos de JavaScript tanto del lado del servidor como del cliente.

npm i @chakrahq/chakra-chat-sdk

Todas las solicitudes realizadas mediante el SDK se autentican con el mismo token de acceso Bearer que se usa para las llamadas directas a la API. Se proporciona una sola vez al inicializarlo, en lugar de tener que adjuntarlo manualmente a cada llamada.

Cuándo conviene más usar el SDK:

• Estás desarrollando en un entorno Node.js o JavaScript/TypeScript y prefieres estructuras tipadas para solicitudes y respuestas, en lugar de crear llamadas HTTP y analizar JSON sin procesar por tu cuenta.
• Llamas a varios endpoints dentro del mismo servicio y quieres usar un único cliente inicializado, en lugar de repetir la lógica de los encabezados de autenticación en todas partes.
• Quieres avanzar más rápido durante el desarrollo inicial y te parece bien el ritmo de publicación del SDK para los endpoints más nuevos.

Cuándo tienen más sentido las llamadas HTTP directas:

• Estás integrando desde un entorno que no usa JS (Python, Ruby, Go o una herramienta de bajo código, como el nodo HTTP Request de n8n): puedes usar toda la API mediante solicitudes HTTP simples. De hecho, este es el patrón más común para las integraciones con plataformas de automatización, ya que herramientas como n8n funcionan de forma nativa con nodos HTTP en lugar de importar un paquete npm.
• Necesitas un endpoint disponible en la API directa, pero que aún no esté incluido en la versión actual del SDK.
• Estás creando una integración sencilla y puntual, y no vale la pena agregar una dependencia completa del SDK para hacer unas pocas llamadas.

En la práctica, la mayoría de los equipos termina usando ambos: el SDK para un servicio central de backend que se comunica con Chakra con regularidad, y las llamadas HTTP directas para integraciones más sencillas, como flujos de trabajo de plataformas de automatización o funciones sin servidor activadas por webhooks.

Patrones de integración comunes

Sincronización con CRM. Usa los endpoints de Leads (Create a lead, Update Lead By Phone Number) para mantener sincronizado el registro de un cliente o prospecto a medida que avanzan las conversaciones de WhatsApp. Si quieres hacer seguimiento de registros estructurados y del estado de los flujos de trabajo en el mismo sistema, en lugar de intercambiar datos con un CRM externo cada vez que hay una actualización, combínalos con los endpoints Process/Task de la capa Platform.

Activadores de automatización mediante n8n. Un patrón común: configura el webhook de transferencia para que apunte a un nodo de activación de webhook de n8n, filtra los eventos de mensajes, envía el contenido del mensaje a un nodo AI Agent (o a cualquier lógica de procesamiento) y luego envía la respuesta mediante un nodo HTTP Request que se conecte directamente al endpoint de mensajes:

POST https://api.chakrahq.com/v1/ext/plugin/whatsapp/{pluginId}/api/v22.0/{whatsappPhoneNumberId}/messagesAuthorization: Bearer {chakraAccessToken}Content-Type: application/json

Los valores de pluginId y whatsappPhoneNumberId están disponibles en la página de configuración de WhatsApp de tu cuenta de Chakra: el ID del plugin está en el menú de tres puntos junto a Save, y el ID de Meta del número de teléfono está en el ícono de engranaje junto a la lista de números de teléfono. Este patrón —recibir un webhook, procesarlo y hacer una llamada HTTP— se aplica también a otras herramientas de automatización de flujos de trabajo, además de n8n, siempre que admitan activadores de webhook y nodos de solicitud HTTP.

Automatización del ciclo de vida de los pedidos de comercio electrónico (integración tipo Shopify). En lugar de crearla a partir de webhooks sin procesar, las plataformas como Shopify suelen conectarse mediante una capa de sincronización sin código que asigna automáticamente los eventos del ciclo de vida del pedido (creado, preparado, enviado, entregado) al envío de mensajes de plantilla, además de enviar los eventos de abandono del proceso de pago a secuencias de plantillas para recuperar carritos. En el caso de plataformas de comercio electrónico personalizadas o que no sean Shopify y no tengan una integración nativa, puedes implementar el mismo patrón directamente en la API: un webhook de estado del pedido de tu plataforma activa un controlador del lado del servidor que llama al endpoint de envío de plantillas con las variables correspondientes completadas con los datos del pedido.

Envío masivo mediante la API. Para enviar una plantilla de Marketing o Utility a un segmento de contactos —en lugar de responder a una sola conversación—, el patrón es el siguiente: crea la lista de destinatarios (a menudo mediante los endpoints de Campaigns, agregando números de teléfono a una campaña de leads) y luego recorre la lista para enviar la plantilla mediante el endpoint correspondiente, respetando el límite de velocidad de 200 llamadas por minuto con procesamiento por lotes y retroceso exponencial, como se explicó anteriormente. Para listas grandes, ejecutar esto como un trabajo en segundo plano en lugar de hacerlo en un bucle síncrono permite que la operación tolere mejor los errores parciales y las pausas por límites de velocidad.

Cómo continuar

Esta guía abarca la arquitectura y los fundamentos: los detalles de cada endpoint (cuerpos exactos de las solicitudes, esquemas de respuesta y la lista completa de operaciones disponibles en cada área funcional) están en la documentación de la API de Chakra. Te recomendamos guardar algunos documentos en tus marcadores mientras comienzas a desarrollar:

• Claves de API — creación y configuración de permisos para las claves
• Webhook de eventos entrantes — referencia completa de webhooks y validación HMAC
• Límites de velocidad de la API
• SDK de Chakra Chat
• Cómo encontrar pluginId y whatsappPhoneNumberId — necesarios para la mayoría de las integraciones HTTP directas

Si quieres seguir un tutorial práctico para crear una automatización específica, las guías de integración de AI Agent con n8n y de integración de Shopify se basan directamente en los conceptos que se explican aquí. Empieza con esta guía para entender la estructura del sistema y luego sigue esas guías para crear una integración concreta paso a paso.