> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integración de Chatwoot

> Ordena conversaciones de WhatsApp en una bandeja de entrada de Chatwoot y deja que los agentes respondan desde Chatwoot.

Con Chatwoot activado, GOWA reenvía los mensajes de WhatsApp (entrante, y los salientes enviados desde el teléfono) a una bandeja de entrada del **canal API** de Chatwoot, y envía respuestas de los agentes de Chatwoot de vuelta a WhatsApp. Se admiten textos, imágenes, audio, vídeo, documentos, etiquetas, ubicaciones y contactos; los chats de grupo aparecen como una conversación por grupo, con el nombre del remitente prefijado.

```mermaid theme={null}
flowchart LR
  WA[WhatsApp] -- messages --> G[GOWA]
  G -- Chatwoot REST API --> CW[Chatwoot inbox]
  CW -- webhook /chatwoot/webhook --> G
  G -- agent reply --> WA
```

## 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](#auto-provisi%C3%B3n)).

**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**

```bash .env theme={null}
CHATWOOT_ENABLED=true
CHATWOOT_URL=https://chatwoot.example.com
CHATWOOT_API_TOKEN=your_user_access_token
CHATWOOT_ACCOUNT_ID=1
CHATWOOT_INBOX_ID=3
CHATWOOT_DEVICE_ID=my-device              # required with more than one device
CHATWOOT_WEBHOOK_SECRET=secret-shown-by-chatwoot
CHATWOOT_WEBHOOK_URL=https://gowa.example.com/chatwoot/webhook
```

Reiniciar GOWA: Las rutas de Chatwoot están registradas al inicio.

**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

| Variable | Por defecto | Descripción |
| - | - | - |
| `CHATWOOT_ENABLED` | `false` | Interruptor maestro. |
| `CHATWOOT_URL` | — | URL base de Chatwoot, sin barra final. |
| `CHATWOOT_API_TOKEN` | — | Token de acceso API de usuario. |
| `CHATWOOT_ACCOUNT_ID` | — | ID de cuenta numérica. |
| `CHATWOOT_INBOX_ID` | — | ID de bandeja de entrada numérica. Opcional con `CHATWOOT_AUTO_CREATE=true`; cuando se establece siempre gana. |
| `CHATWOOT_DEVICE_ID` | — | Dispositivo (slot ID o JID) que envía respuestas al agente. Requerido cuando existe más de un dispositivo. |
| `CHATWOOT_WEBHOOK_URL` | — | URL web de GOWA pública; usada al crear automáticamente la bandeja de entrada. |
| `CHATWOOT_WEBHOOK_SECRET` | — | Verifica webhooks entrantes de Chatwoot. Un secreto vacío y efectivo rechaza las llamadas a menos que se habilite la anulación explícita sin firmar. |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `false` | Aceptar peticiones sin ningún secreto efectivo. Restringir esto a una red de confianza. |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `5m` | Máxima edad / reloj sesgo de `X-Chatwoot-Timestamp`. |
| `CHATWOOT_AUTO_CREATE` | `false` | Reutilizar o crear una bandeja de entrada de API llamada `CHATWOOT_INBOX_NAME` al inicio. |
| `CHATWOOT_INBOX_NAME` | `WhatsApp` | Nombre de la bandeja de entrada para autoprovisioning. |
| `CHATWOOT_IMPORT_MESSAGES` | `false` | Importar historial automáticamente cuando un dispositivo se conecta. |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `3` | Días de historia a importar. |
| `CHATWOOT_IMPORT_DB_URI` | — | URI PostgreSQL de Chatwoot para importar el historial directo (mantiene las marcas de tiempo originales). |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `true` | Importación directa: inserte `[image]`-marcadores de posición para medios que no pueden ser descargados. |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `false` | Importación directa: subir medios a través de la API REST para que se creen archivos adjuntos. |
| `CHATWOOT_REOPEN_CONVERSATION` | `true` | Vuelva a abrir una conversación resuelta cuando el contacto escribe de nuevo. |
| `CHATWOOT_CONVERSATION_PENDING` | `false` | Crea nuevas conversaciones como `pending` en lugar de `open`. |
| `CHATWOOT_IGNORE_JIDS` | — | JIDs o comodines separados por comas (`@g.us`, `@s.whatsapp.net`, `@lid`) nunca reproducido. |
| `CHATWOOT_SIGN_MSG` | `false` | El agente prefijo responde con el nombre del agente. |
| `CHATWOOT_SIGN_DELIMITER` | `\n\n` | Separador entre firma y mensaje. |
| `CHATWOOT_FORWARD_EDITS` | `true` | Mirror WhatsApp edita como notas privadas. |
| `CHATWOOT_FORWARD_DELETES` | `true` | Mirror delete-for -everyone como notas privadas. |
| `CHATWOOT_EVENTS` | Sigue `WHATSAPP_WEBHOOK_EVENTS` | Eventos separados por comas para reenviar a Chatwoot. |
| `CHATWOOT_MESSAGE_READ` | `false` | Sincronizar estado de lectura en ambos sentidos. |
| `CHATWOOT_MESSAGE_DELETE` | `false` | Eliminar el mensaje vinculado en el otro lado. |
| `CHATWOOT_REVOKE_ON_DELETE` | `false` | Revocar mensajes de WhatsApp salientes enlazados cuando un agente elimina su mensaje de Chatwoot. |
| `CHATWOOT_ALLOWED_HOSTS` | — | Lista permitida de hosts que `chatwoot_url` por dispositivo puede dirigirse. |

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](https://gowa-docs.mintlify.site/es/configuration.md).

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:

1. **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.
2. Un HMAC `X-Hub-Signature-256` del cuerpo.
3. El secreto en una cabecera `X-Chatwoot-Webhook-Secret` o `X-Gowa-Chatwoot-Secret`.
4. `?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.

Los fallos devuelven `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

Con `CHATWOOT_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):

```bash theme={null}
curl -u admin:changeme -X PUT http://localhost:3000/devices/sales/chatwoot/config \
  -H "Content-Type: application/json" \
  -d '{
    "chatwoot_url": "https://chatwoot.example.com",
    "account_id": 1,
    "inbox_id": 7,
    "api_token": "token-for-this-inbox",
    "webhook_secret": "secret-of-this-api-channel",
    "enabled": true
  }'
