whatsapp.inbound_message.received

Usa whatsapp.inbound_message.received para gestionar este evento en tu endpoint de webhook.

Activadores

Se produce cuando se recibe un mensaje entrante de WhatsApp. Suscríbete a whatsapp.inbound_message.received cuando configures tu endpoint de webhook. Usa el type del mensaje para seleccionar su objeto de contenido. El contenido multimedia, las respuestas interactivas, la ubicación, los contactos y las notificaciones del sistema tienen campos diferentes. Los ejemplos a continuación muestran estas variantes.

Sintaxis

YCloud envía una solicitud HTTP POST a tu URL de webhook configurada. La siguiente estructura muestra una variante de la carga útil. Los valores entre corchetes angulares son marcadores de posición; sus tipos se enumeran en Parámetros. Los campos opcionales y otras variantes se describen a continuación.

{
  "id": "<ID>",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappInboundMessage": {
    "id": "<ID>",
    "wamid": "<WAMID>",
    "wabaId": "<WABA_ID>",
    "to": "<TO>",
    "sendTime": "<SEND_TIME>",
    "type": "<TYPE>",
    "system": {
      "type": "<TYPE>",
      "previous_user_id": "<PREVIOUS_USER_ID>",
      "previous_parent_user_id": "<PREVIOUS_PARENT_USER_ID>"
    }
  }
}

Parámetros

Valida el encabezado HTTP YCloud-Signature antes de procesar el cuerpo JSON. Consulta la validación de firmas.

Envoltorio del evento

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID único del evento. Longitud mínima: `6`. Longitud máxima: `128`.
`type`	string	Sí	Siempre `whatsapp.inbound_message.received`.
`apiVersion`	string	Sí	La versión de la API utilizada para procesar este evento.
`createTime`	string (date-time)	Sí	La fecha y hora en que se creó este evento, con formato RFC 3339. Por ejemplo, `2022-06-01T12:00:00.000Z`.

Carga útil del evento

Parámetro	Tipo	Obligatorio	Descripción
`whatsappInboundMessage`	object	No	Carga útil de `whatsappInboundMessage` específica del evento.

Los cuatro campos comunes del envoltorio son obligatorios. Los campos de la carga útil dependen de la variante del evento. En cada tabla de objetos, Obligatorio se aplica cuando su objeto superior está presente. Los campos opcionales se pueden omitir; un ejemplo no convierte un campo en obligatorio.

