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.

Si la URL de tu Webhook está detrás de un firewall o lista de permitidos, permite las IPs de origen de Positus. Consulta IPs para liberación de Webhook.

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.

Nuevos identificadores de usuario (BSUID). Con la llegada de los usernames de WhatsApp, los payloads de webhook incorporan campos adicionales de identificación — user_id (BSUID), parent_user_id (parent BSUID) y profile.username. Cuando el usuario adopta un username, los campos de teléfono (wa_id, from, recipient_id) pueden omitirse del payload. Maneje este escenario usando el user_id como identificador principal. Para entender estos identificadores, consulte la página BSUID e identificadores de usuario.

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",
        "username": "@kerryfisher"
      },
      "wa_id": "16315551234",
      "user_id": "BR.1234567890",
      "parent_user_id": "BR.ENT.1234567890"
    }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1518694235",
      "type": "text",
      "text": { "body": "Hello this is an answer" }
    }
  ]
}

Los campos profile.username, user_id y parent_user_id solo aparecen en los escenarios descritos en la página BSUID. El wa_id (y el from del mensaje) pueden omitirse cuando el usuario adoptó un username. Los campos siguientes se agregan al objeto contacts[] (no reemplazan a los existentes):

Campo	Descripción
`contacts[].user_id`	BSUID del usuario — identificador acotado al portafolio de negocios. Presente en los webhooks de mensajes.
`contacts[].parent_user_id`	Parent BSUID — solo presente si el portafolio está inscrito en una cuenta principal.
`contacts[].profile.username`	Username público (`@nombre`) — solo presente si el usuario adoptó un username.
`contacts[].wa_id`	Teléfono del usuario — puede omitirse cuando hay un username (ver regla de los 30 días).

El campo messages[].from (teléfono del remitente) sigue el mismo comportamiento que wa_id: puede no venir cuando el usuario adoptó un username. Use el user_id presente en el objeto contacts[] correspondiente para identificar al remitente de forma duradera.

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",
      "recipient_user_id": "BR.1234567890",
      "recipient_parent_user_id": "BR.ENT.1234567890"
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher",
        "username": "@kerryfisher"
      },
      "wa_id": "16315551234",
      "user_id": "BR.1234567890",
      "parent_user_id": "BR.ENT.1234567890"
    }
  ]
}

Los campos de identificación por BSUID en el objeto de estado:

Campo	Descripción
`statuses[].recipient_user_id`	BSUID del destinatario del mensaje. Puede omitirse si el mensaje se envió al teléfono.
`statuses[].recipient_parent_user_id`	Parent BSUID del destinatario — solo presente si el portafolio está inscrito en una cuenta principal.
`statuses[].recipient_id`	Teléfono del destinatario — ahora opcional; puede omitirse cuando el usuario adoptó un username.

El arreglo contacts que acompaña al estado (cuando está presente) trae los mismos campos BSUID descritos en mensajes entrantes: user_id, parent_user_id y profile.username. 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"
        }
    ]
}

Mensaje de sistema: el usuario cambió de identificador (`user_changed_user_id`)

Cuando el identificador de un usuario cambia (por ejemplo, al cambiar de número), WhatsApp envía un mensaje de sistema de tipo system con system.type igual a user_changed_user_id. Llega dentro del arreglo messages, en el mismo formato que los demás mensajes entrantes. Úselo para actualizar el vínculo del contacto con el nuevo user_id.

{
  "contacts": [
    {
      "profile": { "name": "Kerry Fisher" },
      "user_id": "BR.9876543210"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521827831",
      "type": "system",
      "system": {
        "type": "user_changed_user_id",
        "customer": "BR.1234567890",
        "user_id": "BR.9876543210",
        "parent_user_id": "BR.ENT.9876543210",
        "body": "El usuario cambió de identificador"
      }
    }
  ]
}

