Wiki Toolbox

Notificaciones de Mensajes Entrantes

Webhooks

Los webhooks son devoluciones de llamadas HTTP definidas por el usuario que se generan a partir de eventos específicos. Cada vez que ocurre uno de estos eventos, el cliente de la API de WhatsApp Business lo detecta, recopila los datos y envía inmediatamente una notificación (solicitud HTTP) a la URL del webhook especificada en la configuración de la aplicación para actualizar el estado de los mensajes enviados o indicar la recepción de un mensaje.

Este documento abarca lo siguiente:

  • Requisitos
  • Formato del webhook de notificaciones
  • Errores de las notificaciones

Cuando un cliente te envíe un mensaje, el cliente de la API de WhatsApp Business enviará una notificación de solicitud POST de HTTP a la URL del webhook con los detalles que se describen en los siguientes documentos:

  • Notificaciones de mensajes entrantes
  • Notificaciones de mensajes multimedia entrantes
  • Respuestas entrantes a mensajes enviados
  • Mensajes entrantes del sistema
  • Notificaciones de estado de mensajes salientes

TIP

Es importante que el webhook devuelva una respuesta HTTPS 200 OK a las notificaciones. De lo contrario, el cliente de la API de WhatsApp Business considerará que ocurrió un error con la notificación y volverá a intentarlo posteriormente.

Requisitos

Para implementar un webhook activo que pueda recibir eventos de webhook desde la API de WhatsApp Business, el código debe tener lo siguiente:

  • Compatibilidad con HTTPS
  • Un certificado SSL válido

Configuracion de las Notificaciones

Siguiendo las instrucciones de la documentación sobre la configuración de la aplicación, realiza la siguiente configuración para las notificaciones de los webhooks:

  • Webhooks Proporciona la URL para tu webhook. Esto es OBLIGATORIO cuando usas webhooks. Si no se configura la URL del webhook, las devoluciones de llamadas se interrumpen. Consulta la aplicación de ejemplo para pruebas a fin de conocer una manera sencilla de ver y probar los webhooks.

  • sent_status Especifica si quieres recibir notificaciones cuando el servidor recibe un mensaje. De manera predeterminada, las notificaciones están desactivadas.

  • callback_persist Selecciona si quieres almacenar las devoluciones de llamada en el disco hasta que el webhook las reconozca correctamente. Las notificaciones que no se reconocen correctamente (es decir, que no reciben la respuesta HTTPS 200) se reintentan por tiempo indefinido. Usa esta configuración para definir los reintentos.

Formato general de un webhook

El webhook debe tener un campo de matriz de nivel superior que indique lo que se comunica. Los miembros de la matriz son objetos JSON con campos detallados pertinentes para el webhook.

NombreTipo
messagesNotificaciones de mensajes entrantes
statusesActualizaciones de estados de mensajes
errorsErrores fuera de banda serios

TIP

Siempre que sea posible, los nombres de names se mantienen constantes a lo largo de las funciones. Por ejemplo, todas las marcas de tiempo se denominan timestamp.

Formato del webhook de notificaciones

