Saltar al contenido principal
GOWA POSTs un documento JSON a tu URL para cada evento WhatsApp que recibe: mensajes, recibos, reacciones, ediciones, eliminaciones, indicadores de tecleo, cambios de grupo, etiquetas, boletines y llamadas. No hay ningún punto final de registro de webhook. Configurar webhooks al inicio, o por dispositivo a través de /devices/{device_id}/webhook.

Cómo funciona el envío

Cada URL de destino se entrega de forma independiente, con su propio secreto y reintentos.

Configurar

Banderas equivalentes: --webhook, --webhook-secret, --webhook-events, --webhook-ignore-jids, --webhook-insecure-skip-verify, y --webhook-all-device-receipts. Establece explícitamente una clave de firma privada. Si no se configura ninguna clave o se usa el antiguo valor publicado secret, GOWA genera una clave aleatoria que cambia al reiniciar y registra una advertencia. Los receptores necesitan una clave compartida explícita para verificar las firmas tras los reinicios. Los certificados HTTPS se verifican de forma predeterminada.

Eventos

Los nombres de eventos en la lista permitida son insensibles mayúsculas y minúsculas.

Carga útil

Cada solicitud tiene el mismo sobre:
Las respuestas añaden replied_to_id y quoted_body. Los recibos usan ids (array) y receipt_type. Agrupa eventos participantes llevan chat_id, type, y jids. Los cambios de nombre de grupo usan una forma separada group.info. sender_display_name aparece sólo cuando from es una cadena no vacía. Para otro remitente, GOWA prefiere el nombre de contacto guardado, el nombre de envío en vivo del evento, el nombre de la empresa, y la parte de usuario de JID. Para la cuenta activa, prefiere el nombre push de la cuenta, luego su identidad JID. La resolución es el mejor esfuerzo. El legado from_name sigue siendo el mensaje evento push name. Los mensajes entrantes pueden incluir is_business: true, verified_name y verified_level cuando WhatsApp proporciona un certificado de nombre verificado. En caso contrario, estos campos se omiten. Su ausencia no permite determinar si el remitente es una empresa, y verified_level es el valor sin procesar proporcionado por WhatsApp, no una garantía de una insignia oficial.

Medios

Con WHATSAPP_AUTO_DOWNLOAD_MEDIA=true (por defecto), los medios se guardan en statics/media/ y el campo multimedia guarda la ruta:
Cuando hay un pie de foto, el campo pasa a ser {"path": "...", "caption": "..."} y el pie de foto también aparece en body. Con la descarga automática desactivada, es {"url": "https://mmg.whatsapp.net/...", "caption": "..."}; descarga el archivo más tarde con GET /message/{message_id}/download?phone=<chat>. El catálogo completo de payloads (encuestas, ubicaciones, contactos, vista-una vez, referencias de anuncios y más) está en la línea de desarrollo principal referencia de payhook webhook.

Álbumes y mensajes estructurados

Un álbum llega como varios eventos message. La cabecera no tiene cuerpo de mensaje e incluye los recuentos de elementos esperados:
Cada foto o video llega en su propio evento mediático normal con album_id: "ALBUM_HEADER_ID". Agrupa elementos con ese ID. El encabezado no es un elemento multimedia descargable y no se remite a Chatwoot. Creación de encuestas, votos, ediciones y opciones añadidas también usan message. Inspecciona el objeto estructurado poll en lugar de depender de body. Los hasks de opción son hexadecimales en minúsculas SHA-256 con nombres de opción exactos. Las suscripciones existentes WHATSAPP_WEBHOOK_EVENTS=message reciben estas interacciones.

Presencia en línea y fuera de línea

Suscríbete para cada contacto individual utilizando el mismo dispositivo que recibe los eventos:
Una respuesta exitosa contiene results.subscribed: true y results.jid. Grupo y boletines JIDs son rechazados. Una suscripción no anula la configuración de presencia de tu dispositivo. Para actualizaciones continuas, inicia GOWA con:
El pulso de presencia por defecto termina marcando el dispositivo no disponible, lo que detiene las actualizaciones de presencia de contactos. Marcar el dispositivo disponible suprime las notificaciones push de WhatsApp en el teléfono mientras se ejecuta. Cuenta para esta operación antes de habilitar el seguimiento continuo.
state es available o unavailable. last_seen se omite cuando se desconoce u se oculta en la configuración de privacidad del contacto. from_lid se incluye cuando corresponda. Typing y grabación permanecen separados eventos chat_presence y no usen esta suscripción.

Cambios de nombre de grupo

name_set_by se resuelve de LID al JID del teléfono cuando es posible y se omite cuando WhatsApp no identifica al actor. Suscríbete a group.info explícitamente si tu lista de eventos excluye otros eventos.

Actualizaciones del boletín

newsletter.message reporta contadores en vivo en lugar de un nuevo mensaje garantizado. Las entradas siempre incluyen server_id. message_id, type, y timestamp son omitidos cuando WhatsApp no los suministra. Pueden omitirse contadores cero o ausentes.
Cuando esté disponible, reaction_counts contiene el recuento de reacción de WhatsApp. Consume actualizaciones por ID del boletín de noticias e ID del servidor. No trate un contador que falte como un restablecimiento a cero.

