Respuestas automáticas al estado de WhatsApp
Cuando envías un mensaje de WhatsApp mediante la Messages API de Vonage, Vonage se encarga de entregarlo llamadas de retorno de estado a la URL del webhook que hayas configurado cada vez que cambie el estado de un mensaje; por ejemplo, cuando se envíe, se entregue o se lea.
Vonage recibe actualizaciones de estado de Meta (el proveedor subyacente de WhatsApp) y las convierte a un formato de respuesta coherente antes de reenviarlas a tu aplicación. Esto significa que la carga útil que recibe tu webhook puede diferir de la carga útil sin procesar del webhook de Meta.
Para obtener una visión general de las respuestas de estado en todos los canales, consulta Llamadas de estado de la API de Messages.
Llamadas de retorno sobre el estado de los mensajes
Vonage envía una llamada de respuesta de estado a la URL de tu webhook cada vez que un mensaje de WhatsApp pasa a un nuevo estado. Se admiten los siguientes estados:
| Estado | Descripción |
|---|---|
submitted |
Vonage ha recibido el mensaje y lo ha reenviado a WhatsApp. |
delivered |
El mensaje se ha enviado al dispositivo del destinatario. |
read |
El destinatario ha abierto el mensaje (es necesario que la función de confirmación de lectura esté activada). |
rejected |
El mensaje ha sido rechazado por Vonage o WhatsApp. Un error El objeto se incluye en la carga útil. |
undeliverable |
Vonage no ha podido conectarse a WhatsApp para enviar el mensaje. |
Carga útil de la llamada de retorno de estado
El siguiente ejemplo muestra el conjunto completo de campos que pueden aparecer en una respuesta de estado de WhatsApp. No todos los campos están presentes en todas las respuestas; por ejemplo, error solo se incluye para rejected o undeliverable estados, workflow solo se incluye cuando el mensaje se ha enviado como parte de un flujo de trabajo, y profile / whatsapp.recipient solo se incluyen cuando están disponibles en WhatsApp:
{
"to": "447700900001",
"from": "447700900001",
"channel": "whatsapp",
"status": "submitted",
"usage": {
"currency": "EUR",
"price": "0"
},
"profile": {
"name": "Jane Smith",
"username": "janesmith123"
},
"whatsapp": {
"recipient": {
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.11815799212886844830",
"wa_id": "447700900000"
},
"waba_id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"pricing": {
"type": "regular",
"pricing_model": "CBP",
"category": "service"
},
"conversation": {
"id": "1234567890",
"origin": {
"type": "marketing"
}
}
},
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"timestamp": "2025-02-03T12:14:25Z",
"error": {
"type": "https://developer.vonage.com/api-errors/messages#1000",
"title": "1000",
"detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
},
"client_ref": "abc123",
"workflow": {
"workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
"items_number": "1",
"items_total": "2"
}
}
Para consultar la lista completa de campos de estado, véase el Campos de devolución de llamada de estado sección de la guía de referencia de la Messages API.
Funciones de llamada de retorno en caso de error
Cuando un mensaje es rechazado o no se puede entregar, la llamada de retorno incluye un error objeto:
{
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2025-02-03T12:14:25Z",
"status": "rejected",
"channel": "whatsapp",
"error": {
"type": "https://developer.vonage.com/api-errors/messages#1000",
"title": 1000,
"detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
}
Llamadas de retorno para mensajes entrantes
Cuando un usuario de WhatsApp envía un mensaje a tu número de WhatsApp Business, Vonage reenvía el mensaje a la URL de tu webhook de entrada.
Debes configurar una URL de webhook de entrada en tu Panel de control de la API de Vonage o a través de la API de la aplicación para recibir mensajes entrantes.
Carga útil del mensaje entrante
A continuación se muestra un ejemplo de devolución de llamada tras recibir un mensaje de texto:
{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2025-02-03T12:14:25Z",
"profile": {
"name": "Jane Smith",
"username": "janesmith123"
},
"context_status": "available",
"context": {
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"message_from": "447700900000"
},
"provider_message": "Message delivered",
"message_type": "text",
"text": "Hello from Vonage!",
"whatsapp": {
"sender": {
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.11815799212886844830",
"wa_id": "447700900000"
},
"referral": {
"body": "Check out our new product offering",
"headline": "New Products!",
"source_id": "212731241638144",
"source_type": "post",
"source_url": "https://fb.me/2ZulEu42P",
"media_type": "image",
"image_url": "https://example.com/image.jpg",
"video_url": "https://example.com/video.mp4",
"thumbnail_url": "https://example.com/thumbnail.jpg",
"ctwa_clid": "1234567890"
}
},
"_self": {
"href": "https://api-eu.vonage.com/v1/messages/aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
}
}
Para obtener una lista completa de los campos de los mensajes entrantes, consulta el Campos de los mensajes entrantes sección de la guía de referencia de la Messages API.
Campos obsoletos
Está previsto que los siguientes campos queden obsoletos:
| Campo | Notas |
|---|---|
whatsapp.conversation |
Quedará obsoleto en la versión 23.0 y posteriores de la API de webhooks, salvo en el caso de las conversaciones con punto de entrada gratuito. |
pricing.billable |
Quedará obsoleto en una versión futura. Utiliza whatsapp.pricing en su lugar. |
usage.price |
Se establecerá en "0" a partir del 1 de julio de 2025, según el modelo de tarificación por mensaje (PMP). |