whatsappInboundMessage

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID único del objeto.
`wamid`	string	No	El ID del mensaje original en la plataforma de WhatsApp.
`wabaId`	string	No	ID de la cuenta de WhatsApp Business.
`from`	string	No	El número de teléfono del cliente que envió el mensaje a la empresa, con formato E.164.
`fromUserId`	string	No	El ID de usuario con ámbito de WhatsApp Business del cliente (BSUID).
`fromParentUserId`	string	No	El ID de usuario principal con ámbito de WhatsApp Business del cliente.
`customerProfile`	object	No	Información del perfil del cliente.
`to`	string	No	El número de teléfono del destinatario en formato E.164.
`sendTime`	string (date-time)	No	La fecha y hora en que se envió este mensaje, con formato RFC 3339. Por ejemplo, `2022-06-01T12:00:00.000Z`.
`type`	string	No	Tipo de mensaje entrante de WhatsApp. Consulta también el objeto messages del webhook de WhatsApp. Valores: `text`, `image`, `video`, `audio`, `document`, `sticker`, `contacts`, `location`, `interactive`, `button`, `reaction`, `request_welcome`, `order`, `system`, `unsupported`.
`text`	object	No	Cuando la notificación describe un mensaje de texto, el objeto text proporciona el cuerpo del mensaje de texto.
`image`	object	No	Cuando se recibe un mensaje con contenido multimedia (`image` \| `document` \| `audio` \| `video` \| `sticker`), el cliente de la WhatsApp Business API descargará dicho contenido multimedia. Una vez descargado el contenido multimedia, se envía una notificación a tu Webhook. Este mensaje contiene información que identifica el objeto multimedia y te permite buscar y descargar el objeto.
`video`	object	No	Cuando se recibe un mensaje con contenido multimedia (`image` \| `document` \| `audio` \| `video` \| `sticker`), el cliente de la WhatsApp Business API descargará dicho contenido multimedia. Una vez descargado el contenido multimedia, se envía una notificación a tu Webhook. Este mensaje contiene información que identifica el objeto multimedia y te permite buscar y descargar el objeto.
`audio`	object	No	Cuando se recibe un mensaje con contenido multimedia (`image` \| `document` \| `audio` \| `video` \| `sticker`), el cliente de la WhatsApp Business API descargará dicho contenido multimedia. Una vez descargado el contenido multimedia, se envía una notificación a tu Webhook. Este mensaje contiene información que identifica el objeto multimedia y te permite buscar y descargar el objeto.
`document`	object	No	Cuando se recibe un mensaje con contenido multimedia (`image` \| `document` \| `audio` \| `video` \| `sticker`), el cliente de la WhatsApp Business API descargará dicho contenido multimedia. Una vez descargado el contenido multimedia, se envía una notificación a tu Webhook. Este mensaje contiene información que identifica el objeto multimedia y te permite buscar y descargar el objeto.
`sticker`	object	No	Cuando se recibe un mensaje con contenido multimedia (`image` \| `document` \| `audio` \| `video` \| `sticker`), el cliente de la WhatsApp Business API descargará dicho contenido multimedia. Una vez descargado el contenido multimedia, se envía una notificación a tu Webhook. Este mensaje contiene información que identifica el objeto multimedia y te permite buscar y descargar el objeto.
`interactive`	object	No	Cuando un cliente ha interactuado con tu mensaje, este objeto se incluye en el objeto message.
`location`	object	No	Cuando recibes una notificación de la ubicación estática de un usuario, el objeto location proporciona los detalles de la ubicación.
`button`	object	No	Cuando el campo de tipo de mensaje se establece en `button`, este objeto se incluye en el objeto message.
`contacts`	object[]	No	Los elementos del array se describen a continuación.
`reaction`	object	No	Cuando un usuario reacciona a los mensajes con un emoji, el tipo de mensaje se establece en `reaction` y se incluye este campo.
`order`	object	No	Cuando un cliente realiza un pedido, el tipo de mensaje se establece en `order` y se incluye este campo.
`system`	object	No	Cuando el tipo de mensaje se establece en `system`, se incluye este campo. Este objeto describe un cambio de número de teléfono de usuario, un cambio de BSUID o un posible cambio de identidad en WhatsApp.
`errors`	object[]	No	Los elementos del array se describen a continuación.
`context`	object	No	Contexto del mensaje.
`referral`	object	No	Cuando un usuario envía un mensaje a las empresas utilizando los botones de llamada a la acción en anuncios que hacen clic a WhatsApp o en los botones de llamada a la acción de una página de Facebook, este campo se incluye como un archivo adjunto.
`groupId`	string	No	ID del grupo de WhatsApp. Este campo se incluye cuando el mensaje entrante se envía en un grupo de WhatsApp.

Parámetros de objetos anidados

Despliega un campo para ver sus parámetros anidados.

whatsappInboundMessage.customerProfile

Parámetro	Tipo	Requerido	Descripción
`name`	string	No	Nombre de la cuenta de WhatsApp.
`username`	string	No	Nombre de usuario de WhatsApp.

whatsappInboundMessage.text

Parámetro	Tipo	Obligatorio	Descripción
`body`	string	No	Texto del mensaje.

whatsappInboundMessage.image

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	No	ID del archivo multimedia. Puede usarse para eliminar el archivo multimedia si está almacenado localmente en el cliente.
`link`	string	No	La URL para descargar el archivo multimedia. Ten en cuenta que es posible acceder directamente a este enlace durante unos minutos para mayor comodidad del consumidor, pero siempre debes incluir un encabezado `X-API-Key` para descargar este archivo en un plazo de un mes.
`caption`	string	No	El pie de foto o descripción proporcionado para el archivo multimedia. Solo está presente si se especificó.
`filename`	string	No	Nombre del archivo en el dispositivo del remitente. Solo estará presente en mensajes multimedia de `document`.
`metadata`	object	No	Metadatos pertenecientes al archivo multimedia de `sticker`.
`mime_type`	string	No	Tipo MIME del archivo multimedia.
`sha256`	string	No	Checksum.

