Recibir mensajes de texto

El webhook de mensajes de texto entrantes permite recibir notificaciones en tiempo real cuando un usuario envía un mensaje a su número de WhatsApp conectado al servicio.

Cuando se recibe un mensaje, el sistema enviará una solicitud HTTP POST a la URL de webhook configurada.

Configuración del Webhook

Debe configurar una URL pública con HTTPS que pueda recibir solicitudes POST.

Cada vez que llegue un mensaje a su número de WhatsApp, el sistema enviará los datos del evento en formato JSON a esta URL.

Ejemplo de datos enviados al webhook:

{
  "event": "messages.upsert",
  "instance": "6bf3639d-ce54-22b5-b869-af9r54012df4",
  "data": {
    "key": {
      "remoteJid": "[email protected]",
      "remoteJidAlt": "[email protected]",
      "fromMe": false,
      "id": "AC99D5066CFA0B6F4C1FA2EF0A134D07",
      "participant": "",
      "addressingMode": "lid"
    },
    "pushName": "User Name",
    "status": "SERVER_ACK",
    "message": {
      "conversation": "Hello!"
    },
    "messageType": "conversation",
    "messageTimestamp": 1773087982,
    "instanceId": "6bf3639d-ce54-22b5-b869-af9r54012df4",
    "source": "android"
  },
  "destination": "https://my-webhook.site/url",
  "date_time": "2026-03-09T17:26:22.126Z",
  "sender": "[email protected]",
  "server_url": "https://chat.migo.pe",
  "apikey": "00000000-1111-2222-333-ABCDEFGHIJK"
}

Actualmente el servicio no ofrece soporte para la lectura, procesamiento o conversión de archivos multimedia adjuntos en los mensajes.

Dentro del payload recibido en el webhook, los siguientes campos contienen la información principal del mensaje enviado por el usuario.

messageType

Indica el tipo de mensaje recibido.

"messageType": "conversation"

En este caso, el valor conversation indica que se trata de un mensaje de texto simple.

message

Objeto que contiene el contenido del mensaje.

"message": {
  "conversation": "Hello!"
}

El campo conversation contiene el texto enviado por el usuario.

sender

Identificador del remitente del mensaje.

"sender": "[email protected]"

Este valor corresponde al ID de WhatsApp del usuario que envía el mensaje.

Para obtener solo el número telefónico, puede remover el sufijo: @s.whatsapp.net

Respuesta Esperada del Webhook

El servidor debe responder con código HTTP 200 para confirmar la recepción del evento.