Catálogo de eventos

El webhook y el WebSocket comparten el mismo envoltorio y el mismo catálogo de eventos. La única diferencia es el canal de entrega, data es idéntico. Esta página documenta los 6 tipos: message.exchange, message.status, call.update, group.flow, instance.state y label.update.

Envoltorio

{
  "event": "<event-name>",
  "data": { /* event-specific payload */ },
  "instanceData": {
    "baseUrl": "https://api.example.com",
    "instance": "<name>",
    "token":    "<instance-token>"
  }
}

El filtrado se hace por el nombre del event en el campo events de la configuración. Vacío = todos los tipos.

Filtrado y enrutamiento

{ "events": ["message.exchange", "call.update", "instance.state"] }

Cuando byEvents=true (solo webhook), el nombre del evento se agrega a la URL:

Configuración: url: "https://app/wh", byEvents: true
Entrega: POST https://app/wh/message.exchange

Útil para enrutamiento basado en endpoints sin inspeccionar el payload.

`message.exchange`

Mensajes enviados y recibidos (texto, media, sticker, documento, audio, encuesta, contacto, ubicación, etc.), ediciones y revocaciones.

Payload

{
  "id": "wamid.msg.123",
  "message": {
    "id": "wamid.msg.123",
    "direction": "incoming | outgoing",
    "timestamp": "2026-04-28T10:30:00Z",
    "chat": {
      "jid": "5511999999999",
      "lid": "100@s.whatsapp.net",
      "name": "João Silva",
      "type": "private | group | newsletter",
      "isCommunity": true
    },
    "sender": {
      "jid": "5511999999999",
      "lid": "100@s.whatsapp.net",
      "name": "João Silva"
    },
    "content": { "text": "Hello" },
    "media": {
      "type": "image | video | audio | document | sticker | ptt | ptv",
      "url": "https://media-...whatsapp.net/...",
      "s3Url": "https://bucket.s3.amazonaws.com/...",
      "base64": "iVBORw0KGgo...",
      "mimetype": "image/jpeg",
      "size": 45678,
      "caption": "Event photo",
      "fileName": "doc.pdf"
    },
    "edit": {
      "original_id": "wamid.original",
      "originalContent": "Old text",
      "text": "New text"
    },
    "forward": { "count": 2 },
    "reply": {
      "message_id": "wamid.replied",
      "sender": { "jid": "...", "name": "..." },
      "text": "...",
      "media": { /* simplified media object */ }
    },
    "poll": {
      "title": "Which flavor?",
      "options": [{ "name": "Chocolate", "count": 0 }]
    },
    "location": {
      "latitude": -23.5505,
      "longitude": -46.6333,
      "address": "Av. Paulista, 1374"
    },
    "contact": {
      "display_name": "Maria",
      "phone_number": "5511987654321",
      "vcard": "BEGIN:VCARD..."
    },
    "list_response": {
      "title": "...",
      "body": "...",
      "list_type": "single_select",
      "single_select_reply": { "option_name": "p1" }
    },
    "button_response": {
      "title": "Buy",
      "body": "...",
      "selected_button_id": "buy_camiseta"
    },
    "interactive": { /* form / native flow / other surfaces */ },
    "adOrigin": {
      "entryPointSource": "ctwa_ad | click_to_chat_link | global_search_new_chat | qr_code",
      "adType": "CTWA | CAWC",
      "sourceId": "120210350926390440",
      "ctwaClid": "AfjMN6zW...",
      "sourceApp": "instagram | facebook",
      "sourceType": "ad",
      "sourceUrl": "https://www.instagram.com/p/DGnlj_hAqGX/",
      "title": "Príncipe do Mutá Hotel Design",
      "body": "Aqui, seus dias são mais felizes!",
      "mediaType": "IMAGE | VIDEO",
      "thumbnailUrl": "https://scontent-...fbcdn.net/...",
      "greetingMessageBody": "Olá! Como podemos ajudar?",
      "conversionSource": "FB_Ads",
      "entryPointExternalSource": "FB_Ads",
      "ctwaPayload": "QWZqa2xTQkt...(base64)",
      "originalImageUrl": "https://.../ad-creative.jpg",
      "clickToWhatsappCall": true
    }
  }
}