whatsappInboundMessage.video

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	No	ID del archivo multimedia. Puede usarse para eliminar el archivo multimedia si está almacenado localmente en el cliente.
`link`	string	No	La URL para descargar el archivo multimedia. Ten en cuenta que es posible acceder directamente a este enlace durante unos minutos para mayor comodidad del consumidor, pero siempre debes incluir un encabezado `X-API-Key` para descargar este archivo en un plazo de un mes.
`caption`	string	No	El pie de foto o descripción proporcionado para el archivo multimedia. Solo está presente si se especificó.
`filename`	string	No	Nombre del archivo en el dispositivo del remitente. Solo estará presente en mensajes multimedia de `document`.
`metadata`	object	No	Metadatos pertenecientes al archivo multimedia de `sticker`.
`mime_type`	string	No	Tipo MIME del archivo multimedia.
`sha256`	string	No	Checksum.

whatsappInboundMessage.audio

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	No	ID del archivo multimedia. Puede usarse para eliminar el archivo multimedia si está almacenado localmente en el cliente.
`link`	string	No	La URL para descargar el archivo multimedia. Ten en cuenta que es posible acceder directamente a este enlace durante unos minutos para mayor comodidad del consumidor, pero siempre debes incluir un encabezado `X-API-Key` para descargar este archivo en un plazo de un mes.
`caption`	string	No	El pie de foto o descripción proporcionado para el archivo multimedia. Solo está presente si se especificó.
`filename`	string	No	Nombre del archivo en el dispositivo del remitente. Solo estará presente en mensajes multimedia de `document`.
`metadata`	object	No	Metadatos pertenecientes al archivo multimedia de `sticker`.
`mime_type`	string	No	Tipo MIME del archivo multimedia.
`sha256`	string	No	Checksum.

whatsappInboundMessage.document

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	No	ID del archivo multimedia. Puede usarse para eliminar el archivo multimedia si está almacenado localmente en el cliente.
`link`	string	No	La URL para descargar el archivo multimedia. Ten en cuenta que es posible acceder directamente a este enlace durante unos minutos para mayor comodidad del consumidor, pero siempre debes incluir un encabezado `X-API-Key` para descargar este archivo en un plazo de un mes.
`caption`	string	No	El pie de foto proporcionado para el archivo multimedia. Solo está presente si se especificó.
`filename`	string	No	Nombre de archivo en el dispositivo del remitente. Esto solo estará presente en mensajes multimedia `document`.
`metadata`	object	No	Metadatos correspondientes al archivo multimedia `sticker`.
`mime_type`	string	No	Tipo MIME del archivo multimedia.
`sha256`	string	No	Checksum.

whatsappInboundMessage.sticker

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	No	ID del archivo multimedia. Se puede usar para eliminar el archivo multimedia si está almacenado localmente en el cliente.
`link`	string	No	La URL para descargar el archivo multimedia. Ten en cuenta que este enlace se puede consultar directamente durante unos minutos para mayor comodidad del consumidor, pero siempre debes incluir un encabezado `X-API-Key` para descargar este archivo en un plazo de un mes.
`caption`	string	No	El pie de foto proporcionado para el archivo multimedia. Solo está presente si se especificó.
`filename`	string	No	Nombre de archivo en el dispositivo del remitente. Esto solo estará presente en mensajes multimedia `document`.
`metadata`	object	No	Metadatos correspondientes al archivo multimedia `sticker`.
`mime_type`	string	No	Tipo MIME del archivo multimedia.
`sha256`	string	No	Checksum.

whatsappInboundMessage.interactive

