Webhooks

En este artículo te explicamos cómo conectar webhooks, en qué formato los enviamos y qué esperamos como respuesta.

Cómo enviamos webhooks y qué esperamos a cambio

Enviamos los webhooks usando el método POST a la URI especificada. Esta puede incluir una query string.

Si tenemos tu crmKey, añadimos el encabezado: Authorization: Bearer ${crmKey}

Si no lo tenemos, no añadimos ningún encabezado de autorización.

Los webhooks contienen JSON en el cuerpo del mensaje y se incluye el encabezado: Content-Type: application/json; charset=utf-8.

El cuerpo del webhook es un objeto codificado en JSON con propiedades que corresponden a los tipos de webhook.

Un solo webhook puede contener datos de tipo messages y statuses al mismo tiempo. Los webhooks de tipo createContact y createDeal siempre contienen solo un tipo.

Esperamos recibir el código 200 OK. En algunos casos, también esperamos información específica en el cuerpo de la respuesta. El tiempo máximo de espera (timeout) es de 30 segundos.

Cómo activar los webhooks

Para suscribirte a los webhooks, debes hacer una petición:

 PATCH https://api.wazzup24.com/v3/webhooks

El cuerpo debe contener un objeto JSON con los siguientes parámetros:

Al conectarse a la URL especificada, se enviará una solicitud de prueba POST {test: true}, en respuesta a la cual el servidor debe devolver 200 si los webhooks se conectaron correctamente; de ​​lo contrario, un mensaje: "Solicitud de webhooks no válida. El estado de la respuesta debe ser 200".

Ejemplo de petición

 curl --location --request PATCH 'https://api.wazzup24.com/v3/webhooks' \
--header 'Authorization: Bearer w11cf3444405648267f900520d454368d27' \
--header 'Content-Type: application/json' \
--data-raw '{
"webhooksUri": "https://example.com/webhooks",
"subscriptions": {
"messagesAndStatuses": true,
"contactsAndDealsCreation": true
}
}'

Ejemplo de respuesta

 {
ok
}

Posibles errores

Además de los errores comunes en todas las rutas, pueden darse los siguientes:

Verificación de la dirección de recepción de webhooks

Para consultar la URL actualmente configurada para recibir webhooks, realiza la siguiente solicitud:

 GET https://api.wazzup24.com/v3/webhooks

Ejemplo de respuesta

 HTTP/1.1 200 OK
``json
{
"webhooksUri": "https://example.com/webhooks",
{ "subscriptions": {
{ "messagesAndStatuses": { "true",
{ "contactsAndDealsCreation": "true"
}
}
``

Webhook sobre nuevos mensajes

Este webhook envía un objeto JSON con la clave messages, cuyo valor es un array de objetos. Cada objeto representa un mensaje individual y contiene los siguientes parámetros:

Una vista del objeto con información sobre la publicación de Instagram.

 {
id: '2430659146657243411_41370968890',
src: 'https://www.instagram.com/p/CG7b52ejyET',
sha1: 'dc8c036b4a0122bb238fc38dcb0391c125e916f2',
likes: 0,
author: 'wztestdlv',
comments: 22,
timestamp: 1603977171000,
updatedAt: 1608905897958,
authorName: '',
authorId: '798633247',
description: 'Beauty',
previewSha1: '3a55c2920912de4b6a66d24568470dd4ad367c34',
imageSrc: 'https://store.dev-wazzup24.com/dc8c036b4a0122bb238fc38dcb0391c125e916f2',
previewSrc: 'https://store.dev-wazzup24.com/3a55c2920912de4b6a66d24568470dd4ad367c34'
}

Webhook sobre actualización del estado de mensajes salientes

Este webhook envía un objeto JSON con la clave messages, cuyo valor es un array de objetos con los siguientes parámetros:

{
"messages": [
{
"messageId": "be3dc577-60c4-4fc8-83a5-8c358e0bfe15", // guid of the message whose status update we are notifying
"timestamp": "2025-02-05T06:01:07.499Z", // is the time of receiving status update information
"status": "delivered"
}
]
}

Webhooks sobre creación de nuevo contacto o trato (deal)

Wazzup envía este webhook cuando es necesario crear un contacto o trato (deal) en tu CRM. Esto sucede en tres casos:

Caso 1: En la configuración de integración, la opción "Cada nuevo cliente se asigna al primer respondedor" está activada

Un nuevo cliente escribe. Un empleado le responde. Wazzup envía un webhook sobre el nuevo contacto y la creación de un acuerdo si se cargan embudos con etapas desde el CRM.

Este webhook solo se envía si Wazzup ha recibido el ID del empleado que respondió al mensaje del nuevo cliente.

Caso 2: En la configuración de integración, está activada la opción "Los vendedores se asignan a los nuevos clientes por turnos"

Un nuevo cliente escribe. Wazzup envía un webhook sobre la creación de un nuevo contacto y trato si se cargan embudos con etapas desde CRM.

Para que los webhooks se activen en estos dos casos, debe agregar empleados a la cuenta personal y habilitar uno de ellos en la configuración de integración para activar el control deslizante "Obtener nuevos clientes".

Caso 3: El usuario hace clic en el botón "+" en la lista de "Deals" en el chat de Wazzup

Primero comprobamos si el contacto ya existe en nuestra base de datos.

Si ya existe, enviamos un webhook para iniciar la creación del acuerdo:

 { 
createDeal: { 
responsibleUserId: '1', // the id of the user who was selected in turn or was the first to respond 
contacts: ['1'] // link of the deal with a newly created contact 
source: 'auto'|'byUser', // auto - on incoming or outgoing message, byUser - by the button in the "Deals" dropdown 
}, 
}

Si el contacto no existe, primero enviamos un webhook para iniciar la creación del contacto:

 {
createContact: {
responsibleUserId: '1', // id of the user who was selected in turn or was the first to respond
name: 'contacts.name', // contact name from the contacts table
contactData: [{ chatType, chatId }],
source: 'auto'|'byUser', // auto - on incoming or outgoing message, byUser - by button
},
}

Crear el contacto y responder con 200 OK y un objeto JSON que siga el esquema esperado del endpoint de creación de contactos.

Entonces, Wazzup enviará el webhook createDeal.

El CRM debe crear el trato y responder también con 200 OK y un objeto JSON siguiendo el esquema del endpoint de creación de deals.

Webhook sobre cambio de estado del canal

Este webhook se envía cuando el estado de un canal cambia.

 Ejemplo

{
    "channelsUpdates": [
        {
            "channelId": "d9e5721c-ce2b-444f-9627-60a8129d7e1f",
            "state": "qr",
            "timestamp": 1603977171000,
            "qr": "data:image/png;base64,iVBORw0KGgoAAAANS"
        }
    ]
}

Valores posibles de state (estado del canal)

Webhook sobre nuevo estado de moderación de una plantilla WABA

Posibles valores del status