Campos condicionales

Solo se completan los campos relevantes para el tipo de mensaje. Las ediciones tienen edit poblado; las revocaciones llegan con type: "message_revoke" en data.message.type.

chat.isCommunity aparece solo cuando es true, indicando que el chat es el canal de anuncios (parent / announcement channel) de una comunidad de WhatsApp. Los subgrupos vinculados a una comunidad mantienen type: "group" y no incluyen el campo isCommunity. En grupos regulares y DMs el campo también se omite.

media.base64 solo aparece cuando mediaBase64=true en la configuración (webhook o WebSocket). De lo contrario, usa media.url (whatsapp.net, expira) o media.s3Url (si S3 está configurado en la instancia).

`adOrigin` — atribución de origen (Click-to-WhatsApp)

Presente solo en el primer mensaje recibido de una conversación iniciada por un anuncio de Meta o por un punto de entrada (enlace wa.me, búsqueda, QR). Permite enrutar el lead por campaña sin consultar la base de datos. Dos escenarios:

Anuncio nativo (Click-to-WhatsApp / Call Ads) — entryPointSource es ctwa_ad e incluye el bloque completo: sourceId (ID del anuncio — agrupa leads por campaña), ctwaClid (clave de atribución de Meta, úsala en la Conversions API), sourceApp, sourceUrl, title, body, mediaType, greetingMessageBody, además de conversionSource, entryPointExternalSource, ctwaPayload (token base64 para la Conversions API), originalImageUrl y clickToWhatsappCall.
Punto de entrada sin anuncio — enlace wa.me (click_to_chat_link), búsqueda de WhatsApp (global_search_new_chat), código QR, etc. Viene solo entryPointSource (y, cuando está disponible, entryPointApp / entryPointDelaySeconds), sin sourceId / ctwaClid — Meta no adjunta datos de anuncio a estos.

Los mensajes orgánicos — y cualquier mensaje que no sea el primero de la conversación — no incluyen adOrigin. El texto predefinido de un anuncio no es prueba de origen: la atribución confiable viene de sourceId / ctwaClid.

Ejemplo (imagen recibida)

{
  "event": "message.exchange",
  "data": {
    "id": "wamid.123",
    "message": {
      "id": "wamid.123",
      "direction": "incoming",
      "timestamp": "2026-04-28T10:30:00Z",
      "chat":   { "jid": "5511999999999", "name": "João", "type": "private" },
      "sender": { "jid": "5511999999999", "name": "João" },
      "media": {
        "type":     "image",
        "url":      "https://media-abc.whatsapp.net/...",
        "mimetype": "image/jpeg",
        "size":     45678,
        "caption":  "Photo"
      }
    }
  },
  "instanceData": { "baseUrl": "https://api...", "instance": "minha", "token": "..." }
}

`message.status`

Acuses de entrega: delivered, read, played, etc.

Payload

{
  "status": "delivered | read | played | sender | read_self | played_self | retry | inactive | server_error",
  "messageIds": ["wamid.123", "wamid.124"],
  "timestamp":  "2026-04-28T10:45:00Z",
  "chat": {
    "jid": "5511999999999",
    "type": "private | group | broadcast",
    "isCommunity": true
  },
  "recipient":     "5511999999999",
  "messageSender": null,
  "isFromMe":      false
}

Enum `status`

Valor	Significado
`delivered`	El mensaje llegó al dispositivo del destinatario.
`read`	El destinatario lo leyó (con confirmaciones de lectura activas).
`played`	Audio/nota de voz reproducida.
`sender`	Eco interno (la propia fuente reportando entrega).
`read_self`	El propio usuario lo marcó como leído en otro dispositivo.
`played_self`	El propio usuario lo reprodujo en otro dispositivo.
`retry`	El servidor solicitó re-entrega (transitorio).
`inactive`	El destinatario lleva demasiado tiempo offline.
`server_error`	Error genérico del servidor de WhatsApp.