Parámetro	Tipo	Obligatorio	Descripción
`type`	string	No	El tipo de mensaje interactivo recibido. `button_reply`: Se envía cuando un cliente hace clic en un botón. `list_reply`: Se envía cuando un cliente selecciona un elemento de una lista. `nfm_reply`: Se envía cuando un cliente responde a un WhatsApp Flow (Next Feature Messaging). `call_permission_reply`: Se envía cuando un cliente responde a una solicitud de permiso de llamada.
`button_reply`	object	No	Se envía cuando un cliente hace clic en un botón. Se devuelve cuando `type` es `button_reply`.
`list_reply`	object	No	Se envía cuando un cliente selecciona un elemento de una lista. Se devuelve cuando `type` es `list_reply`.
`nfm_reply`	object	No	Se envía cuando un cliente responde a un WhatsApp Flow (Next Feature Messaging). Se devuelve cuando `type` es `nfm_reply`.
`call_permission_reply`	object	No	Se envía cuando un cliente responde a una solicitud de permiso de llamada. Se devuelve cuando `type` es `call_permission_reply`. Esto ocurre cuando WhatsApp solicita a los usuarios que concedan permisos para devolver la llamada después de llamar a tu empresa.

whatsappInboundMessage.interactive.button_reply

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	No	ID único del botón en el que se hizo clic.
`title`	string	No	Título de un botón.

whatsappInboundMessage.interactive.list_reply

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	No	ID único del elemento de lista seleccionado.
`title`	string	No	Título del elemento de lista seleccionado.
`description`	string	No	Descripción de la fila seleccionada.

whatsappInboundMessage.interactive.nfm_reply

Parámetro	Tipo	Obligatorio	Descripción
`name`	string	No	El nombre del flujo o formulario al que se responde.
`response_json`	string	No	Cadena JSON que contiene las respuestas del usuario al flujo. Contiene los valores de los campos del formulario y el token del flujo.
`body`	string	No	El contenido del cuerpo del mensaje de respuesta del flujo.

whatsappInboundMessage.interactive.call_permission_reply

Parámetro	Tipo	Obligatorio	Descripción
`response`	string	No	La respuesta del cliente a la solicitud de permiso de llamada. `accept`: el usuario otorgó permiso para que la empresa le devuelva la llamada `reject`: el usuario rechazó el permiso para que la empresa le devuelva la llamada
`expiration_timestamp`	integer (int64)	No	La marca de tiempo (en segundos) en la que caduca el permiso de llamada. Solo está presente cuando la respuesta es “accept” y is_permanent es false.
`is_permanent`	boolean	No	Indica si el permiso es permanente o temporal. `true`: autorización permanente (sin caducidad) `false`: autorización temporal (caduca en expiration_timestamp)

whatsappInboundMessage.location

Parámetro	Tipo	Obligatorio	Descripción
`latitude`	number (double)	No	Latitud de la ubicación que se envía.
`longitude`	number (double)	No	Longitud de la ubicación que se envía.
`address`	string	No	Dirección de la ubicación.
`name`	string	No	Nombre de la ubicación.
`url`	string	No	URL del sitio web desde donde el usuario descargó la información de la ubicación.

whatsappInboundMessage.button

Parámetro	Tipo	Obligatorio	Descripción
`payload`	string	No	La carga útil (payload) de un botón configurado por la empresa en el que el cliente hizo clic como parte de un mensaje interactivo.
`text`	string	No	Texto del botón.

whatsappInboundMessage.contacts[]

Parámetro	Tipo	Obligatorio	Descripción
`addresses`	object[]	No	Los elementos del arreglo se describen a continuación.
`birthday`	string	No	Cadena con formato `YYYY-MM-DD`.
`emails`	object[]	No	Los elementos del arreglo se describen a continuación.
`name`	object	Sí	Nombre completo del contacto formateado como un objeto name.
`org`	object	No	Información de la organización del contacto formateada como un objeto org.
`phones`	object[]	No	Número(s) de teléfono del contacto formateado(s) como un objeto phone.
`urls`	object[]	No	URL(s) del contacto formateada(s) como un objeto urls.
`vcard`	string	No	vCard opcional proporcionada con la carga útil del contacto compartido.
`origin`	string	No	Establecido en `contact_request` cuando el usuario compartió el contacto en respuesta a un mensaje request-contact-info.