A continuación se muestran todos los campos posibles del webhook de notificaciones.

  {
            "contacts":[
               {
                  "profile":{
                     "name":"sender-profile-name"
                  },
                  "wa_id":"wa-id-of-contact"
               }
            ],
            "messages":[
               "context":{
                  "from":"sender-wa-id-of-context-message",
                  "group_id":"group-id-of-context-message",
                  "id":"message-id-of-context-message",
                  "mentions":[
                     "wa-id1",
                     "wa-id2"
                  ]
               },
               "from":"sender-wa-id",
               "group_id":"group-id",
               "id":"message-id",
               "timestamp":"message-timestamp",
               "type":"audio | document | image | location | system | text | video | voice",
               "errors":[
                  {
                     "..."
                  }
               ],
               "audio":{
                  "file":"absolute-filepath-on-coreapp",
                  "id":"media-id",
                  "link":"link-to-audio-file",
                  "mime_type":"media-mime-type",
                  "sha256":"checksum"
               }"document":{
                  "file":"absolute-filepath-on-coreapp",
                  "id":"media-id",
                  "link":"link-to-document-file",
                  "mime_type":"media-mime-type",
                  "sha256":"checksum",
                  "caption":"document-caption"
               }"image":{
                  "file":"absolute-filepath-on-coreapp",
                  "id":"media-id",
                  "link":"link-to-image-file",
                  "mime_type":"media-mime-type",
                  "sha256":"checksum",
                  "caption":"image-caption"
               }"location":{
                  "address":"1 Hacker Way, Menlo Park, CA, 94025",
                  "latitude":"latitude",
                  "longitude":"longitude",
                  "name":"location-name"
               }"system":{
                  "body":"system-message-content"
               }"text":{
                  "body":"text-message-content"
               }"video":{
                  "file":"absolute-filepath-on-coreapp",
                  "id":"media-id",
                  "link":"link-to-video-file",
                  "mime_type":"media-mime-type",
                  "sha256":"checksum"
               }"voice":{
                  "file":"absolute-filepath-on-coreapp",
                  "id":"media-id",
                  "link":"link-to-audio-file",
                  "mime_type":"media-mime-type",
                  "sha256":"checksum"
               }
            ]
         }

Errores de las notificaciones

Cuando ocurran errores fuera de banda durante el funcionamiento normal de la aplicación, la matriz errors incluirá una descripción del error. Este tipo de errores se deben a problemas temporales de conectividad de la red, credenciales no válidas, controladores de administración no disponibles, etc. En caso de que ocurra un error, consulta los mensajes de error y de estado para obtener más información.

Ejemplo

   "POST /"{
              "errors":[
                 {
                    "code":"error-code",
                    "title":"error-title",
                    "details":"error-description",
                    "href":"location for error detail"
                 },
                 {
                    "..."
                 }
              ]
           }

Objeto errors

El objeto errors contiene los siguientes parámetros:

Nombre del campoDescripciónTipo
codeCódigo de errorNumerico
titleTítulo del errorCadena
detailsOpcional. Se detalla el error si hay información disponible o si corresponde.Cadena
hrefOpcional. Se detalla el error si hay información disponible o si corresponde.Cadena

Notificaciones entrantes

Hay varios tipos de notificaciones entrantes que se pueden entregar a tu webhook único.

Este documento abarca lo siguiente:

  • Notificación de mensajes entrantes
  • Notificación de mensajes multimedia entrantes
  • Respuestas entrantes a mensajes enviados
  • Mensajes entrantes del sistema
  • Descripciones de parámetros/campos para mensajes entrantes
  • Mención de usuarios en mensajes
  • Marcar mensajes como leídos

Para obtener más información general sobre los webhooks, consulta:

  • Formato del webhook de notificaciones
  • Configuración de las notificaciones
  • App de ejemplo para pruebas

Notificaciones de mensajes entrantes

Recibirás una notificación cuando tu empresa reciba un mensaje. En la sección sobre el objeto messages, se proporciona toda la información que recibes sobre un mensaje entrante.

En esta sección, se muestran ejemplos de mensajes de texto y mensajes de ubicación.

Ejemplo: Mensaje de texto recibido

El siguiente es un ejemplo de un mensaje de texto que puedes recibir de un cliente. Consulta la sección sobre el objeto text a continuación para obtener más información.

   {
    "contacts": [ {
        "profile": {
            "name": "Kerry Fisher"
        },
        "wa_id": "16315551234"
    } ],
        "messages":[{
            "from": "16315551234",
            "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
            "timestamp": "1518694235",
            "text": {
                "body": "Hello this is an answer"
            },
            "type": "text"
        }]
    }

Ejemplo: Mensaje de ubicación estática recibido

