Ir al contenido principal

Rastreo del estado de las plantillas de mensajes usando Webhooks

Actualizado ayer

Resumen

Al enviar mensajes de planta utilizando la API Enviar Mensaje de Planta de WATI, es esencial rastrear su estado: enviado, entregado, leído, respondido o fallido. Esto garantiza una mejor visibilidad y gestión de las interacciones con los clientes.

Instrucciones

Enviar un Mensaje de Planta

Para enviar un mensaje de planta utilizando la API de WATI, utilice el punto final sendTemplateMessage V2.

Ejemplo de solicitud cURL

curl --location 'https://live-server-123.wati.io/api/v2/sendTemplateMessage?whatsappNumber=<whatsappNumber>' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{
"template_name": "update_for_you",
"broadcast_name": "JPTestBroadcast",
"parameters": []
}'

Ejemplo de respuesta API

{
"result": true,
"error": null,
"templateName": "update_for_you",
"receivers": [
{
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"waId": "<whatsappNumber>",
"isValidWhatsAppNumber": true,
"errors": []
}
],
"parameters": []
}

Campo clave:

  • localMessageId – Un identificador único para rastrear el estado del mensaje a través de webhooks.

Webhooks para rastrear el estado del mensaje

1. El mensaje de la planta enviada

Se activa cuando: Un mensaje de planta se envía correctamente.

  • Evento de webhook: templateMessageSent_v2

  • Campo clave: localMessageId

  • Cadena de estado: "SENT"

Ejemplo de carga útil webhook

{
"eventType": "templateMessageSent_v2",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"templateId": "63766ae83b2e064905789c63",
"templateName": "update_for_you",
"created": "2023-03-11T14:27:32.9655388Z",
"statusString": "SENT",
"sourceType": "API"
}

2. Mensaje entregado

Se activa cuando: El mensaje se entrega correctamente al destinatario.

  • Evento de webhook: sentMessageDELIVERED_v2

  • Cadena de estado: "Delivered"

Ejemplo de carga útil webhook

{
"eventType": "sentMessageDELIVERED_v2",
"statusString": "Delivered",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"timestamp": "1678544854",
"operatorEmail": "[email protected]"
}

3. Mensaje leído

Se activa cuando: El destinatario lee el mensaje.

  • Evento de webhook: sentMessageREAD_v2

  • Cadena de estado: "Read"

Ejemplo de carga útil webhook

{
"eventType": "sentMessageREAD_v2",
"statusString": "Read",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"timestamp": "1678545043",
"operatorEmail": "[email protected]"
}

4. Mensaje respondido

Se activa cuando: El destinatario responde al mensaje.

  • Evento de webhook: sentMessageREPLIED_v2

  • Cadena de estado: "Replied"

Ejemplo de carga útil webhook

{
"eventType": "sentMessageREPLIED_v2",
"statusString": "Replied",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"timestamp": "1678545074",
"operatorEmail": "[email protected]"
}

5. Mensaje recibido

Se activa cuando: Un usuario envía un mensaje a su número de WATI.

  • Evento de webhook: messageReceived

  • Caso de uso: Puede usarse con Mensaje de Planta Enviado para rastrear los clics en el botón de respuesta rápida.

Ejemplo de carga útil webhook

{
"eventType": "messageReceived",
"statusString": "Received",
"localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
"whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
"text": "Hello, I need help!",
"timestamp": "1665645642",
"operatorEmail": "[email protected]"
}

6. Mensaje de planta fallido

Se activa cuando: El mensaje de la planta no puede ser enviado.

  • Evento de webhook: templateMessageFailed

  • Detalles del fallo: Incluye un código de error y un mensaje de error.

Ejemplo de carga útil webhook

{
"eventType": "templateMessageFailed",
"statusString": "Failed",
"localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
"failedCode": "131026",
"failedDetail": "Message undeliverable",
"id": "66b2531d4931581381944612",
"whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
"timestamp": "1665645642",
"operatorEmail": "[email protected]"
}

Cómo configurar webhooks

  1. Vaya al Panel de Control de WATI.

  2. Navegue a Webhooks.

  3. Haga clic en "Agregar Webhook".

  4. Ingrese su URL de webhook.

  5. Establezca el Estado en "Habilitado".

  6. Seleccione los eventos necesarios (por ejemplo, Mensaje de Planta Enviado, Entregado, Leído, etc.)

Siguiendo estos pasos, puede rastrear y gestionar de manera efectiva todos los mensajes de plantilla enviados a través de la API de WATI.

Preguntas Frecuentes (FAQs)

Enviar Mensajes de Planta

1. ¿Cómo envío un mensaje de planta utilizando la API de WATI?

→ Para enviar un mensaje de planta, utilice el punto final sendTemplateMessage V2. Debe incluir el número de WhatsApp, el nombre de la planta y el token de autorización en la solicitud. Consulte la solicitud de cURL de ejemplo en la documentación para obtener detalles.

2. ¿Qué parámetros debo incluir en la solicitud de API?

→ Los parámetros obligatorios incluyen whatsappNumber, template_name, broadcast_name y parameters (si es aplicable). Asegúrese de proporcionar un token de autorización válido.

Rastrear el estado del mensaje

3. ¿Cómo puedo rastrear el estado de un mensaje enviado?

→ Cada respuesta de la API incluye un localMessageId, que se puede usar para rastrear el estado del mensaje a través de webhooks. Los webhooks proporcionan actualizaciones en tiempo real para mensajes enviados, entregados, leídos, respondidos y fallidos.

4. ¿Qué evento de webhook rastrea cuándo se envía un mensaje?

→ El evento de webhook templateMessageSent_v2 rastrea cuándo se envía un mensaje. Contiene el localMessageId, whatsappMessageId y otros metadatos.

5. ¿Cómo sé cuándo un mensaje es entregado?

→ El evento de webhook sentMessageDELIVERED_v2 indica que el mensaje ha sido entregado. El campo statusString tendrá el valor Delivered.

6. ¿Cómo rastreo cuándo un mensaje es leído?

→ El evento de webhook sentMessageREAD_v2 se activa cuando el destinatario lee el mensaje. El campo statusString tendrá el valor Read.

7. ¿Puedo rastrear si un usuario responde a un mensaje?

→ Sí, el evento de webhook sentMessageREPLIED_v2 se activa cuando el destinatario responde al mensaje.

Manejo de fallos

8. ¿Qué ocurre si falla el envío de un mensaje de planta?

→ Si un mensaje falla, el evento de webhook templateMessageFailed se activa. Proporciona un failedCode y failedDetail que explican la razón del fallo.

9. ¿Dónde puedo encontrar detalles sobre los códigos de fallo?

→ Los códigos de fallo están incluidos en la carga útil del webhook templateMessageFailed. Puede referirse a la documentación de Meta para obtener una explicación detallada de cada código de error.

Configurar webhooks

10. ¿Cómo habilito los webhooks en WATI?

→ Para habilitar webhooks:

  • Vaya al Panel de Control de WATI.

  • Navegue a Webhooks.

  • Haga clic en Add Webhook.

  • Ingrese su URL de webhook.

  • Establezca el estado en Enabled.

  • Seleccione los eventos de webhook que desea rastrear.

11. ¿Qué eventos webhook debo habilitar para un seguimiento completo del mensaje?

→ Para rastrear el ciclo de vida completo del mensaje, habilite los siguientes eventos:

  • templateMessageSent_v2

  • sentMessageDELIVERED_v2

  • sentMessageREAD_v2

  • sentMessageREPLIED_v2

  • messageReceived

  • templateMessageFailed

¿Ha quedado contestada tu pregunta?