Webhook

Los Webhooks son retornos de llamada HTTP definidos por el usuario que se activan mediante eventos específicos. Siempre que ocurra un evento de activación, el cliente de la API de WhatsApp Business 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 recibe un mensaje.

Es importante que su Webhook devuelva una respuesta HTTPS 200 OK a las notificaciones. De lo contrario, el cliente de la API de WhatsApp Business considerará esa notificación como un fallo y volverá a intentarlo tras un retraso.

Configuración del Webhook

Para recibir notificaciones, el cliente debe registrar la URL de su Webhook en el número. Definir/actualizar la URL del Webhook:

PUT https://api.positus.global/v2/whatsapp/numbers/{chave}/webhook
Authorization: Bearer <seu-token>
Content-Type: application/json

{
  "webhook": "https://seu-dominio.com/webhook"
}

El campo webhook es opcional (puede ser null para eliminarlo) y tiene un máximo de 255 caracteres. Si la URL del Webhook no está definida, las notificaciones no se entregarán.

Además del Webhook principal, es posible configurar un webhook secundario (secondary_webhook). Cuando está definido, recibe las mismas notificaciones que el Webhook principal.

Probar el Webhook (handshake): para validar que la URL responde correctamente, dispare un mensaje de prueba. Positus enviará una notificación de prueba ("Beep Beep!") a la URL configurada:

POST https://api.positus.global/v2/whatsapp/numbers/{chave}/positus-webhook
Authorization: Bearer <seu-token>

Es importante que su Webhook devuelva una respuesta HTTP 200 OK a las notificaciones. De lo contrario, la notificación se considerará un fallo y habrá intentos de reenvío.

Definir la configuración de notificaciones

Los números de Positus utilizan la WhatsApp Cloud API. El cliente recibe, en la URL de Webhook registrada, un subconjunto normalizado del payload de Meta (sin el sobre entry/changes). Los objetos entregados son los objetos crudos de la Cloud API.

Nombre	contenido del objeto
messages	Notificaciones de mensajes entrantes
statuses	Actualizaciones de estado de los mensajes
errors	Errores graves fuera de banda

Siempre que sea posible, los nombres se mantendrán constantes en las funciones. (Por ejemplo, todas las marcas de fecha y hora se denominan timestamp.

Formato del Webhook de notificaciones

Una notificación de mensaje entrante tiene el nivel superior { "contacts": [...], "messages": [...] }. Una notificación de estado tiene el nivel superior { "statuses": [...], "contacts": [...] } (contacts solo está presente cuando el estado no es failed). Ejemplo (mensaje de texto entrante)

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

Actualizaciones de estado de los mensajes

Además de los mensajes entrantes, el cliente recibe notificaciones de estado de los mensajes que envió. Estas notificaciones tienen el nivel superior { "statuses": [...], "contacts": [...] }. Ejemplo (estado delivered)

{
  "statuses": [
    {
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "status": "delivered",
      "timestamp": "1521497954",
      "recipient_id": "16315551234"
    }
  ],
  "contacts": [
    {
      "profile": { "name": "Kerry Fisher" },
      "wa_id": "16315551234"
    }
  ]
}

El campo status puede tomar los siguientes valores:

Valor	Descripción
`sent`	El mensaje fue enviado al servidor de WhatsApp.
`delivered`	El mensaje fue entregado al dispositivo del destinatario.
`read`	El mensaje fue leído por el destinatario.
`failed`	Hubo un fallo en el envío del mensaje.

Cuando el status es failed, el objeto de estado incluye un arreglo errors con el detalle del fallo y contacts no se envía. Ejemplo (estado failed)

{
  "statuses": [
    {
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "status": "failed",
      "timestamp": "1521497954",
      "recipient_id": "16315551234",
      "errors": [
        {
          "code": 131026,
          "title": "Message undeliverable"
        }
      ]
    }
  ]
}

Errores de notificaciones

Cuando haya errores fuera de banda que ocurran durante la operación normal de la aplicación, el arreglo errors proporcionará una descripción del error. Este tipo de error puede deberse a errores temporales de conectividad de red, credenciales no válidas, controladores de gestión con estado no disponible, etc. Si recibe un error, consulte Mensajes de error y estado para obtener más información. Ejemplo

{
  "errors": [
    {
      "code": 131026,
      "title": "Message undeliverable",
      "details": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
      "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes"
    }
  ]
}

El objeto errors
El objeto errors contiene los siguientes parámetros:

Nombre del campo	Descripción	Tipo
code	Código de error	Numérico
title	Título del 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

Notificaciones de mensajes entrantes

Recibe una notificación cuando su empresa recibe un mensaje. La sección del objeto messages presenta toda la información que se puede recibir sobre un mensaje entrante.

Ejemplo: Mensaje de texto recibido

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
  "messages":[{
    "from": "16315551234",
    "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
    "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":"wamid.HBgLMTYzMTU1NTEyMzQ...",
   "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 recibido

{
    "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": "kfish@fb.com",
                            "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": "wamid.HBgLMTY1MDU1NTEyMzQ...",
            "timestamp": "1537248012",
            "type": "contacts"
        }
    ]
}

Notificaciones de mensajes de medios entrantes

Cuando se recibe un mensaje con medios, la notificación enviada a su Webhook contiene un objeto de medios con los campos que identifican el archivo. En la Cloud API, el objeto de medios solo trae id, mime_type y sha256 (más un caption opcional para imagen, documento y video). No hay campos file ni link. Para descargar el medio, use el id en el endpoint de descarga: GET https://api.positus.global/v2/whatsapp/numbers/{chave}/media/{id}.

Ejemplo: Mensaje con imagen recibido

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521497954",
      "type": "image",
      "image": {
        "id": "1234567890",
        "mime_type": "image/jpeg",
        "sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
        "caption": "Check out my new phone!"
      }
    }
  ]
}

