Introducción a los Webhooks

Conceptualización

En este tema, abordamos los retornos de los webhooks utilizados por la API WhatsApp Web.

Importante

Tu endpoint debe aceptar solicitudes POST para recibir notificaciones de eventos.

Recuerda: al crear la instancia, necesitas indicar las URLs donde deseas recibir notificaciones.

¿Qué es y para qué sirve?

Los webhooks sirven para informarte sobre el envío y la recepción de mensajes, además del estado actual de tu instancia.

La instancia es la página de WhatsApp Web que gestionamos para tu cuenta.

Si estás integrando tu aplicación a la API WhatsApp Web, debes configurar los endpoints para recibir notificaciones sobre todas las interacciones ocurridas en el WhatsApp conectado.

Nuestros Webhooks

• Delivery: Notifica cuando un mensaje es enviado.
• Receive: Notifica cada vez que alguien interactúa con tu número.
• Status: Permite comprobar el estado de un mensaje: recibido, leído, respondido o eliminado.
• Disconnected: Indica interrupciones en la comunicación entre tu dispositivo y WhatsApp.
• Connected: Indica el inicio de la comunicación entre tu dispositivo y WhatsApp.

Configuración de Webhook

Puedes configurar el webhook de tu instancia accediendo a tu cuenta:

Al crear una nueva instancia, puedes agregar configuraciones para recibir mensajes.

Configuración vía Panel

Accede al panel de administración, haz clic en "Instancias", visualiza la instancia deseada y edita las configuraciones.

Webhook al Enviar

Cambiar URL del Webhook vía API

Esta API permite cambiar la URL del webhook para el envío de mensajes mediante una solicitud PUT.

URL Base

URL Base: https://apiwhatsappweb.com/api/config/sent

Autenticación

Para autenticar las solicitudes, debes incluir la clave API (apiKey) y la identificación de la instancia ID en el encabezado (Header).

{
    "apiKey": "Tu clave API aquí",
    "id": "La identificación de la instancia aquí"
}

Cómo Cambiar el Webhook

Cuerpo de la Solicitud

El cuerpo de la solicitud debe ser un objeto JSON con la siguiente estructura:

{
    "URL": "https://Tu_Sitio_Web_aqui.com/api/config/sent" 
    // Envía la URL donde deseas recibir las notificaciones
}

Importante

La API WhatsApp Web no acepta webhooks que no sean HTTPS.

Respuestas de los Webhooks

El Webhook de envío permite que recibas una notificación en cuanto un mensaje sea enviado con éxito.

Ejemplo de Respuesta

{
    "message": "¡Texto enviado con éxito!",
    "messageSent": "Mensaje enviado por ti",
    "number": "Número del contacto",
    "messageId": "Identificación del mensaje" // Permite acceder al estado del mensaje posteriormente
}

{
    messageId: 'Identificación del mensaje', //Permite acceder al estado del mensaje después,
    message: 'Mensaje enviado por otra persona',  //Los mensajes expiran automáticamente en 30 días
    number: "Número enviado",
    photo: 'Foto', //Si no es una foto, será null
    video: 'Video', //Si no es un video, será null,
    senderName: 'Nombre del usuario', //Si no tiene, será 'Unknown'
    instanceName: 'Nombre de la Instancia registrada en la plataforma',
    instanceId: "ID de la Instancia registrada en la plataforma",
    whatsappStatus: {
      message: "Recibido",
      description: 'Mensaje enviado por otra persona',
      title: 'Título' || null,
      url: 'Url enviado por otra persona', // Si no tiene, será Nulo
      groupInvite: 'Invitación a grupo' //Si no tiene, será nulo
    }
};
    

{
    instanceName: "El nombre de la instancia que se desconectó", 
    instanceId: "La identificación de la instancia que se desconectó",
    status: 'Desconectado',
    whatsappStatus: { message: "Desconectado" }
};
    

{
    instanceName: "El nombre de la instancia que se conectó",
    instanceId: "La identificación de la instancia que se conectó",
    status: 'Conectado',
    whatsappStatus: { message: "Conectado" }
};