El siguiente es un ejemplo de un mensaje de texto que puedes recibir de un cliente para especificar su ubicación estática. Consulta la sección sobre el objeto location a continuación para obtener más información.

     {
            "contacts": [ {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16315551234"
            } ],
            "messages":[{
            "from":"16315551234",
            "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
            "location":{
                "address":"Main Street Beach, Santa Cruz, CA",
                "latitude":38.9806263495,
                "longitude":-131.9428612257,
                "name":"Main Street Beach",
                "url":"https://foursquare.com/v/4d7031d35b5df7744"},
            "timestamp":"1521497875",
            "type":"location"
            }]
        }

Ejemplo: Mensaje de un contacto recibido

El siguiente es un ejemplo de un mensaje de texto que puedes recibir de un cliente para especificar su información de contacto. Consulta la sección sobre el objeto contacts a continuación para obtener más información.

     {
      "contacts": [ {
          "profile": {
            "name": "Kerry Fisher"
          },
          "wa_id": "16315551234"
      } ],
      "messages": [
          {
              "contacts": [
                  {
                      "addresses": [
                          {
                              "city": "Menlo Park",
                              "country": "United States",
                              "country_code": "us",
                              "state": "CA",
                              "street": "1 Hacker Way",
                              "type": "WORK",
                              "zip": "94025"
                          }
                      ],
                      "birthday": "2012-08-18",
                      "contact_image": "/9j/4AAQSkZJRgABAQEAZABkAAD/....",
                      "emails": [
                          {
                              "email": "[email protected]",
                              "type": "WORK"
                          }
                      ],
                      "ims": [
                          {
                              "service": "AIM",
                              "user_id": "kfish"
                          }
                      ],
                      "name": {
                          "first_name": "Kerry",
                          "formatted_name": "Kerry Fisher",
                          "last_name": "Fisher"
                      },
                      "org": {
                          "company": "Facebook"
                      },
                      "phones": [
                          {
                              "phone": "+1 (940) 555-1234",
                              "type": "CELL"
                          },
                          {
                              "phone": "+1 (650) 555-1234",
                              "type": "WORK",
                              "wa_id": "16505551234"
                          }
                      ],
                      "urls": [
                          {
                              "url": "https://www.facebook.com",
                              "type": "WORK"
                          }
                      ]
                  }
              ],
              "from": "16505551234",
              "id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
              "timestamp": "1537248012",
              "type": "contacts"
          }
      ]
  }

Ejemplo: Mensaje desconocido recibido

A partir de la versión v2.21.3, es posible recibir una notificación de devolución de llamada unknown. El siguiente es un ejemplo de un mensaje que puedes recibir de un cliente que no se admite.

    {
        "messages": [{
                "errors": [
                    {
                        "code": 501,
                        "details": "Message type is not currently supported",
                        "title": "Unknown message type"
                    }
                ],
                "from": "16315551234",
                "id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
                "timestamp": "1531933468",
                "type": "unknown"
        }]
    }

Notificaciones de mensajes multimedia entrantes

Cuando se recibe un mensaje multimedia, el cliente de la API de WhatsApp Business descarga el contenido multimedia. Una vez que este se descarga, se envía una notificación a tu webhook. Este mensaje contiene información que identifica el objeto multimedia y te permite buscarlo y recuperarlo. Usa el extremo de contenido multimedia con el id del contenido para recuperarlo.

En esta sección, se muestran ejemplos de mensajes que se reciben con contenido multimedia.

Ejemplo: Mensaje recibido con imagen

El siguiente es un ejemplo de un mensaje entrante que contiene una imagen. Consulta la sección sobre el objeto media a continuación para obtener más información sobre los diferentes tipos de contenido multimedia

{
  "messages": [
    {
      "from": "16315551234",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "image": {
        "file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
        "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
        "mime_type": "image/jpeg",
        "sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
        "caption": "Check out my new phone!"
      },
      "timestamp": "1521497954",
      "type": "image"
    }
  ]
}

TIP

El campo caption es opcional para los mensajes multimedia. Se incluye solamente si el usuario configuró texto.

