Webhook

Cuando el cliente le envía un mensaje, el cliente API de WhatsApp Business enviará una notificación de solicitud HTTP POST a la URL de Webhook con los detalles que se describen en este manual.

Webhooks son devoluciones de llamada HTTP definidas por el usuario que se desencadenan por eventos específicos. Cada vez que se produce un evento desencadenante, el cliente de la API empresarial de WhatsApp verá el evento, recopilará los datos e inmediatamente enviará una notificación (solicitud HTTP) a la URL de WhatsApp especificada en la configuración de la aplicación, actualizando el estado de los mensajes enviados o indicando cuándo recibir un mensaje

Es importante que su Webhook devuelva una respuesta HTTPS 200 OK a las notificaciones. De lo contrario, el cliente de la API empresarial de WhatsApp considerará que esta notificación es un error y volverá a intentarlo después de un retraso.

Configurar ajustes de notificaciones

webhooks: proporcione la URL para su Webhook. OBlIGATÓRIO cuando estás usando Webhooks. Si la URL de Webhook no está definida, se eliminan las devoluciones de llamada.

Nombre	contenido del objeto
mensajes	Notificaciones de mensajes entrantes
estados	Actualizaciones de estado del mensaje
errores	Graves errores fuera de banda

Siempre que sea posible, los nombres se mantendrán constantes en todas las funciones. (Por ejemplo, todas las marcas de tiempo se llamantimestamp.

Formato de Webhook de notificaciones

Todos los campos posibles del Webhook de notificación se muestran a continuación.

Ejemplo

POST / { "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", # Se houver algum erro, o campo de erros (matriz) estará presente. # O campo de erros pode ser retornado como parte de qualquer evento de retorno de chamada. "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 notificación

Cuando se producen errores fuera de banda en el funcionamiento normal de la aplicación, la matriz de errores proporcionará una descripción del error. Este tipo de error puede ser causado por errores temporales de conectividad de red, credenciales no válidas, controladores de administración con estado no disponible, etc. Si recibe un error, consulte Mensajes de error y estado para obtener más información.

Ejemplo

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

El objeto de errores El objeto de errores contiene los siguientes parámetros:

Nombre del campo	Descripción	Tipo
code	Código de error	Numérico
title	Título do error	Cadena de caracteres
details	Opcional. Detalles del error proporcionados, si están disponibles / aplicables	Cadena de caracteres
href	Opcional. Detalles de la ubicación del error.	Cadena de caracteres

Notificiones de mensajes de entrada

Recibirá una notificación cuando su empresa reciba un mensaje. La sección del objeto de mensajes a continuación presenta toda la información que se puede recibir sobre un mensaje entrante.

Ejemplo: Mensaje recibido Texto

{
  "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

{
  "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 con contactos recibidos

{
    "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/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCABgAGADASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD1NLloxyc0j3bNUHDGgoCMVNkBbhutvVqc9yGHNZ3kOW4Wn/ZnQZzSsgLLXAA61Xn1O2t4zLcyJHGvV3OAKMADmvOviLq9m11a2bO/l2xLzoqnliF2j9f1NTLRXHGHM7Hb2vivSL+8e0s7yKaVeyHg/Q9D+FXWuHPOzivFodT0WZkeF44bheVdE2EH+Rr2+zuVuNPt7gqh86JX+TkcjPFTCdy6lNQ2dyr5+G5WpRe4HTFWWSOQfwioZbCIn5XNaXRmQPegjmqrKLh+...",
                    "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": "[phone]",
                            "type": "CELL"
                        },
                        {
                            "phone": "[phone]",
                            "type": "WORK",
                            "wa_id": "16505551234"
                        }
                    ],
                    "urls": [
                        {
                            "url": "https://www.facebook.com",
                            "type": "WORK"
                        }
                    ]
                }
            ],
            "from": "16505551234",
            "id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
            "timestamp": "1537248012",
            "type": "contacts"
        }
    ]
}

Notificaciones de mensajes de medios entrantes

Cuando se recibe el mensaje de medios, el cliente de la API empresarial de WhatsApp descarga los medios. Se envía una notificación a su Webhook cuando se descargan los medios. Este mensaje contiene información que identifica el objeto multimedia y le permite encontrar y recuperar el objeto. Use el punto final de medios con la identificación de medios para recuperarlo.

Ejemplo: Mensaje con imagen recibida

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

Ejemplo: Mensaje con documento recibido

{
   "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 con mensaje de voz recibida

{
    "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 con etiqueta recibida

{
  "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" : 0 | 1 # integer 
            },
            "mime_type": "image/webp",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
        }  
    }]
}

Respuestas entrantes a mensajes enviados

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

Ejemplo: el Cliente respondió a su mensaje

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

Sistema de mensajes entrantes

Los mensajes del sistema se generan cuando ocurre un evento, por ejemplo, un usuario agrega / elimina otro usuario o deja un grupo, etc. Consulte la sección de objetos del sistema a continuación para obtener más información.

{
    "messages": [
        {
            "from": "16506448470",
            "group_id": "16315558032-1530825318",
            "id": "ACELFjFVWAMqFTCCUxgDM3N5cy0xNjMxNTU1ODAzMi0xNTMwODI1MzE4QGcudXMtMTUzMDgyNTU4NzI5OS1hZGQtMBGGFlBkSEcP",
            "system": {
                "body": "[phone] added [phone]",
                "group_id": "16315558032-1530825318",
                "operator": "16503875246",
                "type": "group_user_joined",
                "users": [
                    "16506448470"
                ]
            },
            "timestamp": "1530825587",
            "type": "system"
        }
    ]
}

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

Message received: {"messages":[{"from":"12345678901","group_id":"16315558011-1521728362","id":"gBEGkYiEB1VXAglK1ZEqA1YKPrU","system":{"body":"‎‎[phone] was added‎"},"timestamp":"1521739514","type":"system"}]}

Message received: {"messages":[{"from":"16315558011","group_id":"16315558011-1521728362","id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf","system":{"body":"‎‎[phone] changed this group's icon‎"},"timestamp":"1521745780","type":"system"}]}

Documentación oficial WhatsApp Business API

Positus sigue los estándares API exactamente igual que el estándar oficial de Facebook / WhatsApp. La documentación completa y actualizada se puede encontrar en el siguiente enlace:

https://developers.facebook.com/docs/whatsapp/api/webhooks