logo
enes

Notificaciones de mensajes

Last update: 4 days ago by Irais Aguirre

Resumen para integración

  • Entrega: WhatsApp → Concepto Móvil → POST a la URL de tu webhook (la que compartes con nuestro equipo de Operaciones), con un JSON en el cuerpo.
  • Formato: el objeto value de Meta sin metadata ni messaging_product (ver Webhook).
  • Identificar al usuario: from/recipient_id o, si no llega, el BSUID.
  • Tipos en esta página: text, audio, document, image, location, video, voice, sticker, contacts, reaction, unsupported, edit, revoke (valores de type), 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:

NombreDescripciónTipoRequerimientos
contactsArreglo con los datos del contacto que envió el mensaje.Arreglo de objetosObligatorio
messagesArreglo con los datos del mensaje enviado.Arreglo de objetosObligatorio

Objeto contacts

NombreDescripciónTipoRequerimientos
profileObjeto que contiene los datos del contactoObjectObligatorio
wa_idTelé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).StringCondicional
user_idBSUID del usuario. Siempre llega.StringObligatorio
parent_user_idBSUID principal. Solo llega si el negocio tiene portafolios vinculados.StringOpcional

Objeto messages

NombreDescripciónTipoRequerimientos
fromTeléfono (con código de país) que envió el mensaje. Puede no llegar si el usuario tiene nombre de usuario.StringCondicional
from_user_idBSUID del usuario que envió el mensaje. Siempre llega.StringObligatorio
from_parent_user_idBSUID principal del usuario. Solo llega si el negocio tiene portafolios vinculados.StringOpcional
idIdentificador del mensajeStringObligatorio
timestampFecha y hora de envío de mensajeStringObligatorio
typeDe acuerdo al tipo de mensaje, el valor puede ser:
  • text
  • audio
  • document
  • image
  • location
  • video
  • voice
  • button (respuestas rápidas)
  • contacts
  • interactive
  • order
  • sticker
  • reaction
  • system
  • unsupported
  • edit (solo Coexistence)
  • revoke (solo Coexistence)
StringObligatorio
group_idIdentificador del grupo al que pertenece el mensaje. Solo llega cuando el mensaje proviene de un grupo.StringCondicional
textObjeto que contiene el texto del mensajeObjectOpcional
audioObjeto que contiene los datos del audioObjectOpcional
documentObjeto que contiene los datos del documentoObjectOpcional
imageObjeto que contiene los datos de la imagenObjectOpcional
locationObjeto que contiene los datos de la ubicaciónObjectOpcional
videoObjeto que contiene los datos del videoObjectOpcional
voiceObjeto que contiene los datos del mensaje de vozObjectOpcional
stickerObjeto que contiene los datos del stickerObjectOpcional
interactiveObjeto que contiene los datos de mensajes interactivosObjectOpcional
buttonObjeto que contiene el texto de repuesta rápidaObjectOpcional
contextObjeto que contiene información relacionada a los siguientes casos:
  • cuando se recibe una notificación de tipo button
  • cuando el cliente responde haciendo referencia a un mensaje propio o enviado por el negocio
  • cuando el mensaje ha sido reenviado
  • cuando el negocio envía un mensaje que menciona a uno o más teléfonos y su cliente responde haciendo referencia a este mensaje
ObjectSe enviará en los siguientes casos:
  • cuando se recibe una notificación de tipo button
  • cuando el cliente responde haciendo referencia a un mensaje propio o enviado por el negocio
  • cuando el mensaje ha sido reenviado
  • cuando el negocio envía un mensaje que menciona a uno o más teléfonos y su cliente responde haciendo referencia a este mensaje
contactsArreglo con los datos del contacto compartido.Arreglo de objetosObligatorio cuando se recibe una notificación de contacto compartido.
reactionObjeto que contiene los datos de una reacción a un mensaje.ObjectOpcional
referralObjeto 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.ObjectOpcional

Objeto profile

NombreDescripciónTipoRequerimientos
nameNombre del contacto que envió el mensajeStringObligatorio
usernameNombre de usuario. Solo llega si el usuario tiene uno activo.StringOpcional


Texto

El campo type es "text".

Estructura

Campos de Texto:

NombreDescripciónTipoRequerimientos
bodyTexto del Mensaje.StringObligatorio.

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_id y messages[0].from antes 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:

NombreDescripciónTipoRequerimientos
idIdentificador del archivo.StringObligatorio.
mime_typeTipo de archivo.StringObligatorio.
sha256Checksum del archivo.StringObligatorio.

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:

NombreDescripciónTipoRequerimientos
idIdentificador del archivo.StringObligatorio.
mime_typeTipo de archivo.StringObligatorio.
sha256Checksum del archivo.StringObligatorio.
captionTexto que acompaña al documento.StringOpcional.
filenameNombre del archivo en el dispositivo del remitente.StringObligatorio.

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:

NombreDescripciónTipoRequerimientos
idIdentificador del archivo.StringObligatorio.
mime_typeTipo de archivo.StringObligatorio.
sha256Checksum del archivo.StringObligatorio.
captionTexto que acompaña a la imagen.StringOpcional.

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:

NombreDescripciónTipoRequerimientos
addressDirección.StringOpcional.
latitudeLatitud.NumberObligatorio.
longitudeLongitud.NumberObligatorio.
nameNombre de la ubicación.StringOpcional.
urlURL del sitio web de donde el usuario descargó la información de la ubicación.StringOpcional.

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:

NombreDescripciónTipoRequerimientos
idIdentificador del archivo.StringObligatorio.
mime_typeTipo de archivo.StringObligatorio.
sha256Checksum del archivo.StringObligatorio.
captionTexto/Título que asigna el usuario al archivo que envíaStringOpcional, 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:

NombreDescripciónTipoRequerimientos
idIdentificador del archivo.StringObligatorio
mime_typeTipo de archivo.StringObligatorio
sha256Checksum del archivo.StringObligatorio
captionTexto/Título que asigna el usuario al archivo que envía.StringOpcional, 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:

NombreDescripciónTipoRequerimientos
idIdentificador del archivo.StringObligatorio.
mime_typeTipo de archivo.StringObligatorio.
sha256Checksum del archivo.StringObligatorio.
animatedAnimado.BooleanObligatorio.

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:

NombreDescripciónTipoRequerimientos
message_idIdentificador del mensaje al que se reacciona. Corresponde al id interno devuelto por la API de envío.StringObligatorio
emojiEmoji con el que el usuario reaccionó.StringObligatorio


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:

NombreDescripciónTipoRequerimientos
source_urlURL del anuncio.StringObligatorio
source_idIdentificador del anuncio.StringOpcional
source_typeTipo de fuente (p. ej. "ad", "post").StringOpcional
headlineEncabezado del anuncio.StringOpcional
bodyCuerpo del anuncio.StringOpcional
imageImagen asociada al anuncio.StringOpcional


Contacto compartido

El campo type es "contacts".

Estructura

Campos de Contacto compartido:

NombreDescripciónTipoRequerimientos
fromTeléfono (con código de país) del remitente del mensaje.StringObligatorio.
typeEl valor debe ser "contacts".StringObligatorio
contactsArreglo con los datos del contacto compartido.Arreglo de objetosObligatorio.

Objeto contacts compartido

NombreDescripciónTipoRequerimientos
birthdayFecha de nacimiento del Contacto.StringOpcional.
addressesDirecciones del Contacto.Arreglo de objetosOpcional.
emailsEmails del Contacto.Arreglo de objetosOpcional.
nameNombre del Contacto.ObjectObligatorio.
orgCompañía del Contacto.ObjectOpcional.
phonesTeléfonos del Contacto.Arreglo de objetosOpcional.
urlsURLs del Contacto.Arreglo de objetosOpcional.

Objeto addresses

NombreDescripciónTipoRequerimientos
cityCiudad.StringOpcional.
countryPaís.StringOpcional.
country_codeCódigo de país ISO.StringOpcional.
stateEstado.StringOpcional.
streetCalle.StringOpcional.
typeLos valores podrán ser: WORK, HOME.StringOpcional.
zipCódigo Postal.StringOpcional.

Objeto emails

NombreDescripciónTipoRequerimientos
emailCorreo del Contacto.StringOpcional.
typeLos valores podrán ser: WORK.StringOpcional.

Objeto name

NombreDescripciónTipoRequerimientos
first_nameNombre del Contacto.StringObligatorio si middle_name y last_name no tienen valor.
middle_nameSegundo nombre del contacto.StringObligatorio si first_name y last_name no tienen valor.
last_nameApellido del Contacto.StringObligatorio si middle_name y first_name no tienen valor.
formatted_nameNombre Completo.StringObligatorio.
prefixPrefijo del nombre (p. ej. "Dr.", "Sr.").StringOpcional.
suffixSufijo del nombre (p. ej. "Jr.", "III").StringOpcional.

Objeto org

NombreDescripciónTipoRequerimientos
companyNombre de la compañía.StringObligatorio
departmentDepartamento.StringOpcional
titlePuesto/cargo.StringOpcional

Objeto phones

NombreDescripciónTipoRequerimientos
phoneTeléfono del Contacto.StringObligatorio.
typeLos valores podrán ser: WORK, HOME.StringObligatorio.
wa_idWhatsApp ID (número con código de país) del contacto.StringOpcional.

Objeto urls

NombreDescripciónTipoRequerimientos
urlURL del contacto.StringObligatorio.
typeLos valores podrán ser: WORK.StringObligatorio.

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

NombreDescripciónTipoRequerimientos
typeTipo de mensaje no soportado. Posibles valores:
  • button
  • edit
  • errors
  • gif
  • group_invite
  • hsm
  • image
  • interactive
  • keep_in_chat
  • link_preview
  • list
  • location
  • media_placeholder
  • order
  • pin
  • poll_creation
  • poll_update
  • product
  • reaction
StringObligatorio

Objeto errors

NombreDescripciónTipoRequerimientos
codeCódigo de error. Posibles valores:
  • 131051: el tipo de mensaje no es soportado.
  • 131060: el mensaje no está disponible actualmente.
NumberObligatorio
titleTítulo del error.StringObligatorio
messageMensaje del error. Mismo valor que title.StringOpcional
error_data.detailsDescripción legible del error.StringOpcional

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

NombreDescripciónTipoRequerimientos
original_message_idID del mensaje original que se editó.StringObligatorio
messageEl contenido editado. Incluye su propio type y el objeto específico del tipo correspondiente (por ejemplo text o image), y un context opcional.ObjectObligatorio

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

NombreDescripciónTipoRequerimientos
original_message_idID del mensaje original que se eliminó.StringObligatorio

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

NombreDescripciónTipoRequerimientos
codeCódigo de error. Para más detalle, consulta Códigos de error.NumberObligatorio
titleTítulo del error.StringObligatorio
messageMensaje del error. Mismo valor que title.StringOpcional
error_data.detailsDescripción legible del error.StringOpcional
hrefEnlace a la documentación del código de error.StringOpcional

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"
}
]
}


Whatsapp — Anterior
Webhook
Siguiente — Whatsapp
Respuestas de mensajes interactivos