whatsappInboundMessage.contacts[].addresses[]

Parámetro	Tipo	Obligatorio	Descripción
`street`	string	No	Número y nombre de la calle.
`city`	string	No	Nombre de la ciudad.
`state`	string	No	Abreviatura del estado o provincia.
`zip`	string	No	Código postal.
`country`	string	No	Nombre completo del país.
`country_code`	string	No	Abreviatura del país de dos letras.
`type`	string	No	Los valores estándar son `HOME` y `WORK`.

whatsappInboundMessage.contacts[].emails[]

Parámetro	Tipo	Obligatorio	Descripción
`email`	string	No	Dirección de correo electrónico.
`type`	string	No	Los valores estándar son `HOME` y `WORK`.

whatsappInboundMessage.contacts[].name

Parámetro	Tipo	Obligatorio	Descripción
`formatted_name`	string	Sí	Nombre completo, tal como aparece normalmente.
`first_name`	string	No	Nombre de pila.
`last_name`	string	No	Apellido.
`middle_name`	string	No	Segundo nombre.
`suffix`	string	No	Sufijo del nombre.
`prefix`	string	No	Prefijo del nombre.

whatsappInboundMessage.contacts[].org

Parámetro	Tipo	Obligatorio	Descripción
`company`	string	No	Nombre de la empresa del contacto.
`department`	string	No	Nombre del departamento del contacto.
`title`	string	No	Cargo laboral del contacto.

whatsappInboundMessage.contacts[].phones[]

Parámetro	Tipo	Obligatorio	Descripción
`phone`	string	No	Se completa automáticamente con el valor `wa_id` como un número de teléfono formateado.
`type`	string	No	Los valores estándar son `CELL`, `MAIN`, `IPHONE`, `HOME` y `WORK`.
`wa_id`	string	No	WhatsApp ID.

whatsappInboundMessage.contacts[].urls[]

Parámetro	Tipo	Obligatorio	Descripción
`url`	string	No	URL.
`type`	string	No	Los valores estándar son `HOME` y `WORK`.

whatsappInboundMessage.reaction

Parámetro	Tipo	Obligatorio	Descripción
`message_id`	string	Sí	Especifica el `wamid` del mensaje recibido que contenía la reacción.
`emoji`	string	No	Obligatorio cuando envías un mensaje `reaction`. Establécelo en `""` si quieres eliminar el emoji. Opcional cuando recibes un mensaje de un usuario. Este campo se incluye cuando un usuario reacciona a los mensajes con un emoji. De lo contrario, indica que un usuario eliminó el emoji.

whatsappInboundMessage.order

Parámetro	Tipo	Obligatorio	Descripción
`catalog_id`	string	No	El ID del catálogo.
`product_items`	object[]	No	Los elementos del array se describen a continuación.
`text`	string	No	Mensaje de texto enviado junto con el pedido.

whatsappInboundMessage.order.product_items[]

Parámetro	Tipo	Obligatorio	Descripción
`product_retailer_id`	string	No	El identificador SKU del producto.
`quantity`	integer (int32)	No	Cantidad de artículos.
`item_price`	number (double)	No	Precio unitario del artículo.
`currency`	string	No	Moneda del precio. Código de moneda ISO 4217.

whatsappInboundMessage.system