Campo	Descripción
`system.type`	`user_changed_user_id` — identifica el disparador.
`system.customer`	BSUID anterior del usuario — úselo para localizar el contacto existente.
`system.user_id`	Nuevo BSUID del usuario.
`system.parent_user_id`	Nuevo parent BSUID — presente si el portafolio está inscrito en una cuenta principal.
`system.body`	Texto descriptivo del mensaje de sistema.

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

Webhooks de eventos del workspace (BSUID)

Además de las notificaciones de mensajes y estado (entregadas en el formato crudo de la Cloud API), Positus envía dos eventos de workspace relacionados con el BSUID. Estos eventos usan un sobre diferente: un objeto de nivel superior con el campo event (nombre del evento), el objeto workspace (identificación del workspace) y un objeto con los datos del evento — nombrado contact o number, según el caso.

Actualización de BSUID (`user_id_update`)

Se dispara cuando el BSUID (o parent BSUID) de un usuario se actualiza. Trae los valores anterior y actual de cada identificador. Los datos vienen en el objeto contact.

{
  "event": "user_id_update",
  "workspace": {
    "id": "9f8b7c6d-...",
    "provider": { "id": 1, "name": "Positus V2" },
    "type_workspace": "...",
    "name": "Mi Empresa",
    "business_id": "1234567890",
    "waba_id": "9876543210"
  },
  "contact": {
    "wa_id": "16315551234",
    "previous_user_id": "BR.1234567890",
    "current_user_id": "BR.9876543210",
    "previous_parent_user_id": "BR.ENT.1234567890",
    "current_parent_user_id": "BR.ENT.9876543210",
    "timestamp": "1521827831",
    "detail": "...",
    "waba_id": "9876543210",
    "phone_number_id": "16315551234"
  }
}

Campo	Descripción
`contact.wa_id`	Teléfono del usuario asociado al evento (puede omitirse).
`contact.previous_user_id`	BSUID anterior del usuario.
`contact.current_user_id`	BSUID actual del usuario.
`contact.previous_parent_user_id`	Parent BSUID anterior (si aplica).
`contact.current_parent_user_id`	Parent BSUID actual (si aplica).
`contact.timestamp`	Momento de la actualización.
`contact.detail`	Detalle adicional del evento, cuando lo proporciona Meta.
`contact.waba_id`	ID de la cuenta de WhatsApp Business (WABA).
`contact.phone_number_id`	ID del número de teléfono de la línea.

Actualización de username de la línea (`business_username_update`)

Se dispara cuando cambia el estado del username de su línea oficial (el @nombre público del número comercial). Los datos vienen en el objeto number.

{
  "event": "business_username_update",
  "workspace": {
    "id": "9f8b7c6d-...",
    "provider": { "id": 1, "name": "Positus V2" },
    "type_workspace": "...",
    "name": "Mi Empresa",
    "business_id": "1234567890",
    "waba_id": "9876543210"
  },
  "number": {
    "display_phone_number": "16315551234",
    "username": "@miempresa",
    "status": "approved",
    "timestamp": "1521827831",
    "waba_id": "9876543210"
  }
}

Campo	Descripción
`number.display_phone_number`	Teléfono de la línea oficial cuyo username cambió.
`number.username`	Username (`@nombre`) de la línea.
`number.status`	Estado del username: `approved`, `deleted` o `reserved`.
`number.timestamp`	Momento de la actualización.
`number.waba_id`	ID de la cuenta de WhatsApp Business (WABA).

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

​Mensaje de sistema: el usuario cambió de identificador (user_changed_user_id)

​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

​Webhooks de eventos del workspace (BSUID)

​Actualización de BSUID (user_id_update)

​Actualización de username de la línea (business_username_update)

​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

Mensaje de sistema: el usuario cambió de identificador (`user_changed_user_id`)

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

Webhooks de eventos del workspace (BSUID)

Actualización de BSUID (`user_id_update`)

Actualización de username de la línea (`business_username_update`)

Documentación oficial de WhatsApp Cloud API