Ejemplos de cargas útiles de notificaciones de webhooks
Mensajes recibidos
Mensajes de texto
A continuación se incluye un ejemplo de un mensaje de texto recibido de un cliente:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"contacts": [
{
"profile": {
"name": "<WHATSAPP_USER_NAME>"
},
"wa_id": "<WHATSAPP_USER_ID>"
}
],
"messages": [
{
"from": "<WHATSAPP_USER_PHONE_NUMBER>",
"id": "<WHATSAPP_MESSAGE_ID>",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"text": {
"body": "<MESSAGE_BODY_TEXT>"
},
"type": "text"
}
]
},
"field": "messages"
}
]
}
]
}Mensajes de reacción
A continuación se incluye un ejemplo de un mensaje de reacción recibido de un cliente. No recibirás este webhook si el mensaje al que reacciona el cliente tiene más de 30 días.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": PHONE_NUMBER
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"reaction": {
"message_id": "MESSAGE_ID",
"emoji": "EMOJI"
},
"type": "reaction"
}]
},
"field": "messages"
}]
}]
}
Ten en cuenta que, en el caso de las reacciones, el valor de timestamp indica el momento en que el cliente envió la reacción y no el momento en que se generó el webhook.
Mensajes multimedia
Cuando se recibe un mensaje con contenido multimedia, la Plataforma de WhatsApp Business descarga dicho contenido. Se envía una notificación a tu webhook una vez descargado el contenido multimedia.
La notificación de webhook contiene información que identifica el objeto de contenido multimedia y te permite buscar y recuperar el objeto. Utiliza los extremos de contenido multimedia para recuperar dicho contenido.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"type": "image",
"image": {
"caption": "CAPTION",
"mime_type": "image/jpeg",
"sha256": "IMAGE_HASH",
"id": "ID"
}
}]
},
"field": "messages"
}]
}]
}Cuando recibas un sticker, obtendrás la siguiente notificación:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "ID"
}
],
"messages": [
{
"from": "SENDER_PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"type": "sticker",
"sticker": {
"mime_type": "image/webp",
"sha256": "HASH",
"id": "ID"
}
}
]
},
"field": "messages"
}
]
}
]
}Mensajes desconocidos
Es posible recibir una notificación de devolución de llamada de mensaje desconocido. Por ejemplo, un cliente podría enviarte un mensaje que no se admite, como un mensaje temporal; en ese caso, notificaríamos al cliente de que el tipo de mensaje no se admite.
A continuación se incluye un ejemplo de un mensaje recibido de un cliente que no se admite.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"errors": [
{
"code": 131051,
"details": "Message type is not currently supported",
"title": "Unsupported message type"
}],
"type": "unknown"
}]
}
"field": "messages"
}],
}]
}Mensajes de ubicación
A continuación se incluye un ejemplo de un mensaje de ubicación recibido de un cliente:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"location": {
"latitude": LOCATION_LATITUDE,
"longitude": LOCATION_LONGITUDE,
"name": LOCATION_NAME,
"address": LOCATION_ADDRESS,
}
}]
},
"field": "messages"
}]
}]
}Mensajes de contactos
A continuación se incluye un ejemplo de un mensaje de contactos recibido de un cliente:
{
"object":"whatsapp_business_account",
"entry":[{
"id":"WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes":[{
"value":{
"messaging_product":"whatsapp",
"metadata": {
"display_phone_number":"PHONE_NUMBER",
"phone_number_id":"PHONE_NUMBER_ID"
},
"contacts": [{
"profile":{
"name":"NAME"
},
"wa_id":"WHATSAPP_ID"
}],
"messages":[{
"from":"PHONE_NUMBER",
"id":"wamid.ID",
"timestamp":"TIMESTAMP",
"contacts":[{
"addresses":[{
"city":"CONTACT_CITY",
"country":"CONTACT_COUNTRY",
"country_code":"CONTACT_COUNTRY_CODE",
"state":"CONTACT_STATE",
"street":"CONTACT_STREET",
"type":"HOME or WORK",
"zip":"CONTACT_ZIP"
}],
"birthday":"CONTACT_BIRTHDAY",
"emails":[{
"email":"CONTACT_EMAIL",
"type":"WORK or HOME"
}],
"name":{
"formatted_name":"CONTACT_FORMATTED_NAME",
"first_name":"CONTACT_FIRST_NAME",
"last_name":"CONTACT_LAST_NAME",
"middle_name":"CONTACT_MIDDLE_NAME",
"suffix":"CONTACT_SUFFIX",
"prefix":"CONTACT_PREFIX"
},
"org":{
"company":"CONTACT_ORG_COMPANY",
"department":"CONTACT_ORG_DEPARTMENT",
"title":"CONTACT_ORG_TITLE"
},
"phones":[{
"phone":"CONTACT_PHONE",
"wa_id":"CONTACT_WA_ID",
"type":"HOME or WORK>"
}],
"urls":[{
"url":"CONTACT_URL",
"type":"HOME or WORK"
}]
}]
}]
},
"field":"messages"
}]
}]
}Devolución de llamada recibida de un botón de respuesta rápida
Cuando un cliente hace clic en un botón de respuesta rápida de una plantilla interactiva de mensaje, se envía una respuesta. A continuación se incluye un ejemplo del formato de devolución de llamada.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"context": {
"from": PHONE_NUMBER,
"id": "wamid.ID"
},
"from": "16315551234",
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"type": "button",
"button": {
"text": "No",
"payload": "No-Button-Payload"
}
}]
},
"field": "messages"
}]
}]
}Respuesta recibida de un mensaje de lista
La notificación de webhook siguiente se recibe cuando un usuario hace clic en un elemento de un mensaje de lista que has enviado:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "PHONE_NUMBER_ID"
}
],
"messages": [
{
"from": PHONE_NUMBER_ID,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"interactive": {
"list_reply": {
"id": "list_reply_id",
"title": "list_reply_title",
"description": "list_reply_description"
},
"type": "list_reply"
},
"type": "interactive"
}
]
},
"field": "messages"
}
]
}
]
}Respuesta recibida para un botón de respuesta
La notificación de webhook siguiente se recibe cuando un usuario hace clic en un botón de respuesta que has enviado:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": PHONE_NUMBER_ID,
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "PHONE_NUMBER_ID"
}
],
"messages": [
{
"from": PHONE_NUMBER_ID,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"interactive": {
"button_reply": {
"id": "unique-button-identifier-here",
"title": "button-text",
},
"type": "button_reply"
},
"type": "interactive"
}
]
},
"field": "messages"
}
]
}
]
}Mensaje recibido activado mediante anuncios de clic a WhatsApp
Cuando se inicia una conversación después de que un usuario haga clic en un anuncio con una llamada a la acción de clic a WhatsApp, recibes el webhook siguiente:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "ID"
}
],
"messages": [
{
"referral": {
"source_url": "AD_OR_POST_FB_URL",
"source_id": "ADID",
"source_type": "ad or post",
"headline": "AD_TITLE",
"body": "AD_DESCRIPTION",
"media_type": "image or video",
"image_url": "RAW_IMAGE_URL",
"video_url": "RAW_VIDEO_URL",
"thumbnail_url": "RAW_THUMBNAIL_URL",
"ctwa_clid": "CTWA_CLID"
},
"from": "SENDER_PHONE_NUMBERID",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"type": "text",
"text": {
"body": "BODY"
}
}
]
},
"field": "messages"
}
]
}
]
}Mensajes de consulta sobre un producto
Un mensaje de consulta sobre un producto se recibe cuando un cliente pide más información sobre un producto. Estos mensajes aparecen en las situaciones siguientes:
- Un cliente responde a mensajes sobre uno o varios productos.
- Un cliente accede al catálogo de una empresa por otro punto de acceso, navega a la página Detalles del producto y hace clic en Enviar un mensaje a la empresa sobre este producto.
Una notificación de webhooks de un mensaje de consulta sobre un producto tiene el siguiente aspecto:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "PHONE_NUMBER_ID"
}
],
"messages": [
{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"text": {
"body": "MESSAGE_TEXT"
},
"context": {
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"referred_product": {
"catalog_id": "CATALOG_ID",
"product_retailer_id": "PRODUCT_ID"
}
},
"timestamp": "TIMESTAMP",
"type": "text"
}
]
},
"field": "messages"
}
]
}
]
}Mensajes de pedidos
Una notificación de webhooks recibida cuando un cliente hace un pedido tiene el siguiente aspecto:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "8856996819413533",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "16505553333",
"phone_number_id": "phone-number-id",
},
"contacts": [
{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}
],
"messages": [
{
"from": "16315551234",
"id": "wamid.ABGGFlCGg0cvAgo6cHbBhfK5760V",
"order": {
"catalog_id": "the-catalog_id",
"product_items": [
{
"product_retailer_id":"the-product-SKU-identifier",
"quantity":"number-of-item",
"item_price":"unitary-price-of-item",
"currency":"price-currency"
},
...
],
"text":"text-message-sent-along-with-the-order"
},
"context": {
"from": "16315551234",
"id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
},
"timestamp": "1603069091",
"type": "order"
}
]
},
"field": "messages"
}
]
}
]
}Notificación de número cambiado por el usuario
Cuando un usuario cambia su número de teléfono en WhatsApp, recibes una notificación de mensaje del sistema:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"system": {
"body": "NAME changed from PHONE_NUMBER to PHONE_NUMBER",
"new_wa_id": NEW_PHONE_NUMBER,
"type": "user_changed_number"
},
"timestamp": TIMESTAMP,
"type": "system"
}]
},
"field": "messages"
}]
}]
}Actualizaciones de estado de los mensajes
Los precios basados en conversaciones han cambiado. Consulta Precios para obtener información sobre el funcionamiento del nuevo modelo de precios basados en conversaciones.
Además, la visibilidad de metric_types ha cambiado el 1 de julio de 2023. Consulta la tabla de análisis de conversaciones para obtener más información.
La Plataforma de WhatsApp Business envía notificaciones para informarte del estado de los mensajes que intercambias con los usuarios. Cuando se envía un mensaje correctamente, recibes una notificación en cuanto el mensaje se envía, se entrega y se lee. El orden de las notificaciones en la aplicación podría no reflejar el momento justo de cada estado del mensaje. Consulta la marca de tiempo para determinarlo, si es necesario.
Estado: mensaje enviado
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<WHATSAPP_MESSAGE_ID>",
"status": "sent",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"recipient_id": "<WHATSAPP_USER_ID>",
"conversation": {
"id": "<CONVERSATION_ID>",
"expiration_timestamp": "<CONVERSATION_EXPIRATION_TIMESTAMP>",
"origin": {
"type": "<CONVERSATION_CATEGORY>"
}
},
"pricing": {
"billable": <IS_BILLABLE?>,
"pricing_model": "CBP",
"category": "<CONVERSATION_CATEGORY>"
}
}
]
},
"field": "messages"
}
]
}
]
}En el caso de las conversaciones gratuitas desde punto de acceso, los parámetros origin.type y pricing.category se establecen en referral_conversion, y el parámetro pricing.billable está establecido en false.
Estado: mensaje entregado
La notificación siguiente se recibe cuando se entrega un mensaje de una empresa y dicho mensaje forma parte de una conversación iniciada por el usuario (si dicha conversación no se originó en un punto de entrada gratuito):
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<WHATSAPP_MESSAGE_ID>",
"status": "sent",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"recipient_id": "<WHATSAPP_USER_ID>",
"conversation": {
"id": "<CONVERSATION_ID>",
"origin": {
"type": "<CONVERSATION_CATEGORY>"
}
},
"pricing": {
"billable": <IS_BILLABLE?>,
"pricing_model": "CBP",
"category": "<CONVERSATION_CATEGORY>"
}
}
]
},
"field": "messages"
}
]
}
]
}En el caso de las conversaciones gratuitas desde punto de acceso, los parámetros origin.type y pricing.category se establecen en referral_conversion, y el parámetro pricing.billable está establecido en false.
Estado: mensaje leído
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<WHATSAPP_MESSAGE_ID>",
"status": "read",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"recipient_id": "<WHATSAPP_USER_ID>"
}
]
},
"field": "messages"
}
]
}
]
}Estado: mensaje eliminado
Actualmente, la API de la nube no admite las actualizaciones de estado de webhooks para los mensajes eliminados. Si un usuario elimina un mensaje, recibirás un webhook con un código de error de un tipo de mensaje no admitido:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": PHONE_NUMBER
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"errors": [{
"code": 131051,
"details": "Message type is not currently supported",
"title": "Unsupported message type"
}],
"type": "unsupported"
}]
},
"field": "messages"
}]
}]
}Ten en cuenta que hay otros comportamientos de los usuarios que pueden activar este mismo mensaje de error.
Estado: se ha producido un error en el mensaje
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<WHATSAPP_MESSAGE_ID>",
"status": "failed",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"recipient_id": "<WHATSAPP_USER_ID>",
"errors": [
{
"code": <ERROR_CODE>,
"title": "<ERROR_TITLE>",
"message": "<ERROR_MESSAGE>",
"error_data": {
"details": "<ERROR_DETAILS>"
},
"href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
}
]
}
]
},
"field": "messages"
}
]
}
]
}