Parámetro	Tipo	Obligatorio	Descripción
`body`	string	No	Describe el evento del mensaje del sistema. Los casos de uso compatibles son: Actualización del número de teléfono: para cuando un usuario cambia de un número antiguo a uno nuevo. Actualización de identidad: para cuando la identidad de un usuario ha cambiado.
`wa_id`	string	No	Número de teléfono proporcionado por Meta, sin el `+` inicial. Puede mantenerse sin cambios u omitirse para un cambio de BSUID.
`user_id`	string	No	Nuevo ID de usuario específico del negocio suministrado por Meta para un cambio de número de teléfono o BSUID. Este campo conserva el nombre snake_case original.
`parent_user_id`	string	No	Nuevo BSUID principal para un cambio de número de teléfono o BSUID, solo cuando esté habilitado y sea proporcionado por Meta. Este campo conserva el nombre original en snake_case.
`previous_user_id`	string	No	ID de usuario anterior con alcance comercial suministrado por Meta.
`previous_parent_user_id`	string	No	BSUID principal anterior, solo cuando esté habilitado y sea proporcionado por Meta.
`type`	string	No	Los tipos admitidos son: `user_changed_user_id`: notificación de que un usuario cambió su BSUID. El número de teléfono puede permanecer sin cambios. `user_changed_number`: para una notificación de cambio de número de usuario. `user_identity_changed`: para una notificación de cambio de identidad de usuario.
`user`	string	No	Añadido a los Webhooks para actualizaciones de identidad. El nuevo ID de usuario de WhatsApp del cliente.
`new_wa_id`	string	No	Añadido a los Webhooks para actualizaciones del número de teléfono. Nuevo ID de WhatsApp del cliente.

whatsappInboundMessage.errors[]

Parámetro	Tipo	Obligatorio	Descripción
`code`	string	No	El código de error.
`title`	string	No	El título del error.
`message`	string	No	El mensaje de error.
`error_data`	object	No	Un objeto de datos de error con las siguientes propiedades: `details`: una cadena que describe el motivo del error. Ejemplo: `Message type is currently not supported.`.

whatsappInboundMessage.context

Parámetro	Tipo	Obligatorio	Descripción
`forwarded`	boolean	No	Se añade a los Webhooks si el mensaje fue reenviado. Se establece en `true` si el mensaje recibido ha sido reenviado.
`frequently_forwarded`	boolean	No	Se añade a los Webhooks si el mensaje se ha reenviado con frecuencia. Se establece en `true` si el mensaje recibido se ha reenviado más de cinco veces.
`from`	string	No	Se agrega a los Webhooks si el mensaje es una respuesta entrante a un mensaje enviado. El ID de WhatsApp (un número de teléfono sin el prefijo ’+’) del remitente del mensaje enviado.
`id`	string	No	Opcional. El `wamid` del mensaje enviado para una respuesta entrante. `wamid` es el ID del mensaje original en la plataforma de WhatsApp.
`referred_product`	object	No	Obligatorio para mensajes de consulta de producto. Especifica el producto sobre el cual el usuario solicita información. Consulta también Sell Products & Services.

whatsappInboundMessage.context.referred_product

Parámetro	Tipo	Obligatorio	Descripción
`catalog_id`	string	No	El ID del catálogo.
`product_retailer_id`	string	No	El identificador SKU del producto.

whatsappInboundMessage.referral

Parámetro	Tipo	Obligatorio	Descripción
`source_url`	string	No	Especifica la URL que lleva al anuncio o publicación en la que hizo clic el usuario. Abrir esta URL te lleva al anuncio que vio tu usuario.
`source_type`	string	No	Especifica el tipo de origen del anuncio. Los valores admitidos son “ad” o “post”.
`source_id`	string	No	Especifica el ID de Meta para un anuncio o publicación.
`headline`	string	No	Especifica el titular utilizado en el anuncio o publicación que generó el mensaje.
`body`	string	No	La descripción, o cuerpo, del anuncio o publicación que generó el mensaje.
`media_type`	string	No	Archivo multimedia presente en el anuncio o publicación en la que hizo clic el usuario. Los valores admitidos son “image” o “video”.
`image_url`	string	No	Se añade si media_type es “image”. Contiene una URL a la imagen original.
`video_url`	string	No	Se añade si media_type es “video”. Contiene una URL al video.
`thumbnail_url`	string	No	Se añade si media_type es “video”. Contiene una URL a la imagen en miniatura del video en el que se hizo clic.
`ctwa_clid`	string	No	ID de clic generado por Meta para anuncios que hacen clic a WhatsApp.

Ejemplo

El siguiente JSON es el cuerpo entregado a tu receptor. Los ID, números de teléfono y otros valores de cuenta son ilustrativos.

El usuario cambió de BSUID sin exponer un número de teléfono