Ejemplo: Mensaje con documento recibido

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1522189546",
      "type": "document",
      "document": {
        "id": "1234567890",
        "mime_type": "application/pdf",
        "sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e",
        "caption": "80skaraokesonglistartist"
      }
    }
  ]
}

Ejemplo: Mensaje con audio recibido

En la Cloud API, los mensajes de audio (incluidos los mensajes de voz) se entregan con el tipo audio, no voice.

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521827831",
      "type": "audio",
      "audio": {
        "id": "1234567890",
        "mime_type": "audio/ogg; codecs=opus",
        "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
      }
    }
  ]
}

Ejemplo: Mensaje con video recibido

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521827831",
      "type": "video",
      "video": {
        "id": "1234567890",
        "mime_type": "video/mp4",
        "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710",
        "caption": "Look at this!"
      }
    }
  ]
}

Ejemplo: Mensaje con sticker recibido

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521827831",
      "type": "sticker",
      "sticker": {
        "id": "1234567890",
        "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 entienda el contexto de la respuesta a un mensaje, incluimos el objeto context. Este objeto context proporciona el id del mensaje al que el cliente respondió y el ID 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":"wamid.HBgLMTYzMTU1NTgwMTE..."
         },
      "from":"16315551234",
      "id":"wamid.HBgLMTYzMTU1NTEyMzQ...",
      "text":{"body":"Yes, count me in!"},
      "timestamp":"1521499915",
      "type":"text"
  }]
}

Documentación oficial de WhatsApp Cloud API

Positus utiliza la WhatsApp Cloud API y entrega los objetos en el mismo formato que el estándar oficial de Meta. La documentación completa y actualizada se puede encontrar en el enlace a continuación:https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components

​Webhook

​Configuración del Webhook

​Definir la configuración de notificaciones

​Formato del Webhook de notificaciones

​Actualizaciones de estado de los mensajes

​Errores de notificaciones

​Notificaciones de mensajes entrantes

​Ejemplo: Mensaje de texto recibido

​Ejemplo: Mensaje de ubicación estática recibido

​Ejemplo: Mensaje con contactos recibido

​Notificaciones de mensajes de medios entrantes

​Ejemplo: Mensaje con imagen recibido

​Ejemplo: Mensaje con documento recibido

​Ejemplo: Mensaje con audio recibido

​Ejemplo: Mensaje con video recibido

​Ejemplo: Mensaje con sticker recibido

​Respuestas entrantes a mensajes enviados

​Ejemplo: El cliente respondió a su mensaje

​Documentación oficial de WhatsApp Cloud API

Webhook

Configuración del Webhook

Definir la configuración de notificaciones

Formato del Webhook de notificaciones

Actualizaciones de estado de los mensajes

Errores de notificaciones

Notificaciones de mensajes entrantes

Ejemplo: Mensaje de texto recibido

Ejemplo: Mensaje de ubicación estática recibido

Ejemplo: Mensaje con contactos recibido

Notificaciones de mensajes de medios entrantes

Ejemplo: Mensaje con imagen recibido

Ejemplo: Mensaje con documento recibido

Ejemplo: Mensaje con audio recibido

Ejemplo: Mensaje con video recibido

Ejemplo: Mensaje con sticker recibido

Respuestas entrantes a mensajes enviados

Ejemplo: El cliente respondió a su mensaje

Documentación oficial de WhatsApp Cloud API