Notificaciones de mensajes
Resumen para integración
- Entrega: WhatsApp → Concepto Móvil →
POSTa la URL de tu webhook (la que compartes con nuestro equipo de Operaciones), con un JSON en el cuerpo.- Formato: el objeto
valuede Meta sinmetadatanimessaging_product(ver Webhook).- Identificar al usuario:
from/recipient_ido, si no llega, el BSUID.- Tipos en esta página:
text,audio,document,image,location,video,voice,sticker,contacts,reaction,unsupported,edit,revoke(valores detype), además de notificaciones de error a nivel de cuenta
Mensajes, archivos, ubicaciones y contactos que te envía tu cliente. Todos llegan con la misma estructura general (contacts y messages) y el campo type indica el tipo de contenido. Las respuestas a mensajes interactivos, el carro de compras y las respuestas de Flows están en Respuestas de mensajes interactivos.
Estructura general
Estructura común a todas las notificaciones de mensajes.
Estructura
Campos de Estructura general:
Objeto contacts
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| profile | Objeto que contiene los datos del contacto | Object | Obligatorio |
| wa_id | Teléfono (con código de país) del usuario. Puede no llegar si el usuario tiene nombre de usuario (ver Nombres de usuario y BSUID). | String | Condicional |
| user_id | BSUID del usuario. Siempre llega. | String | Obligatorio |
| parent_user_id | BSUID principal. Solo llega si el negocio tiene portafolios vinculados. | String | Opcional |
Objeto messages
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| from | Teléfono (con código de país) que envió el mensaje. Puede no llegar si el usuario tiene nombre de usuario. | String | Condicional |
| from_user_id | BSUID del usuario que envió el mensaje. Siempre llega. | String | Obligatorio |
| from_parent_user_id | BSUID principal del usuario. Solo llega si el negocio tiene portafolios vinculados. | String | Opcional |
| id | Identificador del mensaje | String | Obligatorio |
| timestamp | Fecha y hora de envío de mensaje | String | Obligatorio |
| type | De acuerdo al tipo de mensaje, el valor puede ser:
| String | Obligatorio |
| group_id | Identificador del grupo al que pertenece el mensaje. Solo llega cuando el mensaje proviene de un grupo. | String | Condicional |
| text | Objeto que contiene el texto del mensaje | Object | Opcional |
| audio | Objeto que contiene los datos del audio | Object | Opcional |
| document | Objeto que contiene los datos del documento | Object | Opcional |
| image | Objeto que contiene los datos de la imagen | Object | Opcional |
| location | Objeto que contiene los datos de la ubicación | Object | Opcional |
| video | Objeto que contiene los datos del video | Object | Opcional |
| voice | Objeto que contiene los datos del mensaje de voz | Object | Opcional |
| sticker | Objeto que contiene los datos del sticker | Object | Opcional |
| interactive | Objeto que contiene los datos de mensajes interactivos | Object | Opcional |
| button | Objeto que contiene el texto de repuesta rápida | Object | Opcional |
| context | Objeto que contiene información relacionada a los siguientes casos:
| Object | Se enviará en los siguientes casos:
|
| contacts | Arreglo con los datos del contacto compartido. | Arreglo de objetos | Obligatorio cuando se recibe una notificación de contacto compartido. |
| reaction | Objeto que contiene los datos de una reacción a un mensaje. | Object | Opcional |
| referral | Objeto con los datos del anuncio click-to-WhatsApp del que proviene el usuario. Cuando llega, el campo text.body se concatena con el valor de referral.source_url. | Object | Opcional |
Objeto profile
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| name | Nombre del contacto que envió el mensaje | String | Obligatorio |
| username | Nombre de usuario. Solo llega si el usuario tiene uno activo. | String | Opcional |
Texto
El campo type es "text".
Estructura
Campos de Texto:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| body | Texto del Mensaje. | String | Obligatorio. |
Ejemplo
Ejemplo completo de Texto:
{"contacts": [{"profile": {"name": "Héctor"},"wa_id": "5215500000001"}],"messages": [{"from": "5215500000001","id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA","timestamp": "1617061836","type": "text","text": {"body": "Hola amigo"}}]}
Nota (Números de Brasil): para números mexicanos con prefijo 55 y menos de 13 dígitos, la plataforma inserta un "9" después del código de área en
contacts[0].wa_idymessages[0].fromantes de entregar la notificación.
Texto de un usuario con nombre de usuario
El usuario tiene nombre de usuario y su número de teléfono no está disponible, así que solo llegan su BSUID y su nombre de usuario.
{"contacts": [{"profile": {"name": "test user name","username": "@testusername"},"user_id": "US.13491208655302741918","parent_user_id": "US.ENT.506847293015824"}],"messages": [{"id": "ABGGFlA5Fpa","timestamp": "1504902988","from_user_id": "US.13491208655302741918","type": "text","text": {"body": "this is a text message"}}]}
El usuario tiene nombre de usuario y su número de teléfono está disponible, así que llegan todos los campos.
{"contacts": [{"profile": {"name": "test user name","username": "@testusername"},"wa_id": "16315551181","user_id": "US.13491208655302741918","parent_user_id": "US.ENT.506847293015824"}],"messages": [{"id": "ABGGFlA5Fpa","timestamp": "1504902988","from": "16315551181","from_user_id": "US.13491208655302741918","type": "text","text": {"body": "this is a text message"}}]}
Audio
El campo type es "audio".
Estructura
Campos de Audio:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| id | Identificador del archivo. | String | Obligatorio. |
| mime_type | Tipo de archivo. | String | Obligatorio. |
| sha256 | Checksum del archivo. | String | Obligatorio. |
Ejemplo
Ejemplo completo de Audio:
{"contacts": [{"profile": {"name": "Héctor"},"wa_id": "5215500000001"}],"messages": [{"from": "5215500000001","id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA","timestamp": "1617061836","type": "audio","audio": {"id": "6b6f751e-5757-4652-bf51-fb4ce7445533","mime_type": "audio/mpeg","sha256": "693cddca479f19817d300d743849e1a69f045b97f65c08339c2f9d9e0c16cb6f"}}]}
Documento
El campo type es "document".
Estructura
Campos de Documento:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| id | Identificador del archivo. | String | Obligatorio. |
| mime_type | Tipo de archivo. | String | Obligatorio. |
| sha256 | Checksum del archivo. | String | Obligatorio. |
| caption | Texto que acompaña al documento. | String | Opcional. |
| filename | Nombre del archivo en el dispositivo del remitente. | String | Obligatorio. |
Ejemplo
Ejemplo completo de Documento:
{"contacts": [{"profile": {"name": "Héctor"},"wa_id": "5215500000001"}],"messages": [{"from": "5215500000001","id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA","timestamp": "1617061836","type": "document","document": {"caption": "smppdoc.pdf","filename": "smppdoc.pdf","id": "a26072ab-a20e-4c2b-9595-929a92fb3f9e","mime_type": "application/pdf","sha256":"c29f4d7461ddca08fd58db1f716610a2b3f36f9c0f2620bf4f5ea9b698f0912b"}}]}
Imagen
El campo type es "image".
Estructura
Campos de Imagen:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| id | Identificador del archivo. | String | Obligatorio. |
| mime_type | Tipo de archivo. | String | Obligatorio. |
| sha256 | Checksum del archivo. | String | Obligatorio. |
| caption | Texto que acompaña a la imagen. | String | Opcional. |
Ejemplo
Ejemplo completo de Imagen:
{"contacts": [{"profile": {"name": "Héctor"},"wa_id": "5215500000001"}],"messages": [{"from": "5215500000001","id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA","timestamp": "1617061836","type": "image","image": {"id": "647b9f5d-89fb-43fc-9708-49b067d49766","mime_type": "image/jpeg","sha256": "1b78676c0af68ec66b71b7b09803e68d698db7891c7b0820b24a35c82535b06c"}}]}
Ubicación
El campo type es "location".
Estructura
Campos de Ubicación:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| address | Dirección. | String | Opcional. |
| latitude | Latitud. | Number | Obligatorio. |
| longitude | Longitud. | Number | Obligatorio. |
| name | Nombre de la ubicación. | String | Opcional. |
| url | URL del sitio web de donde el usuario descargó la información de la ubicación. | String | Opcional. |
Ejemplo
Ejemplo completo de Ubicación:
{"contacts": [{"profile": {"name": "Héctor"},"wa_id": "5215500000001"}],"messages": [{"from": "5215500000001","id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA","timestamp": "1617061836","type": "location","location": {"latitude": 19.5386,"longitude": -99.15124}}]}
Video
El campo type es "video".
Estructura
Campos de Video:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| id | Identificador del archivo. | String | Obligatorio. |
| mime_type | Tipo de archivo. | String | Obligatorio. |
| sha256 | Checksum del archivo. | String | Obligatorio. |
| caption | Texto/Título que asigna el usuario al archivo que envía | String | Opcional, solo se encuentra presente si el usuario lo escribe. |
Ejemplo
Ejemplo completo de Video:
{"contacts": [{"profile": {"name": "Héctor"},"wa_id": "5215500000001"}],"messages": [{"from": "5215500000001","id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA","timestamp": "1617061836","type": "video","video": {"id": "a2936494-0747-462a-9381-5e5d6672ce33","mime_type": "video/mp4","sha256":"ca5c888f78787f62efe3b382a8b243556dbb982f0e2c585adfd8d0b4808d5d99"}}]}
Mensaje de voz
El campo type es "voice".
Estructura
Campos de Mensaje de voz:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| id | Identificador del archivo. | String | Obligatorio |
| mime_type | Tipo de archivo. | String | Obligatorio |
| sha256 | Checksum del archivo. | String | Obligatorio |
| caption | Texto/Título que asigna el usuario al archivo que envía. | String | Opcional, solo se encuentra presente si el usuario lo escribe. |
Ejemplo
Ejemplo completo de Mensaje de voz:
{"contacts": [{"profile": {"name": "Juan Pérez"},"wa_id": "5215500000001"}],"messages": [{"from": "5215500000001","id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA","timestamp": "1617061836","type": "voice","voice": {"id": "e091fa61-d8dc-41c4-967b-e6a163ba21c2","mime_type": "audio/ogg; codecs=opus","sha256":"acd78d57200637690bcca16239dd452fc4e5bb8b817c85b58452abfe28ab8f2e"}}]}
Sticker
El campo type es "sticker".
Estructura
Campos de Sticker:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| id | Identificador del archivo. | String | Obligatorio. |
| mime_type | Tipo de archivo. | String | Obligatorio. |
| sha256 | Checksum del archivo. | String | Obligatorio. |
| animated | Animado. | Boolean | Obligatorio. |
Ejemplo
Ejemplo completo de Sticker:
{"contacts": [{"profile": {"name": "Juan Pérez"},"wa_id": "5215500000001"}],"messages": [{"from": "5215500000001","id": "wamid.HBgNNTIxNTUyMDc3NzA1OBUCABIYFDNBMDRDRTJDODlFQ0Q5Mzc5RkUzAA==","timestamp": "1617061836","type": "sticker","sticker": {"id": "647b9f5d-89fb-43fc-9708-49b067d49766","mime_type": "image/webp","sha256": "mCZ/7a6sZ6TMa14YokRCSfultjY6aQEVE5Z11TpjsP8=","animated": false}}]}
Reaction
El campo type es "reaction". El usuario reaccionó con un emoji a un mensaje enviado previamente.
Estructura
Campos de Reaction:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| message_id | Identificador del mensaje al que se reacciona. Corresponde al id interno devuelto por la API de envío. | String | Obligatorio |
| emoji | Emoji con el que el usuario reaccionó. | String | Obligatorio |
Referral
Objeto referral presente cuando el mensaje proviene de un anuncio click-to-WhatsApp. Cuando llega, el campo text.body del mensaje se concatena con un espacio y el valor de referral.source_url.
Estructura
Campos de Referral:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| source_url | URL del anuncio. | String | Obligatorio |
| source_id | Identificador del anuncio. | String | Opcional |
| source_type | Tipo de fuente (p. ej. "ad", "post"). | String | Opcional |
| headline | Encabezado del anuncio. | String | Opcional |
| body | Cuerpo del anuncio. | String | Opcional |
| image | Imagen asociada al anuncio. | String | Opcional |
Contacto compartido
El campo type es "contacts".
Estructura
Campos de Contacto compartido:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| from | Teléfono (con código de país) del remitente del mensaje. | String | Obligatorio. |
| type | El valor debe ser "contacts". | String | Obligatorio |
| contacts | Arreglo con los datos del contacto compartido. | Arreglo de objetos | Obligatorio. |
Objeto contacts compartido
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| birthday | Fecha de nacimiento del Contacto. | String | Opcional. |
| addresses | Direcciones del Contacto. | Arreglo de objetos | Opcional. |
| emails | Emails del Contacto. | Arreglo de objetos | Opcional. |
| name | Nombre del Contacto. | Object | Obligatorio. |
| org | Compañía del Contacto. | Object | Opcional. |
| phones | Teléfonos del Contacto. | Arreglo de objetos | Opcional. |
| urls | URLs del Contacto. | Arreglo de objetos | Opcional. |
Objeto addresses
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| city | Ciudad. | String | Opcional. |
| country | País. | String | Opcional. |
| country_code | Código de país ISO. | String | Opcional. |
| state | Estado. | String | Opcional. |
| street | Calle. | String | Opcional. |
| type | Los valores podrán ser: WORK, HOME. | String | Opcional. |
| zip | Código Postal. | String | Opcional. |
Objeto emails
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| Correo del Contacto. | String | Opcional. | |
| type | Los valores podrán ser: WORK. | String | Opcional. |
Objeto name
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| first_name | Nombre del Contacto. | String | Obligatorio si middle_name y last_name no tienen valor. |
| middle_name | Segundo nombre del contacto. | String | Obligatorio si first_name y last_name no tienen valor. |
| last_name | Apellido del Contacto. | String | Obligatorio si middle_name y first_name no tienen valor. |
| formatted_name | Nombre Completo. | String | Obligatorio. |
| prefix | Prefijo del nombre (p. ej. "Dr.", "Sr."). | String | Opcional. |
| suffix | Sufijo del nombre (p. ej. "Jr.", "III"). | String | Opcional. |
Objeto org
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| company | Nombre de la compañía. | String | Obligatorio |
| department | Departamento. | String | Opcional |
| title | Puesto/cargo. | String | Opcional |
Objeto phones
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| phone | Teléfono del Contacto. | String | Obligatorio. |
| type | Los valores podrán ser: WORK, HOME. | String | Obligatorio. |
| wa_id | WhatsApp ID (número con código de país) del contacto. | String | Opcional. |
Objeto urls
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| url | URL del contacto. | String | Obligatorio. |
| type | Los valores podrán ser: WORK. | String | Obligatorio. |
Ejemplo
Ejemplo completo de Contacto compartido:
{"contacts": [{"profile": {"name": "Juan Pérez"},"wa_id": "5215500000001"}],"messages": [{"from": "5215500000001","id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA","timestamp": "1617061836","type": "contacts","contacts": [{"addresses": [],"contact_image": "/9j/4AAQSkZJRgABAQEAZABkAAD","emails": [{"email": "test@mail.com","type": "Otro"}],"ims": [],"name": {"first_name": "Juan","formatted_name": "Juan Pérez","last_name": "Pérez"},"org": {},"phones": [{"phone": "+1 (000) 111-1111","type": "Móvil"}],"urls": [{"type": "PROFILE","url": "http://www.google.com/profiles/1012231243417990451811"}]}]}]}
Mensaje no soportado
El campo type es "unsupported". Se envía cuando el usuario manda un tipo de mensaje que Cloud API no soporta, o en algunos otros casos (por ejemplo, el primer mensaje de un usuario cuyo negocio se incorporó con la app de WhatsApp Business). El mensaje incluye un arreglo errors y un objeto unsupported.
Estructura
Campos de Mensaje no soportado:
Objeto unsupported
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| type | Tipo de mensaje no soportado. Posibles valores:
| String | Obligatorio |
Objeto errors
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| code | Código de error. Posibles valores:
| Number | Obligatorio |
| title | Título del error. | String | Obligatorio |
| message | Mensaje del error. Mismo valor que title. | String | Opcional |
| error_data.details | Descripción legible del error. | String | Opcional |
Ejemplo
Ejemplo completo de Mensaje no soportado:
{"contacts": [{"profile": {"name": "Héctor"},"wa_id": "5215500000001","user_id": "US.13491208655302741918"}],"messages": [{"from": "5215500000001","from_user_id": "US.13491208655302741918","id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA","timestamp": "1617061836","errors": [{"code": 131051,"title": "Message type unknown","message": "Message type unknown","error_data": {"details": "Message type is currently not supported."}}],"type": "unsupported","unsupported": {"type": "poll_update"}}]}
Mensaje editado
El campo type es "edit". Se envía cuando el usuario edita un mensaje que envió previamente (texto, o multimedia con pie de foto), dentro de los 15 minutos posteriores a su envío. El objeto edit contiene el ID del mensaje original y el nuevo contenido.
Nota: la notificación de edición solo está disponible para los negocios que usan la app de WhatsApp Business (Coexistence).
Estructura
Campos de Mensaje editado:
Objeto edit
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| original_message_id | ID del mensaje original que se editó. | String | Obligatorio |
| message | El contenido editado. Incluye su propio type y el objeto específico del tipo correspondiente (por ejemplo text o image), y un context opcional. | Object | Obligatorio |
Ejemplo
Ejemplo completo de Mensaje editado:
{"contacts": [{"profile": {"name": "Héctor"},"wa_id": "5215500000001","user_id": "US.13491208655302741918"}],"messages": [{"from": "5215500000001","from_user_id": "US.13491208655302741918","id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=","timestamp": "1749854575","type": "edit","edit": {"original_message_id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA=","message": {"context": {"id": "M0"},"type": "image","image": {"caption": "Updated image caption","mime_type": "image/jpeg","sha256": "a1b2c3d4e5f6...","id": "1234567890"}}}}]}
Mensaje eliminado
El campo type es "revoke". Se envía cuando el usuario elimina un mensaje que envió previamente, dentro de los dos días posteriores a su envío. El objeto revoke contiene el ID del mensaje eliminado.
Nota: la notificación de eliminación solo está disponible para los negocios que usan la app de WhatsApp Business (Coexistence).
Estructura
Campos de Mensaje eliminado:
Objeto revoke
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| original_message_id | ID del mensaje original que se eliminó. | String | Obligatorio |
Ejemplo
Ejemplo completo de Mensaje eliminado:
{"contacts": [{"profile": {"name": "Héctor"},"wa_id": "5215500000001","user_id": "US.13491208655302741918"}],"messages": [{"from": "5215500000001","from_user_id": "US.13491208655302741918","id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=","timestamp": "1749854575","type": "revoke","revoke": {"original_message_id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA="}}]}
Notificación de error
Error a nivel de cuenta, app o sistema que impidió procesar una solicitud. Llega en un arreglo errors en el nivel superior de la notificación, sin los arreglos contacts ni messages.
Estructura
Campos de Notificación de error:
Objeto errors
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| code | Código de error. Para más detalle, consulta Códigos de error. | Number | Obligatorio |
| title | Título del error. | String | Obligatorio |
| message | Mensaje del error. Mismo valor que title. | String | Opcional |
| error_data.details | Descripción legible del error. | String | Opcional |
| href | Enlace a la documentación del código de error. | String | Opcional |
Ejemplo
Ejemplo completo de Notificación de error:
{"errors": [{"code": 130429,"title": "Rate limit hit","message": "Rate limit hit","error_data": {"details": "Message failed to send because there were too many messages sent from this phone number in a short period of time"},"href": "https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes"}]}