{
  "id": "evt_system_user_id_changed_123",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "msg_system_user_id_changed_123",
    "wamid": "wamid.EXAMPLE_USER_ID_CHANGED",
    "wabaId": "whatsapp-business-account-id",
    "to": "+12025550123",
    "sendTime": "2026-10-10T08:00:00.000Z",
    "type": "system",
    "system": {
      "type": "user_changed_user_id",
      "previous_user_id": "US.13491208655302741918",
      "previous_parent_user_id": "US.ENT.11815799212886844830"
    }
  }
}

El usuario cambió de número con BSUID anteriores

{
  "id": "evt_system_number_changed_123",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "msg_system_number_changed_123",
    "wamid": "wamid.EXAMPLE_NUMBER_CHANGED",
    "wabaId": "whatsapp-business-account-id",
    "from": "+12025550124",
    "to": "+12025550123",
    "sendTime": "2026-10-10T08:00:00.000Z",
    "type": "system",
    "system": {
      "type": "user_changed_number",
      "previous_user_id": "US.13491208655302741918",
      "previous_parent_user_id": "US.ENT.11815799212886844830",
      "new_wa_id": "16315553333"
    }
  }
}

Mensaje entrante no compatible

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f8709b741c165b4342a714",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "errors": [
      {
        "code": "131051",
        "title": "Message type unknown",
        "message": "Message type unknown",
        "error_data": {
          "details": "Message type is currently not supported."
        }
      }
    ],
    "type": "unsupported"
  }
}

Mensaje de texto entrante

{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensaje de texto entrante activado por anuncios con clic a WhatsApp

{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "referral": {
      "source_url": "https://fb.me/xxx",
      "source_type": "ad",
      "source_id": "MEDIA-ID",
      "headline": "Chat with us",
      "media_type": "image",
      "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/xxx.jpg",
      "ctwa_clid": "feRgX__yiYtsI1HhjI2FRjyKInYlrU9cm9ml-Yl1MXp_fJy6Mwp-adZ-yLqOWX5CiZJYtjQERgKbAUetcwFXb_6FUYyOl9Kc6HFOBCd"
    }
  }
}

Mensaje de imagen entrante

{
  "id": "evt_eEkv5wsCJItpaH01",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87878509703399f3fd3d0",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "image",
    "image": {
      "link": "https://example.com/sample",
      "caption": "Go for a walk.",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjmP8smFJQEwYBnkGBUt1cx4qzFcnUhQ=",
      "mime_type": "image/jpeg"
    }
  }
}

Mensaje de video entrante

{
  "id": "evt_eEkwhYtqMPmYdsN3",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87991741c165b4342a797",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "video",
    "video": {
      "link": "https://example.com/sample",
      "caption": "Go for a walk.",
      "id": "919306472440541",
      "sha256": "xDzrSTubvTFnw3+s1WIlAbIFKjzAKi5tVViQNV8JWpg=",
      "mime_type": "video/mp4"
    }
  }
}

Mensaje de audio entrante

{
  "id": "evt_eEl1TDAcquZUxzLn",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87cd3509703399f3fd3f2",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "audio",
    "audio": {
      "link": "https://example.com/sample",
      "id": "712063723747110",
      "sha256": "AkRZDytLy2I1K1dOeL6pQOjYnPppgjtSCO9MQ+Cry0Q=",
      "mime_type": "audio/mpeg"
    }
  }
}

Mensaje de documento entrante

{
  "id": "evt_eEkz3y7V6TCqgkbK",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87b2e741c165b4342a79b",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "document",
    "document": {
      "link": "https://example.com/sample",
      "caption": "PDF example",
      "filename": "sample.pdf",
      "id": "948915536111569",
      "sha256": "EpvCtzTjYdq4exmqsfGbei+STgXxVqTC2toiZ80vmnk=",
      "mime_type": "application/pdf"
    }
  }
}

Mensaje de sticker entrante

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc1678741c165b4342b38e",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "sticker",
    "sticker": {
      "link": "https://example.com/sample",
      "id": "729118992174848",
      "sha256": "RZEEl5HVWT4S6C0PoOgjYCQVDWs5esIMJsjcDYI80ZE=",
      "mime_type": "image/webp"
    }
  }
}