Ejemplo: Mensaje recibido con documento

El siguiente es un ejemplo de un mensaje entrante que contiene un documento. Consulta la sección sobre el objeto media a continuación para obtener más información sobre los diferentes tipos de contenido multimedia.

{
  "messages": [
    {
      "from": "16315551234",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "timestamp": "1522189546",
      "type": "document",
      "document": {
        "caption": "80skaraokesonglistartist",
        "file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33",
        "id": "fc233119-733f-49c-bcbd-b2f68f798e33",
        "mime_type": "application/pdf",
        "sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e"
      }
    }
  ]
}

Ejemplo: Mensaje recibido con mensaje de voz

El siguiente es un ejemplo de un mensaje entrante que contiene un mensaje de voz. Consulta la sección sobre el objeto media a continuación para obtener más información sobre los diferentes tipos de contenido multimedia.

{
  "messages": [
    {
      "from": "16315551234",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "timestamp": "1521827831",
      "type": "voice",
      "voice": {
        "file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2",
        "id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
        "mime_type": "audio/ogg; codecs=opus",
        "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
      }
    }
  ]
}

Ejemplo: Mensaje recibido con sticker

El siguiente es un ejemplo de un mensaje entrante que contiene un sticker. Consulta la sección sobre el objeto media a continuación para obtener más información sobre los diferentes tipos de contenido multimedia.

{
  "messages": [
    {
      "from": "16315551234",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "timestamp": "1521827831",
      "type": "sticker",
      "sticker": {
        "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
        "metadata": {
          "sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
          "sticker-pack-name": "Happy New Year",
          "sticker-pack-publisher": "Kerry Fisher",
          "emojis": [
            "🐥",
            "😃"
          ],
          "ios-app-store-link": "https://apps.apple.com/app/id3133333",
          "android-app-store-link": "https://play.google.com/store/apps/details?id=com.example",
          "is-first-party-sticker": 1
          // 0 | 1
        },
        "mime_type": "image/webp",
        "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
      }
    }
  ]
}

Respuestas entrantes a mensajes enviados

Los usuarios pueden responder a un mensaje específico en WhatsApp. Para permitir que la empresa comprenda el contexto de la respuesta a un mensaje, incluimos el objeto context. Este objeto context proporciona el id del mensaje que contestó el cliente y el identificador de WhatsApp del remitente del mensaje original.

En Responder mensajes, se proporciona más información.

Ejemplo: Mensaje respondido por el cliente

El siguiente es un ejemplo de un mensaje entrante que es la respuesta a un mensaje que enviaste. Consulta la sección sobre el objeto context a continuación para obtener más información.

{
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher"
      },
      "wa_id": "16315551234"
    }
  ],
  "messages": [
    {
      "context": {
        "from": "16315558011",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf"
      },
      "from": "16315551234",
      "id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
      "text": {
        "body": "Yes, count me in!"
      },
      "timestamp": "1521499915",
      "type": "text"
    }
  ]
}

TIP

El campo text es opcional para los mensajes multimedia. Si existe, el valor text es el texto del contenido multimedia enviado o el cuerpo de la respuesta, en caso de que la respuesta sea un mensaje de texto.

Mensajes entrantes del sistema

El sistema genera mensajes cuando ocurre un evento, por ejemplo, si un usuario agrega o elimina a otro usuario, si abandona el grupo, etc. Consulta la sección sobre el objeto system a continuación para obtener más información.

    {
  "messages": [
    {
      "from": "16506448470",
      "group_id": "16315558032-1530825318",
      "id": "ACELFjFVWAMqFTCCUxgDM3...",
      "system": {
        "body": "+1 (650) 387-5246 added +1 (650) 644-8470",
        "group_id": "16315558032-1530825318",
        "operator": "16503875246",
        "type": "group_user_joined",
        "users": [
          "16506448470"
        ]
      },
      "timestamp": "1530825587",
      "type": "system"
    }
  ]
}