Restricciones de la cuenta y cierre de sesión

Los eventos del dispositivo siempre llevan session_id, así que las ranuras usando el mismo número de WhatsApp siguen siendo distinguibles. El evento utiliza la configuración del webhook de la zona de emisión. Un cierre de sesión remoto mantiene la ranura para volver a emparejar e informa de la identidad de antes de salir. Los ajustes de webhook de la ranura sobreviven a la revinculación. Estos eventos no se envían a Chatwoot.
Los códigos son enviados sin cambios y la razón de que el texto viene de lo que quiera. Los códigos desconocidos todavía llegan. Los códigos de salida 403 y 406 solos no establecen la causa exacta. Una duración temporal de bloqueo de cero significa que WhatsApp no ha expirado. Un bloqueo de tiempo de alcance restringe el inicio de nuevos chats y puede producir el error de envío 463.

Verificar firmas

Cada solicitud lleva X-Hub-Signature-256: sha256=<hex>, un cuerpo HMAC-SHA256 de la solicitud cruda clavado con el secreto del webhook. Calcular sobre los bytes exactos recibidos, antes de analizar JSON.

Entrega y reintentos

  • Cada intento expira después de 10 segundos.
  • Cualquier respuesta que no sea 2xx o error de red es recuperada. GOWA compone hasta 5 intentos, esperando 1 s, 2 s, 4 y 8 s entre ellos. La fecha límite del contexto del gestor de eventos puede detener la entrega antes de que se completen todos los intentos.
  • Después del último fallo el evento es eliminado y registrado. No hay cola persistente ni almacén de letras muertas.
  • Varias URLs se entregan de forma independiente.
Responde 2xx después de aceptar el evento en su propia cola de procesamiento duradera. Hace que los manejadores sean idempotentes porque un evento reprobado puede llegar más de una vez.

Recibos de dispositivos conectados

De forma predeterminada, GOWA reenvía los reconocimientos de contacto desde dispositivos primarios sólo para reducir duplicados. Los recibos de la cuenta corriente read y read-self pasan de todos sus dispositivos. Para estos recibos de propia cuenta, payload.from es el JID de la cuenta y payload.ids identifica los mensajes entrantes que fueron leídos. Establece WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true o --webhook-all-device-receipts=true para recibir también las confirmaciones de los contactos desde los dispositivos vinculados, incluso cuando el teléfono del contacto esté desconectado. La opción de la CLI prevalece sobre la variable de entorno, incluido un valor explícito false. Esta opción puede producir reconocimientos duplicados o fuera de orden. Aplicar actualizaciones idempotentemente por cuenta, chat e ID del mensaje. Nunca reduzca un mensaje de lectura para entregarlo cuando llegue un recibo antiguo. Los IDs de mensajes y los JIDs de remitente mantienen su forma canónica sin sufijos de dispositivos.

Filtrar eventos

Por tipo: WHATSAPP_WEBHOOK_EVENTS=message,message.ack reenvía sólo esos eventos. Por chat o enviador: WHATSAPP_WEBHOOK_IGNORE_JIDS coincide con chat_id, from, chat_lid y from_lid. Las entradas que empiezan con @ son comodines para un espacio de direcciones completo (@g.us, @s.whatsapp.net, @lid); cualquier otra cosa es un JIG exacto.
@s.whatsapp.net también coincide con los mensajes de grupo, porque su from es un usuario JID. Usa @g.us para silenciar grupos. Los dos filtros combinados: un evento se envía sólo si su tipo está permitido y su JID no es ignorado.

Webhooks por dispositivo

Dar a una ranura su propio webhook, secreto y lista de eventos permitidos:
Los mismos campos son aceptados por POST /devices. Lee la configuración actual con GET /devices/{device_id}/webhook. Send "webhook_url": "" para borrarlo. Un dispositivo vacío webhook_secret o webhook_events vuelve a la configuración global correspondiente. El dispositivo almacenado webhook_insecure_skip_verify boolean reemplaza la configuración global de TLS. En particular, false mantiene habilitada la verificación de certificados incluso cuando el bypass global está habilitado. Por defecto una URL por dispositivo reemplaza el WHATSAPP_WEBHOOK global para esa ranura. Con WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true se agrega a las URL globales en su lugar: la URL del dispositivo utiliza el secreto y lista permitida, las URLs globales mantienen las globales, y una URL presente en ambas recibe el evento una vez. Las reglas Ignore-JID se aplican a ambos.

Probando localmente

Exponga un receptor local con un túnel (por ejemplo ngrok http 8080) y establezca WHATSAPP_WEBHOOK en la URL del túnel. Con --debug=true, GOWA registra cada intento de entrega y fallo.

Otras formas de recibir eventos

  • WebSocket en /ws?device_id=<id> empuja los eventos de emparejamiento y estado con los clientes del panel de control. Usa webhooks para la entrega de mensajes.
  • Polling: GET /chats y GET /chat/{chat_jid}/messages leen el almacenamiento local de chat de GOWA. Vea Recibiendo mensajes.