Compatibilidad con Webhook & API - Preguntas frecuentes
Preguntas frecuentes sobre el uso de las API de Chakra Chat y los webhooks entrantes.
Incluye webhooks de eventos entrantes (de transferencia directa y en formato Chakra), firma HMAC, recuperación del historial de mensajes, coexistencia e idempotencia del envío.
1. Comportamiento general de los webhooks
¿Los webhooks admiten reintentos, colas o procesamiento por lotes? ¿Cuál es el plazo y el cuerpo de respuesta requeridos para confirmar correctamente la recepción?
No existe una política de reintentos ni de colas para los webhooks de transferencia directa ni para los webhooks de Chakra. La confirmación correcta es una respuesta HTTP 200, sin necesidad de un cuerpo de respuesta, y debe devolverse en menos de 200 ms. Referencia: Documentación de Webhooks de eventos entrantes
¿Se pueden procesar los eventos de webhook por lotes, duplicar o entregar fuera de orden? ¿Las entregas duplicadas son idénticas byte por byte y cada entrega tiene una firma HMAC independiente?
No se admite el procesamiento por lotes y los eventos pueden llegar fuera de orden. Referencia: Webhook de eventos entrantes — sección Validación de HMAC
¿Qué límites se aplican al tamaño del cuerpo del webhook, al tamaño de los lotes, a la simultaneidad y al rendimiento de entrega?
No se publican límites. Se espera un uso razonable.
¿Cuál es la latencia de los eventos de webhook al suscribirse a los webhooks?
La latencia histórica medida entre el momento en que un evento de Meta llega al webhook de Chakra y el momento en que se intenta enviar el evento es de aproximadamente 10-50 ms.
2. Recuperación de eventos perdidos
Si se pierde un webhook, ¿qué endpoint permite enumerar los mensajes entrantes, los estados de entrega y los ecos de Business App que faltan?
No hay un endpoint específico para «eventos perdidos». Los mensajes entrantes perdidos se pueden recuperar mediante las API del historial de chats, con filtros por ID del plugin e ID del número de teléfono de WhatsApp. La documentación publicada no cubre una consulta equivalente para los estados de entrega o los ecos de Business App, ni los períodos de retención o los tiempos de demora de consistencia; por lo tanto, debe considerarse que esta función no está disponible actualmente, a la espera de una confirmación interna. Referencia: Listar chats | Listar mensajes del chat | Listar mensajes anteriores de un número de teléfono
3. Cargas útiles e identificación de eventos
¿Dónde puedo encontrar cargas útiles actuales completas y con datos redactados para message, status, message_echoy smb_message_echo, incluido un estado de error con todos los campos de error?
En la referencia de Webhooks de eventos entrantes se publican ejemplos de cargas útiles. Referencia: Webhook de eventos entrantes — ejemplos de cargas útiles
Para los eventos status, message_echoy smb_message_echo , ¿qué campos identifican el plugin, la WABA y el número de teléfono de la empresa que recibe los mensajes cuando una cuenta tiene varios números?
En los eventos de transferencia directa o en formato Meta, el número receptor aparece en value.metadata.phone_number_id / display_phone_number, y el ID de la WABA aparece en entry[].id.
- Ejemplo de evento de mensaje de texto entrante: apidocs.chakrahq.com/doc-919167#sample-inbound-text-message-event
- Estructura del objeto de evento entrante: apidocs.chakrahq.com/doc-919167#inbound-event-object-structure
Referencia: Webhook de eventos entrantes
¿Qué mensajes de Business App generan eventos smb_message_echoy hay tipos no compatibles o dispositivos complementarios?
Todos los mensajes de texto y multimedia de Business App generan eventos smb_message_echo . Los tipos de mensajes no compatibles son:
- Encuestas
- Mensajes temporales
- Mensajes eliminados
¿A qué campos/eventos está suscrita nuestra WABA?
Los siguientes eventos están suscritos y disponibles a través del webhook de paso
El webhook account_alerts te notifica sobre cambios en el límite de mensajería, perfil de empresay el estado de la cuenta de empresa oficial . | |
El webhook account_review_update te notifica cuando una cuenta de WhatsApp Business se ha revisado según nuestras políticas. | |
El webhook account_update notifica sobre cambios en el envío de verificación de empresa facilitada por socios de una cuenta de WhatsApp Business, su elegibilidad para la tarifa de autenticación internacional o la ubicación principal de la empresa cuando se comparte con un Solution Partner, infracciones de políticas o términos, la desvinculación, la reconexión o su eliminación. | |
El webhook automatic_events te notifica cuando detectamos un evento de compra o de cliente potencial en un hilo de chat entre tú y un usuario de WhatsApp que te haya enviado un mensaje a través de tu anuncio de clic a WhatsApp, si aceptaste participar en los informes de eventos automáticos . | |
El webhook business_capability_update te notifica sobre cambios en las capacidades de una cuenta de WhatsApp Business o de un portafolio de empresas (límites de mensajería, límites de números de teléfono, etc.). | |
El webhook calls te notifica sobre eventos de llamadas de llamadas iniciadas por usuarios y llamadas iniciadas por empresas, como cuando una llamada se conecta o finaliza. | |
El webhook history se usa para sincronizar el historial de chats de la app WhatsApp Business de un cliente empresarial incorporado por un proveedor de soluciones. | |
El webhook message_template_components_update te notifica sobre cambios en los componentes de una plantilla. | |
El webhook message_template_quality_update te notifica sobre cambios en la calificación de calidad. | |
El webhook message_template_status_update te notifica sobre cambios en el estado de una plantilla existente. | |
El webhook messages describe los mensajes que envía un usuario de WhatsApp a una empresa y el estado de los mensajes que esta envía a un usuario de WhatsApp. | |
El webhook partner_solutions webhook describe los cambios en el estado de una solución multipartner. | |
El webhook payment_configuration_update te notifica sobre cambios en las configuraciones de pago de Payments API India y Payments API Brazil. | |
El webhook phone_number_name_update te notifica sobre los resultados de la verificación del nombre para mostrar del número de teléfono de una empresa. | |
El webhook phone_number_quality_update te notifica sobre cambios en el nivel de capacidad de envío. | |
El webhook security te notifica sobre cambios en la configuración de seguridad del número de teléfono de una empresa. | |
El webhook smb_app_state_sync se usa para sincronizar los contactos de los usuarios de la app WhatsApp Business que se incorporaron a través de un proveedor de soluciones. | |
El webhook smb_message_echoes te notifica sobre los mensajes enviados desde la app WhatsApp Business o desde un dispositivo complementario («vinculado») por un cliente empresarial que se haya incorporado a Cloud API a través de un proveedor de soluciones. | |
El webhook template_category_update te notifica sobre cambios en la categoría. | |
El webhook user_preferences te notifica sobre cambios en las preferencias de mensajes de marketing. |
4. Controles de mensajes salientes
¿Nuestra cuenta incluye webhooks de paso, webhooks personalizados, HMAC y ecos de coexistencia?
Todas las cuentas de Chakra Chat son compatibles con webhooks de paso, webhooks personalizados, HMAC y ecos de coexistencia.
5. Secreto de HMAC y rotación
¿Proporcionamos el secreto de HMAC o lo genera Chakra?
Tú lo proporcionas y lo configuras en Admin > Team > Secrets. Referencia: Webhook de eventos entrantes — Validación de HMAC
Al regenerar el secreto de HMAC del equipo, el anterior se invalida de inmediato. ¿Qué procedimiento de transición evita la pérdida de webhooks durante la rotación y pueden superponerse temporalmente las firmas anterior y nueva? El mecanismo de rotación está documentado (el secreto se configura en Admin > Team > Secrets y se envía mediante el encabezado X-Chakra-Signature-256 ), pero no se admite ningún procedimiento de transición ni un período de superposición de firmas. Referencia: Webhook de eventos entrantes — Validación de HMAC
¿Puede la misma URL de devolución de llamada y el mismo secreto recibir mensajes, estados, message_echoy eventos smb_message_echo ?
Todos los eventos en formato Chakra y los eventos de paso (message, status, message_echo, smb_message_echo) comparten una sola URL de devolución de llamada y un solo secreto de HMAC. El flujo de paso de Meta usa una URL independiente, y no está documentado específicamente el firmado HMAC para ese flujo. Referencia: Webhook de eventos entrantes
6. Configuración de la URL de devolución de llamada
¿Dónde configuramos la URL de devolución de llamada del webhook: en el panel o mediante la API? En el panel de Chakra: página WhatsApp Setup → pestaña "More" → campo "Pass-through webhook url" (formato Meta) y campo "Chakra webhook url" (formato Chakra).
También se puede configurar mediante programación a través de la API de configuración del complemento: apidocs.chakrahq.com/api-33925592
Referencia: Webhook de eventos entrantes
¿La devolución de llamada corresponde a todo el equipo, a la WABA o al complemento, o es específica de cada número de teléfono?
Por complemento. Cada instancia del complemento WhatsApp Setup tiene sus propios campos para la URL del webhook de paso y la del webhook de Chakra; no hay un webhook a nivel de equipo. Dentro de un complemento, se pueden configurar webhooks específicos para la WABA o el número de teléfono. Referencia: Webhook de eventos entrantes
7. Idempotencia de la API
¿Algún endpoint de envío admite una clave de idempotencia del cliente o un mecanismo para suprimir duplicados? Después de un tiempo de espera agotado, ¿cómo podemos determinar de forma concluyente si se aceptó un mensaje?
Los endpoints de envío no admiten ningún parámetro de clave de idempotencia. Un envío exitoso devuelve de forma síncrona un ID de mensaje de WhatsApp (wamid) en el cuerpo de la respuesta. El procedimiento documentado después de un tiempo de espera agotado es consultar el historial del chat/mensajes y buscar coincidencias con ese wamid — la llamada de envío en sí no cuenta con un mecanismo de clave de idempotencia ni de supresión de duplicados. Referencia: Enviar un mensaje de sesión de WhatsApp | Listar mensajes del chat
8. Desconexión de Coexistence
¿Qué SLA de liberación y escalamiento del proveedor se aplica al desconectar Coexistence, incluidas las asociaciones residuales con socios o de facturación?
El cliente proporciona directamente a Meta sus propios datos de facturación, por lo que no puede haber problemas residuales de facturación. Referencia: Desconectar la cuenta de WABA | Anular el registro de un número de teléfono de empresa de WhatsApp