Por ejemplo, los siguientes mensajes del sistema se recibieron cuando (1) un usuario se unió a un grupo y (2) el administrador de un grupo agregó un icono de grupo.

{
  "messages": [
    {
      "from": "12345678901",
      "group_id": "16315558011-1521728362",
      "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU",
      "system": {
        "body": "‎‎+1 (234) 567-8901 was added‎"
      },
      "timestamp": "1521739514",
      "type": "system"
    }
  ]
}

{
  "messages": [
    {
      "from": "16315558011",
      "group_id": "16315558011-1521728362",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "system": {
        "body": "‎‎+1 (631) 555-8011 changed this group's icon‎"
      },
      "timestamp": "1521745780",
      "type": "system"
    }
  ]
}

Tipos de mensajes del sistema

Tipo de mensaje del sistemaDescripción
group_createdSe creó el grupo
group_user_promotedUn usuario del grupo se designó como administrador
group_user_demotedUn usuario del grupo se eliminó como administrador
group_user_joinedUn usuario se unió al grupo
group_user_leftUn usuario abandonó el grupo
group_subject_changedSe cambió el asunto del grupo
group_description_changedSe cambió la descripción del grupo
group_icon_changedSe cambió el icono del grupo
group_icon_deletedSe eliminó el icono del grupo
group_invite_link_revokedSe desactivó el enlace de invitación al grupo
group_user_changed_numberCambió el número de teléfono de un usuario
group_error_fetching_photoError al recuperar la foto del grupo
group_error_adding_usersError al agregar usuarios al grupo
group_error_adding_userError al agregar a un usuario al grupo
group_error_full_adding_usersEl grupo alcanzó su capacidad máxima y no es posible agregar más usuarios
group_error_removing_userError al eliminar a un usuario del grupo
broadcast_list_createdSe creó una lista de difusióno
group_endedFinalizó el grupo
group_error_blocked_adding_userError al intentar agregar a un usuario que bloqueó a quien desea agregarlo

Descripciones de parámetros/campos para mensajes entrantes

Como se muestra en los ejemplos proporcionados en este documento, las notificaciones de los mensajes recibidos se incluyen en un objeto messages. En las tablas de esta sección, se describen los campos de las notificaciones entrantes.

NombreDescripciónTipo
contactsObjeto de contactosMatriz de información de perfil del contacto
messagesObjeto de mensajesMatriz de cualquier tipo de objetos de mensajes

Objeto contacts

El objeto contacts proporciona toda la información sobre el contacto.

TIP

Este objeto se aplica únicamente a texto, contactos y mensajes de ubicación. Actualmente, no se admite para mensajes multimedia y no es aplicable a los mensajes del sistema.

NombreDescripciónTipo
profileA partir de la versión v2.21.4, contiene la información del perfil del remitente.Objeto de perfil
wa_idIdentificador de WhatsApp del contactoCadena

Objeto profile

NombreDescripciónTipo
nameOpcional. A partir de v2.21.4, contiene el nombre del perfil del remitente.Cadena

Objeto messages

El objeto messages proporciona toda la información sobre el mensaje

NombreDescripciónTipo
contextOpcional. Este objeto solamente se incluirá si alguien responde uno de tus mensajes. Contiene información sobre el contenido del mensaje original, como el identificador del remitente y el del mensaje.Cadena
fromIdentificador de WhatsApp del remitente.Cadena
group_idOpcional. Identificador de WhatsApp del grupo.Cadena
idIdentificador del mensaje.Cadena
timestampMarca de tiempo de recepción del mensaje.Cadena
typeTipo de mensaje. Los valores son: audio, contacts, document, image, location, text, unknown, video, voice.Cadena
Objetos audio, contacts, document, image, location, system, text, video, voiceContenido del mensaje.Objetos de mensaje que proporcionan más información acerca del mensaje recibido. Consulta los campos del objeto media para obtener más información.
systemNotificaciones sobre cambios en el sistemaObjetos de sistema