messageSender en grupos: JID del autor original del mensaje (relevante cuando alguien lee un mensaje de otro participante).
chat.isCommunity sigue la misma regla que message.exchange: presente y true solo cuando el chat es el canal de anuncios de una comunidad.

`call.update`

Eventos de llamadas: offer, accepted, rejected, terminated, latency.

Payload

{
  "type": "offer | accepted | rejected | terminated | notification | latency",
  "direction": "incoming | outgoing",
  "callId": "call-abc123",
  "from": "5511999999999",
  "to":   "5511888888888",
  "timestamp": "2026-04-28T10:35:00Z",
  "groupJid": null,
  "callMedia": "audio | video | null",
  "remotePlatform": "Android | iPhone | null",
  "remoteVersion": "2.23.15.74",
  "noticeType": "group | null",
  "reason": null,
  "duration": 123,
  "latency":  45.6,
  "latencyStatus": "Excellent | Good | Average | Poor"
}

Enum `type`

Valor	Cuándo se dispara
`offer`	Llamada recibida/enviada (timbre inicial).
`accepted`	El lado remoto contestó.
`rejected`	El lado remoto rechazó.
`terminated`	Llamada finalizada, se completa `duration` en segundos.
`notification`	Notificación contextual de llamada (p. ej., llamada perdida en grupo).
`latency`	Métrica de latencia durante la llamada (`latency` en ms, `latencyStatus`).

Para auto-rechazar llamadas, configura autoRejectCalls=true en el bloque de configuración de la instancia, aún recibirás los eventos offer + rejected en el webhook.

`group.flow`

Cambios de grupo: miembros, metadatos, configuraciones.

Payload, cambio de participante

{
  "type": "joined | left | promoted | demoted",
  "groupJid": "120363406289005073@g.us",
  "groupName": "Dev Team",
  "timestamp": "2026-04-28T11:00:00Z",
  "participants": [
    { "jid": "5511999999999", "action": "joined" }
  ]
}

Subtipos de metadatos

`type`	Significado
`name`	Nombre del grupo cambiado
`topic`	Descripción cambiada
`locked` / `unlocked`	Los miembros pueden/no pueden editar la información
`announce` / `not_announce`	Los miembros pueden/no pueden enviar mensajes
`ephemeral` / `not_ephemeral`	Mensajes efímeros activados/desactivados
`invite`	Enlace de invitación generado
`link` / `unlink`	Subgrupo vinculado/desvinculado de la comunidad
`delete`	Grupo eliminado
`membership_approval`	Modo de aprobación para nuevos miembros cambiado
`suspended` / `unsuspended`	Grupo suspendido/reactivado por WhatsApp

`instance.state`

Cambios en el estado de la propia instancia (conexión, QR, ban, emparejamiento).

Payload

{
  "instance": "minha",
  "state": "connected | disconnected | logged_out | stream_replaced | temp_banned | client_outdated | connect_failure | stream_error | cat_refresh_error | qr_ready | pair_success | pair_error | qr_scanned_no_multidevice | keepalive_timeout | keepalive_restored | manual_reconnect",
  "timestamp": "2026-04-28T10:50:00Z",
  "reason": "...",
  "reasonCode": 123,
  "message": "...",
  "expireAt": "2026-04-28T11:50:00Z",
  "expireInSeconds": 3600,
  "onConnect": true,
  "codes": ["1@abc...,xyz==,base64string"],
  "jid": "5511999999999@s.whatsapp.net",
  "platform": "iPhone | Android | Desktop",
  "errorMsg": "..."
}

Enum `state`

