Requisitos
- GOWA accesible desde Chatwoot a través de una URL pública (para webhooks de respuesta de agentes).
- Una cuenta de Chatwoot con acceso de administrador y un token de acceso de API de usuario.
- Al menos un dispositivo WhatsApp para iniciar sesión.
Configurar
1
Crear bandeja de entrada de canal API
En Chatwoot vaya a Ajustes → Bandejas de entrada → Añadir bandeja de entrada → API. Ten en cuenta el ID de la bandeja de entrada numérico de la URL de la bandeja de entrada, y el secreto webhook se muestra para el canal. Alternativamente, deje que GOWA cree la bandeja de entrada (ver Auto-provisioning).
2
Recoge IDs y token
El ID de cuenta es el número en
/app/accounts/<id>/.... Copie el token de acceso de un usuario desde Configuración de perfil. Ambos IDs deben ser los identificadores numéricos, no el canal identifier o hmac_token.3
Configurar GOWA
.env
4
Chatwoot de Puntos en GOWA
Establece la URL del webhook del canal API a
https://gowa.example.com/chatwoot/webhook (con APP_BASE_PATH, incluye la ruta base). Esta ruta es pública: está protegida por el secreto webhook, no Basic Auth.5
Prueba
Enviar un mensaje al número de WhatsApp desde otro teléfono; debería aparecer en la bandeja de entrada. Responda desde Chatwoot y comprueba que llegue a WhatsApp.
Configuración
La mayoría de las configuraciones también tienen una bandera
--chatwoot-*; CHATWOOT_URL, CHATWOOT_API_TOKEN, CHATWOOT_ACCOUNT_ID y CHATWOOT_INBOX_ID son solo de entorno. Vea la referencia de configuración.
En GOWA main después de v9.9.0, establece CHATWOOT_EVENTS=message para seguir reflejando los mensajes en Chatwoot mientras se filtra las entregas ordinarias de webhook por separado. El selector message también permite reacciones, recibos, ediciones y borrados a través del filtro de Chatwoot. La lectura separada, edición y eliminación de ajustes todavía aplican.
Deja CHATWOOT_EVENTS vacío para heredar WHATSAPP_WEBHOOK_EVENTS. Si el filtro efectivo está vacío, permite todos los eventos soportados. Si excluye message, GOWA registra una advertencia al iniciar y deja de reproducir los mensajes de WhatsApp en Chatwoot.
En esas compilaciones, GOWA envía el token de usuario de Chatwoot en la cabecera api-access-token para que nginx pueda pasarlo a través de sus ajustes de cabecera predeterminados.
Secreto de Webhook
Un secreto de webhook efectivo vacío rechaza la entrega.CHATWOOT_WEBHOOK_ALLOW_UNSIGNED=true permite explícitamente la entrega sin firmar cuando el secreto efectivo está vacío. Con un secreto configurado, cada solicitud debe demostrarlo por uno de:
- Firma de Chatwoot (
X-Chatwoot-Signature+X-Chatwoot-Timestamp), recomendado. Usa el propio secreto del canal de la API. GOWA comprueba el HMAC-SHA256 de<timestamp>.<raw body>y rechaza marcas de tiempo fuera de la tolerancia configurada. - Un HMAC
X-Hub-Signature-256del cuerpo. - El secreto en una cabecera
X-Chatwoot-Webhook-SecretoX-Gowa-Chatwoot-Secret. ?secret=en la URL del webhook, sólo para versiones de Chatwoot que no pueden firmar ni añadir cabeceras. El secreto aparece en los registros de acceso.
401; GOWA registra el motivo (signature does not match indica que el secreto es incorrecto; timestamp outside the tolerance window indica un desfase del reloj).
El dispositivo webhook_secret reemplaza el secreto global para ese dispositivo tanto en los puntos finales compartidos como por dispositivo. Sin un secreto de dispositivo, se aplica el secreto global. GOWA verifica el secreto para el dispositivo enrutado antes de enviar, eliminar, marcar leer o escribir datos. Preferir la URL de devolución de llamada por dispositivo cuando varios dispositivos usan los mismos identificadores de cuenta y bandeja de entrada.
Una petición repetida firmada por Chatwoot que ya recibió 2xx se reconoce con 200 y se omite dentro de la ventana de la marca de tiempo. Las solicitudes fallidas siguen siendo reintentables. Una petición idéntica todavía en curso puede devolver 503 después de esperar hasta 30 segundos. La memoria de repetición es local en el proceso, se pierde al reiniciar y se limita a 65,536 solicitudes aceptadas. No se comparte entre instancias de GOWA. Dos entregas firmadas por separado del mismo mensaje de Chatwoot todavía pueden enviarse dos veces. HMACs, cabeceras secretas y secretos de consulta no proporcionan esta deduplicación de entrega.
Auto-provisión
ConCHATWOOT_AUTO_CREATE=true y sin CHATWOOT_INBOX_ID, GOWA busca una bandeja de entrada de API llamada CHATWOOT_INBOX_NAME al inicio y reutiliza, o crea una con CHATWOOT_WEBHOOK_URL como su webhook.
Una bandeja de entrada por dispositivo
Las variables de entorno configuran un destino compartido por todos los dispositivos. Para enrutar cada dispositivo a su propia bandeja de entrada, cuenta o servidor de Chatwoot, almacene configuraciones por dispositivo (Basic Auth aplicies):webhook_url (<base>/chatwoot/webhook/<device_id>); establézcala como el webhook de la bandeja de entrada. Otras rutas: GET /chatwoot/configs, GET y DELETE /devices/{device_id}/chatwoot/config.
api_tokenes almacenado en la base de datos de GOWA y enmascarado en lecturas;webhook_secretnunca se regresa.chatwoot_urldebe ser HTTP o HTTPS sin credenciales. SinCHATWOOT_ALLOWED_HOSTS, las direcciones privadas, loopback, link-local y metadatos son rechazadas. Un host de coincidencia explícita enCHATWOOT_ALLOWED_HOSTSes confiado y puede dirigirse a Chatwoot autoalojados en una red privada. Establezca esta lista permitida sólo a los hosts que controles.- Cambiando
chatwoot_url,account_idoinbox_iddespués de que las conversaciones estén enlazadas devuelve409; elimina y recrea la configuración en su lugar. - Se puede crear una configuración antes de los pares de dispositivos.
- La importación directa de bases de datos sólo funciona en modo de configuración simple (entorno).
Respuestas y formato
Cuando un agente usa Respuesta en Chatwoot, GOWA cita el mensaje original de WhatsApp cuando puede resolverlo en la tienda local del dispositivo de envío y en el mismo chat. Esto se aplica al texto y a todos los archivos adjuntos, incluyendo el respaldo de audio a archivo. El título solo se mantiene en el primer archivo adjunto. Para un mensaje entrante de WhatsApp, GOWA resuelvein_reply_to_external_id con el prefijo WAID:<id>. Para una respuesta de un agente anterior, el numérico in_reply_to se resuelve a través de un enlace de mensaje duradero en el mismo dispositivo, conversación, cuenta, bandeja de entrada y configuración. Un mensaje con múltiples archivos adjuntos cita su primer archivo. Si el destino no se puede resolver, la respuesta se entrega sin una cita.
Las respuestas entrantes de WhatsApp y el hilo de reacciones en el mensaje de referencia en Chatwoot. Los enlaces Markdown de respuesta del agente se convierten en texto de WhatsApp legible. Listas, saltos de línea, y código se conservan. Los separadores de firmas vacíos se eliminan. CHATWOOT_SIGN_MSG prefiere el nombre del agente después de esta conversión.
Sólo se envían mensajes públicos de agentes salientes elegibles. Las notas privadas y los chats excluidos no son reenviados. GOWA utiliza el dispositivo configurado y la identidad de cuenta/bandeja de entrada para enrutar llamadas compartidas. Las llamadas por dispositivo proporcionan una ruta sin ambigüedades.
Encuestas y borrados de agente
En GOWAmain después de v9.9.0, la creación de encuestas de réplicas de Chatwoot, ediciones y opciones añadidas. Para procesar votaciones individuales, suscríbete a message en WhatsApp webhooks y lee los datos de la encuesta estructurada.
En estas compilaciones, establece CHATWOOT_REVOKE_ON_DELETE=true para sincronizar sólo borra de Chatwoot a WhatsApp. El borrado debe coincidir con enlaces duraderos a mensajes salientes bajo la configuración activa de Chatwoot. GOWA revoca cada mensaje enlazado de WhatsApp, incluyendo adjuntos enviados por separado. Con CHATWOOT_FORWARD_DELETES=true, borra de WhatsApp todavía aparecen como notas privadas. Usa CHATWOOT_MESSAGE_DELETE=true para borrar mensajes enlazados en ambas direcciones.
Importar historial
days_limit=3, include_media=true, y include_groups=true. La sincronización lee el almacenamiento local de chat de GOWA y se ejecuta en segundo plano. Cada dispositivo puede ejecutar una sincronización a la vez.
En GOWA main después de v9.9.0, la sincronización del historial puede pedir al teléfono que vuelva a cargar medios caducados. El teléfono debe estar en línea y todavía tener el archivo. Si el teléfono no responde en un plazo de 30 segundos, la sincronización se salta más solicitudes de volver a subir para que se ejecuten y continúa importando mensajes. Un mensaje cuyo archivo permanece no disponible es importado sin el archivo adjunto.
La ruta REST no puede establecer marcas de tiempo originales; los mensajes importados obtienen el tiempo de importación. Para Chatwoot, CHATWOOT_IMPORT_DB_URI escribe directamente en PostgreSQL de Chatwoot y los preserva.
Con CHATWOOT_REOPEN_CONVERSATION=true en GOWA main después de v9.9.0, la sincronización de la historia sólo reabre una conversación resuelta cuando tiene un nuevo mensaje para importar. La sincronización REST reabre la conversación antes de publicar y vuelve a intentar el chat en la próxima sincronización si la reapertura falla. La importación directa de PostgreSQL vuelve a abrirla en la misma transacción que la escritura del mensaje. Con la opción desactivada, la sincronización REST crea una conversación fresca para nuevos mensajes, mientras que la importación directa sigue usando la conversación resuelta.
Entrega y reintentos
Mensajes en vivo que golpearon un error transitorio de Chatwoot (error de red, HTTP 429 o 5xxx) se ponen en cola en almacenamiento local y se reintentan en segundo plano con un límite de respaldo exponencial. Otros errores de 4xx son registrados y soltados.Solución de problemas
Ejecuta con
APP_DEBUG=true y busca líneas de registro comenzando con Chatwoot: y Chatwoot Webhook:. La fuente Guía de Chatwoot cubre las reglas de importación y formato de base de datos directa en mayor profundidad.