> ## 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.

# 聊天woot 集成

> 将WhatsApp对话镜像成聊天窗口收件箱，让代理人从Chatwoot 回复。

使用 Chatwoot 启用，GOWA 转发WhatsApp 消息(正在导入) 和从手机发送到Chatwoot **API 通道**的收件箱，并且将来自Chatwoot 的代理回复发送回WhatsApp。 文本、图像、音频、视频、文档、贴纸、位置和联系人都被支持；群聊每个群组显示为一个对话，并且有发件人名称前缀。

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

## B. 所需经费

* 通过 Chatwoot 可访问公共网址 (适合代理回复Webhooks)。
* 带有管理员权限的Chatwoot 帐户和用户 API 访问令牌。
* 至少有一个登入的 WhatsApp 设备。

## 设置

**1. 创建 API 频道收件箱**

在 Chatwoot 中转到**设置 -> 收件箱 -> 添加收件箱 -> API**。 请注意收件箱URL中的数字**收件箱ID**，以及频道中的 **webhook 秘密**Chatwoot 显示。 或者，让 GOWA 创建收件箱(见 [Auto-provisioning](#%E8%87%AA%E5%8A%A8%E9%85%8D%E7%BD%AE))。

**2. 收集 ID 和令牌**

**account ID** 是 `/app/accounts/<id>/...` 中的数字。复制用户 **Access token** 从 **Profile 设置** 。 两个ID都必须是数字ID，而不是频道 `identifier` 或 `hmac_token` 。

**3. 配置 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
```

重新启动GOWA：Chatwoot 路由在启动时注册。

**4. GOWA地区的交汇点**

将 API 通道的 webhook URL 设置为 `https://gowa.example.com/chatwoot/webhook` (使用 `APP_BASE_PATH`, 包括基础路径)。 此路由是公开的：它受到webhook 秘密的保护，而不是基本Auth的保护。

**5. 测试**

从另一个手机消息WhatsApp 号码；它应出现在收件箱中。请从Chatwoot 回复，然后检查它到达WhatsApp 上。

## 配置

| 变量 | 默认设置 | 描述 |
| - | - | - |
| `CHATWOOT_ENABLED` | `false` | 主开关。 |
| `CHATWOOT_URL` | — | 聊天woot base URL，无尾随斜杠。 |
| `CHATWOOT_API_TOKEN` | — | 用户 API 访问令牌。 |
| `CHATWOOT_ACCOUNT_ID` | — | 数字账户 ID。 |
| `CHATWOOT_INBOX_ID` | — | 数字形式的收件箱 ID。设置 `CHATWOOT_AUTO_CREATE=true` 时可选；一旦设置此 ID，则始终优先使用它。 |
| `CHATWOOT_DEVICE_ID` | — | 发送代理回复的设备 (栏位 ID 或 JID) 。当存在多个设备时需要。 |
| `CHATWOOT_WEBHOOK_URL` | — | Public GOWA webhook URL；在自动创建收件箱时使用。 |
| `CHATWOOT_WEBHOOK_SECRET` | — | 验证收到的Chatwoot webhooks。除非启用明确的无签名覆盖，否则无效的秘密拒绝呼叫。 |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `false` | 接受没有有效密钥的请求。将此限制在信任的网络。 |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `5m` | `X-Chatwoot-Timestamp`的最大年龄/时钟扭曲。 |
| `CHATWOOT_AUTO_CREATE` | `false` | 在启动时重新使用或创建名为 `CHATWOOT_INBOX_NAME` 的 API 收件箱。 |
| `CHATWOOT_INBOX_NAME` | `WhatsApp` | 自动预配的收件箱名。 |
| `CHATWOOT_IMPORT_MESSAGES` | `false` | 设备连接时自动导入历史记录。 |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `3` | 要导入的历史日子。 |
| `CHATWOOT_IMPORT_DB_URI` | — | 用于直接导入历史记录的 Chatwoot PostgreSQL URI (保留原始时间戳)。 |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `true` | 直接导入：为无法下载的媒体插入 `[image]` 形式的占位符。 |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `false` | 直接导入：通过REST API 上传介质，因此附件已创建。 |
| `CHATWOOT_REOPEN_CONVERSATION` | `true` | 当联系人再次写入时重新打开已解决的对话。 |
| `CHATWOOT_CONVERSATION_PENDING` | `false` | 以 `pending` 而不是 `open` 创建新的对话。 |
| `CHATWOOT_IGNORE_JIDS` | — | 以逗号分隔的 JID 或通配符（`@g.us`、`@s.whatsapp.net`、`@lid`）；匹配的对象始终不会同步。 |
| `CHATWOOT_SIGN_MSG` | `false` | 前缀代理回复使用代理的名称。 |
| `CHATWOOT_SIGN_DELIMITER` | `\n\n` | 签名与电文之间的分隔符。 |
| `CHATWOOT_FORWARD_EDITS` | `true` | 镜像WhatsApp 将其编辑为私人笔记。 |
| `CHATWOOT_FORWARD_DELETES` | `true` | 将每个人删除作为私人注释镜像。 |
| `CHATWOOT_EVENTS` | 跟随`WHATSAPP_WEBHOOK_EVENTS` | 以逗号分隔的事件转发到查特沃特。 |
| `CHATWOOT_MESSAGE_READ` | `false` | 同步读取两种方式的状态。 |
| `CHATWOOT_MESSAGE_DELETE` | `false` | 删除对方链接的消息。 |
| `CHATWOOT_REVOKE_ON_DELETE` | `false` | 当代理人删除聊天窗口消息时，撤销链接到传出的 WhatsApp 消息。 |
| `CHATWOOT_ALLOWED_HOSTS` | — | 允许每台设备 `chatwoot_url` 可以针对主机列表。 |

大多数设置也有对应的 `--chatwoot-*` 标志；`CHATWOOT_URL`、`CHATWOOT_API_TOKEN`、`CHATWOOT_ACCOUNT_ID` 和 `CHATWOOT_INBOX_ID` 只能通过环境变量设置。请参阅[配置参考](https://gowa-docs.mintlify.site/zh/configuration.md)。

在 v9.9.0 之后的 GOWA `main` 分支上，设置 `CHATWOOT_EVENTS=message` 可继续将消息同步到 Chatwoot，同时单独过滤普通 webhook 投递。`message` 选择器还允许表情回应、回执、编辑和删除事件通过 Chatwoot 过滤器。独立的已读、编辑和删除设置仍然生效。

将 `CHATWOOT_EVENTS` 留空可继承 `WHATSAPP_WEBHOOK_EVENTS`。如果最终生效的过滤器为空，则允许所有受支持的事件。如果过滤器排除了 `message`，GOWA 会在启动时记录警告，并停止将 WhatsApp 消息同步到 Chatwoot。

在这些构建中，GOWA会在 `api-access-token` 标题中发送Chatwoot 用户令牌，因此nginx 可以通过默认标题设置传递它。

## Webhook 密钥

一个空有效的 webhook 秘密拒绝交付。`CHATWOOT_WEBHOOK_ALLOW_UNSIGNED=true` 明确允许在有效的秘密为空时发送未签名的货物。 已配置秘密，每个请求必须由以下之一证明：

1. **Chatwoot 签名**（`X-Chatwoot-Signature` + `X-Chatwoot-Timestamp`），推荐使用此方式。使用 API 渠道自身的 webhook 密钥。GOWA 会校验 `<timestamp>.<raw body>` 的 HMAC-SHA256，并拒绝超出所配置容差范围的时间戳。
2. 尸体的`X-Hub-Signature-256`HMAC'。
3. 通过 `X-Chatwoot-Webhook-Secret` 或 `X-Gowa-Chatwoot-Secret` 请求头传递密钥。
4. `?secret=`在 webhook 的 URL，仅适用于无法签名或添加标题的 Chatwoot 版本。然后在访问日志中显示秘密。

验证失败时返回 `401`；GOWA 会记录原因（`signature does not match` 表示密钥错误，`timestamp outside the tolerance window` 表示时钟偏差）。

设备的 `webhook_secret` 在共享和单个设备的端点上替换该设备的全局秘密。如果没有设备保密，则应用全局秘密。 GOWA 在发送、删除、标记读取或写入数据之前验证路由设备的秘密。 当几个设备使用相同的帐户和收件箱ID时，优先使用每个设备的回调URL。

一个重复的 Chatwoot-签名且已经收到了 `2xx` 的请求通过 `200` 承认，并在时间戳窗口内跳过了。 失败请求仍然可以重试。一个仍在进行中的相同请求可以在等待30秒后返回 `503` 。 回放内存是本地的，重启后丢失，与65 536个被接受的请求连接。它不是在 GOWA 实例之间共享的。 两个单独签名发送的Chatwoot 消息仍然可以发送两次。 仅限实体HMAC、秘密信头和查询秘密不会提供这种退货。

## 自动配置

使用 `CHATWOOT_AUTO_CREATE=true` 且没有 `CHATWOOT_INBOX_ID` GOWA 在启动时寻找名为 `CHATWOOT_INBOX_NAME` 的 API 收件箱，并重新使用它，或者创建一个 `CHATWOOT_WEBHOOK_URL` 作为其Webhook。

## 每台设备一个收件箱

环境变量配置所有设备共享的一个目标。 为了将每个设备路由到自己的收件箱、帐户或聊天服务器，存储每个设备的配置(基本认证应用)：

```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
  }'
```

响应包含 `webhook_url`（`<base>/chatwoot/webhook/<device_id>`）；请将其设为该收件箱的 Webhook。其他路由：`GET /chatwoot/configs`，以及 `GET` 和 `DELETE /devices/{device_id}/chatwoot/config`。

> [!WARNING]
>
> 一旦存在每台设备配置**任何**，`CHATWOOT_*`目标将不再被用作备份。没有配置的设备不会被镜像。

* `api_token` 存储在GOWA的数据库中，并已被读取；`webhook_secret` 永远不会返回。
* `chatwoot_url` 必须是 HTTP 或 HTTPS 无凭据。没有 `CHATWOOT_ALLOWED_HOSTS` 、私有、循环、链接本地和元数据地址被拒绝。 一个在 `CHATWOOT_ALLOWED_HOSTS` 中的明确匹配主机是受信任的，并且可以在私人网络上针对自己托管的聊天窗口。设置此允许列表仅用于您控制的主机上。
* 在对话链接返回 `409`后，更改 `chatwoot_url`, `account_id` 或 `inbox_id` ；删除并重新创建配置。
* 可以在设备对应之前创建配对。
* 直接数据库导入仅在单个(环境)配置模式下工作。

## 回复和格式

当代理人在Chatwoot 使用 **回复** 时， GOWA 引用原来的 WhatsApp 消息，当它可以在发送设备的本地商店和同一聊天中解决它。 这适用于文本和每个附件，包括音频至文件回退。标题仅保留在第一个附件。

对于入站的 WhatsApp 消息，GOWA 解决了 `in_reply_to_external_id` 使用 `WAID:<id>` 前缀。 对于早先的代理回复，数字`in_reply_to` 会通过同一设备、 对话、 帐户、 收件箱和配置中的持久消息链接解析。 包含多个附件的消息引用了它的第一个文件。如果目标无法解决，则在没有引用的情况下发送回复。

在 Chatwoot 中传入WhatsApp 的回复和反应线程。代理回复Markdown 链接和强调线转换为可读的 WhatsApp 文本。 Lists, line breaks和代码被保留。空签名分隔符被删除。`CHATWOOT_SIGN_MSG` 前缀着代理人的名称。

只发送合格的公开发出代理消息。私人笔记和排除的聊天不会被传送。 GOWA 使用配置的设备和帐户/收件箱身份来路由共享回调。每次回调提供一个明确的路由。

### 调查和代理删除

在 GOWA v9.9.0后的 `main` 上，Chatwoot 镜像投票创建、编辑和添加选项。 要处理单个投票，请在 [WhatsApp webhooks](https://gowa-docs.mintlify.site/zh/concepts/webhooks.md#%E4%B8%93%E8%BE%91%E5%92%8C%E7%BB%93%E6%9E%84%E5%8C%96%E6%B6%88%E6%81%AF) 中订阅 `message` 并读取结构化投票数据。

在这些构建中，设置 `CHATWOOT_REVOKE_ON_DELETE=true` 只将聊天窗口中的删除同步到 WhatsApp 删除必须匹配有效Chatwoot 配置下发出消息的持久链接。 GOWA 撤销了每个链接的 WhatsApp 消息，包括单独发送的附件。通过 `CHATWOOT_FORWARD_DELETES=true`, 从WhatsApp 中删除仍然是私人笔记。 使用 `CHATWOOT_MESSAGE_DELETE=true` 来删除双向链接的消息。

## 导入历史记录

```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"
```

默认值为 `days_limit=3`、`include_media=true` 和 `include_groups=true`。同步会读取 GOWA 的本地聊天存储，并在后台运行。每个设备同一时间只能运行一个同步任务。

在 GOWA v9.9.0后的`main`上，历史同步可以让手机重新上传过期的媒体。手机必须在线且仍然有文件。 如果手机未能在 30 秒内回答，同步跳板将继续重新上传请求，并继续导入消息。 文件不可用的消息在没有附件的情况下导入。

REST 路径不能设置原始的时间戳；导入的消息会得到导入时间。对于自托的Chatwoot, `CHATWOOT_IMPORT_DB_URI` 直接写入和保存到 Chatwoot 的 PostgreSQL

在 GOWA `main` 上使用 `CHATWOOT_REOPEN_CONVERSATION=true` 在 v9.9.0后，历史同步只是在有新消息导入时重新打开已解决的对话。 REST 同步在发布之前重新打开对话，如果重新打开失败，则重试下次同步的聊天。 直接导入的 PostgreSQL 导入在同一交易中重新打开消息写入。 关闭设置后，REST 同步会为新消息创建新的对话，而直接导入则会保持使用已解决的对话。

## 交货和重试

触碰短暂Chatwoot 错误的在线消息 (网络错误) HTTP 429 或 5xxx 队列在本地存储中，然后在后台重试，带有指数后端。 其它4xx错误被记录和丢弃。

## 故障排除

| Symptom | 检查 |
| - | - |
| 代理回复未发送 | `CHATWOOT_DEVICE_ID` 集合并已登录；webhook URL 正确和公开；`DEVICE_NOT_AVAILABLE` 在日志中意味着没有可用的设备。 |
| `/chatwoot/webhook` 的`401` | 秘密不匹配或时钟漂移（见上文）。 |
| Chatwoot 缺少WhatsApp 消息 | 检查`CHATWOOT_ENABLED`、用户令牌、帐户和收件箱ID以及连接到`CHATWOOT_URL`。在更新后的构建中，请检查有效的事件过滤器是否包含`message`。 |
| `CHATWOOT_NOT_CONFIGURED` | 缺少URL、令牌、帐户 ID 或收件箱ID 。 |

用 `APP_DEBUG=true` 运行，寻找以 `Chatwoot:` 和 `Chatwoot Webhook:`开头的日志行。 上游的 [Chatwoot 指南](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/chatwoot.md) 涵盖更深的直接数据库导入和格式化规则。


## Related topics

- [每台设备聊天woot webhook 端点](https://gowa-docs.mintlify.site/zh/api-reference/chatwoot/每台设备聊天woot-webhook-端点.md)
- [MCP 服务器](https://gowa-docs.mintlify.site/zh/integrations/mcp.md)
- [获取聊天列表](https://gowa-docs.mintlify.site/zh/api-reference/chat/获取聊天列表.md)
- [归档或取消归档聊天](https://gowa-docs.mintlify.site/zh/api-reference/chat/归档或取消归档聊天.md)
- [固定或取消置顶聊天](https://gowa-docs.mintlify.site/zh/api-reference/chat/固定或取消置顶聊天.md)


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