Estado	Significado	Campos extra completados
`connected`	Sesión activa, lista para enviar/recibir.	,
`disconnected`	Desconectado (transitorio, usualmente reconecta solo).	,
`logged_out`	Sesión invalidada (requiere nuevo `connect`).	`reason`
`stream_replaced`	Otra sesión tomó el control (conflicto multi-dispositivo).	,
`temp_banned`	Ban temporal aplicado por WhatsApp.	`expireAt`, `expireInSeconds`, `reason`
`client_outdated`	La versión de WhatsApp Web en uso está desactualizada, contactar soporte.	`message`
`connect_failure`	Falla durante la conexión.	`reason`, `reasonCode`
`stream_error`	Error de stream de WhatsApp.	`errorMsg`
`cat_refresh_error`	Falla al refrescar credenciales (`cat`).	`errorMsg`
`qr_ready`	Nuevo QR disponible para emparejamiento.	`codes[]`, `onConnect`
`pair_success`	Emparejamiento completado.	`jid`, `platform`
`pair_error`	Error durante el emparejamiento.	`errorMsg`
`qr_scanned_no_multidevice`	QR escaneado pero el dispositivo destino no soporta multi-dispositivo.	,
`keepalive_timeout`	Conexión inestable, keepalive no respondido.	,
`keepalive_restored`	Conexión estabilizada después de `keepalive_timeout`.	,
`manual_reconnect`	Reconexión disparada manualmente vía REST.	,

Para que tu cliente sepa cuándo refrescar el QR en la UI, escucha instance.state con state=qr_ready y renderiza data.codes[0].

`label.update`

Ediciones/asociaciones de etiquetas (etiquetas de WhatsApp Business).

Payload

{
  "type":   "edit | chat | message",
  "labelId": "1",
  "timestamp": "2026-04-28T10:00:00Z",
  "action": "updated | deleted | add | remove",

  // type=edit:
  "name": "Important",
  "color": 0,
  "labelType": "CUSTOM",
  "isActive": true,
  "isImmutable": false,
  "orderIndex": 1,
  "deleted": false,

  // type=chat:
  "chatJid": "5511999999999@s.whatsapp.net",
  "labeled": true,

  // type=message:
  "messageId": "wamid.abc"
}

Combinaciones `type` × `action`

`type`	`action` válida	Campos extra
`edit`	`updated`, `deleted`	`name`, `color`, `labelType`, `isActive`, `isImmutable`, `orderIndex`, `deleted`
`chat`	`add`, `remove`	`chatJid`, `labeled`
`message`	`add`, `remove`	`chatJid`, `messageId`

Eventos no emitidos (internos)

Capturados por el handler de whatsmeow pero no propagados vía webhook/WS:

*events.Picture, cambio de foto de perfil (solo registrado en log).
*events.FBMessage, Facebook Business (solo registrado en log).
*events.HistorySync, sincronización de historial (procesado y almacenado en BD).

Si necesitas consumir alguno de estos cambios, haz polling de los endpoints REST correspondientes (perfil, historial).

Referencias

Configurar webhook

Filtra eventos vía events[] en la configuración.

Configurar WebSocket

Misma sintaxis de filtro que el webhook.

Conectar vía WebSocket

Recibe eventos en tiempo real.

Resumen de eventos

Comparación webhook vs WebSocket.

​Envoltorio

​Filtrado y enrutamiento

​message.exchange

​Payload

​Campos condicionales

​adOrigin — atribución de origen (Click-to-WhatsApp)

​Ejemplo (imagen recibida)

​message.status

​Payload

​Enum status

​call.update

​Payload

​Enum type

​group.flow

​Payload, cambio de participante

​Subtipos de metadatos

​instance.state

​Payload

​Enum state

​label.update

​Payload

​Combinaciones type × action

​Eventos no emitidos (internos)

​Referencias

Configurar webhook

Configurar WebSocket

Conectar vía WebSocket

Resumen de eventos

Envoltorio

Filtrado y enrutamiento

`message.exchange`

Payload

Campos condicionales

`adOrigin` — atribución de origen (Click-to-WhatsApp)

Ejemplo (imagen recibida)

`message.status`

Payload

Enum `status`

`call.update`

Payload

Enum `type`

`group.flow`

Payload, cambio de participante

Subtipos de metadatos

`instance.state`

Payload

Enum `state`

`label.update`

Payload

Combinaciones `type` × `action`

Eventos no emitidos (internos)

Referencias