Mensaje de ubicación entrante

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc18ae509703399f3fe000",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "location",
    "location": {
      "latitude": 1.40435,
      "longitude": 103.79304,
      "name": "Singapore Zoo",
      "address": "80 Mandai Lake Road Singapore 72",
      "url": "https://example.com/sample"
    }
  }
}

Mensaje de contactos entrante

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "contacts",
    "contacts": [
      {
        "addresses": [
          {
            "street": "<ADDRESS_STREET>",
            "city": "<ADDRESS_CITY>",
            "state": "<ADDRESS_STATE>",
            "zip": "<ADDRESS_ZIP>",
            "country": "<ADDRESS_COUNTRY>",
            "country_code": "<ADDRESS_COUNTRY_CODE>",
            "type": "HOME"
          }
        ],
        "birthday": "2001-01-01",
        "emails": [
          {
            "email": "recipient@example.com",
            "type": "WORK"
          }
        ],
        "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": "+447901614024",
            "wa_id": "447901614024",
            "type": "WORK"
          }
        ],
        "urls": [
          {
            "url": "<CONTACT_URL>",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}

Mensaje de reacción entrante

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.HBgNODYxNTcwMDA3NzE0NRUCABIYIEYyMzY3OUJBMzY2RkFFQkRDQjYyQ0Q5RDE1QjA2RUYyAA==",
      "emoji": "👍"
    }
  }
}

Mensaje de botón de plantilla entrante

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "button",
    "button": {
      "payload": "more_about_marketing_friday",
      "text": "Learn more"
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensaje interactivo entrante de respuesta de lista

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f73942741c165b43429f86",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "list_reply",
      "list_reply": {
        "id": "<LIST_SECTION_2_ROW_1_ID>",
        "title": "<SECTION_2_ROW_1_TITLE>",
        "description": "<SECTION_2_ROW_1_DESC>"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensaje interactivo entrante de respuesta de botón

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "<UNIQUE_BUTTON_ID_2>",
        "title": "<BUTTON_TITLE_2>"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensaje interactivo entrante de respuesta de flujo

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "nfm_reply",
      "nfm_reply": {
        "name": "flow",
        "body": "Sent",
        "response_json": "{\"flow_token\": \"<FLOW_TOKEN>\", \"optional_param1\": \"<value1>\", \"optional_param2\": \"<value2>\"}"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensaje de pedido entrante

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "order",
    "order": {
      "catalog_id": "the-catalog_id",
      "product_items": [
        {
          "product_retailer_id": "the-product-SKU-identifier",
          "quantity": 2,
          "item_price": 12.5,
          "currency": "price-currency"
        }
      ],
      "text": "text-message-sent-along-with-the-order"
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
    }
  }
}

Mensaje de consulta de producto entrante

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "Can I get this in another color?"
    },
    "context": {
      "referred_product": {
        "catalog_id": "catalog-ID",
        "product_retailer_id": "product-ID"
      }
    }
  }
}

Mensaje de solicitud de bienvenida entrante

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "request_welcome"
  }
}

Tras verificar la firma y aceptar el evento de forma duradera, devuelve una respuesta 2xx. Procesa las tareas lentas de forma asíncrona.

HTTP/1.1 200 OK

Para ver tutoriales de escenarios paso a paso, consulta los ejemplos comentados.

Primeros pasos

Guías

Endpoints

Webhook reference

whatsapp.inbound_message.received

Activadores

Sintaxis

Parámetros

Envoltorio del evento

Carga útil del evento

whatsappInboundMessage

Parámetros de objetos anidados

Ejemplo

​Activadores

​Sintaxis

​Parámetros

​Envoltorio del evento

​Carga útil del evento

​whatsappInboundMessage

Parámetros de objetos anidados

​Ejemplo

Activadores

Sintaxis

Parámetros

Envoltorio del evento

Carga útil del evento

whatsappInboundMessage

Ejemplo