```

La respuesta incluye `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`.

> [!WARNING]
>
> Una vez que existe **cualquiera** configuración por consola, el destino `CHATWOOT_*` ya no se utiliza como una reserva. Los dispositivos sin una configuración no son reproducidos.

* `api_token` es almacenado en la base de datos de GOWA y enmascarado en lecturas; `webhook_secret` nunca se regresa.
* `chatwoot_url` debe ser HTTP o HTTPS sin credenciales. Sin `CHATWOOT_ALLOWED_HOSTS`, las direcciones privadas, loopback, link-local y metadatos son rechazadas. Un host de coincidencia explícita en `CHATWOOT_ALLOWED_HOSTS` es 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_id` o `inbox_id` después de que las conversaciones estén enlazadas devuelve `409`; 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 resuelve `in_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 GOWA `main` 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](https://gowa-docs.mintlify.site/es/concepts/webhooks.md#%C3%A1lbumes-y-mensajes-estructurados) 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

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/chatwoot/sync \
  -H "Content-Type: application/json" \
  -d '{"device_id": "my-device", "days_limit": 7, "include_media": true, "include_groups": true}'

curl -u admin:changeme "http://localhost:3000/chatwoot/sync/status?device_id=my-device"
```

Los valores por defecto son `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

| Síntomas | Comprobar |
| - | - |
| Respuestas del agente no entregadas | `CHATWOOT_DEVICE_ID` set and device logged in; webhook URL correcta y pública; `DEVICE_NOT_AVAILABLE` in logs means no usable device. |
| `401` en `/chatwoot/webhook` | Secundaria discordancia o deriva de reloj (ver arriba). |
| Mensajes de WhatsApp que faltan en Chatwoot | Marque `CHATWOOT_ENABLED`, el token de usuario, los IDs de cuenta y bandeja de entrada, y la conectividad a `CHATWOOT_URL`. En nuevas versiones, compruebe que el filtro de eventos efectivo incluye `message`. |
| `CHATWOOT_NOT_CONFIGURED` | Falta URL, token, ID de cuenta o ID de bandeja de entrada. |

Ejecuta con `APP_DEBUG=true` y busca líneas de registro comenzando con `Chatwoot:` y `Chatwoot Webhook:`. La fuente [Guía de Chatwoot](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/chatwoot.md) cubre las reglas de importación y formato de base de datos directa en mayor profundidad.


## Related topics

- [Referencia de configuración](https://gowa-docs.mintlify.site/es/configuration.md)
- [Obtener metadatos del servidor](https://gowa-docs.mintlify.site/es/api-reference/app/obtener-metadatos-del-servidor.md)
- [Final de webhook de Chatwoot](https://gowa-docs.mintlify.site/es/api-reference/chatwoot/final-de-webhook-de-chatwoot.md)
- [Progreso de sincronización de Chatwoot](https://gowa-docs.mintlify.site/es/api-reference/chatwoot/progreso-de-sincronización-de-chatwoot.md)
- [Lista de configuraciones de Chatwoot por dispositivo](https://gowa-docs.mintlify.site/es/api-reference/chatwoot/lista-de-configuraciones-de-chatwoot-por-dispositivo.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.