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

# 多设备与设备选择

> 在一个 GOWA 服务器上运行几个WhatsApp 帐户，然后选择每个请求使用 X-DeverId 使用哪个账户。

![GOWA Multi设备 Whats App Architecture](https://mintcdn.com/gowa-docs/ccA2Yz4DVI9xOiS8/images/GOWA-Multi-Device-WhatsApp-Architecture.png?fit=max\&auto=format\&n=ccA2Yz4DVI9xOiS8\&q=85\&s=116b948218cb46aa9eca0b959634eaaf)

“多设备”是指GOWA中的两件事：

* **WhatsApp的多设备协议。** GOWA 链接到一个账户作为伴侣设备，例如WhatsApp Web。 手机不需要保持在线状态，每个账户最多允许四个关联的伴侣。
* **每个服务器多个帐户。** 一个 GOWA 进程可以持有许多**设备槽**。 每个栏位配对一个不同的WhatsApp 帐户，或与一个单独的伙伴拥有相同的号码。

## 设备栏位

一个栏位有您选择的 ID (或生成的 UUID)，一个州，一旦配对了账户的 JID。

| 状态 | 含义 |
| - | - |
| `disconnected` | 未连接到WhatsApp。这里开始一个新的或注销的槽位。 |
| `connecting` | 正在连接。 |
| `connected` | Socket 打开，尚未登录 (例如，在等待QR 扫描时)。 |
| `logged_in` | 已配对并准备好发送和接收。 |

### 管理槽位

```bash theme={null}
# Create (device_id is optional)
curl -u admin:changeme -X POST http://localhost:3000/devices \
  -H "Content-Type: application/json" \
  -d '{"device_id": "sales"}'

# List
curl -u admin:changeme http://localhost:3000/devices

# Inspect / live status
curl -u admin:changeme http://localhost:3000/devices/sales
curl -u admin:changeme http://localhost:3000/devices/sales/status

# Pair, log out, reconnect
curl -u admin:changeme http://localhost:3000/devices/sales/login
curl -u admin:changeme -X POST "http://localhost:3000/devices/sales/login/code?phone=628123456789"
curl -u admin:changeme -X POST http://localhost:3000/devices/sales/logout
curl -u admin:changeme -X POST http://localhost:3000/devices/sales/reconnect

# Remove the slot and its session and chat data
curl -u admin:changeme -X DELETE http://localhost:3000/devices/sales
```

`/devices/...` 路由从路径中确定设备，因此始终无需 `X-Device-Id`。设备槽位和会话在重启后仍会保留。

## 选择设备

其他所有针对设备的路由（`/send/*`、`/message/*`、`/chat*`、`/group*`、`/user/*`、`/newsletter/*`、`/call/*` 和 `/app/*`，其中 `/app/info` 和 `/app/metrics` 除外）都需要知道以哪个账户执行操作。GOWA 按以下顺序确定账户：

1. `X-Device-Id`标题 (URL-deced).
2. `device_id`查询参数。
3. 如果两者均未给出，则**确切一个** 槽位存在，这个槽位。

此值可以是栏位ID或账户JID(例如`628123456789@s.whatsapp.net`)。

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: sales" \
  -d '{"phone": "628123456789", "message": "Hi from the sales number"}'

# Equivalent, using the query parameter
curl -u admin:changeme -X POST "http://localhost:3000/send/message?device_id=sales" \
  -H "Content-Type: application/json" \
  -d '{"phone": "628123456789", "message": "Hi from the sales number"}'
```

> [!TIP]
>
> 总是发送 `X-Device-Id` ，即使有一个空档。稍后添加第二个空档，否则每次未知通话都会导致`DEVICE_ID_REQUIRED`失败。

### 选择错误

| HTTP | `code` | 原因 |
| - | - | - |
| 400 | `DEVICE_ID_REQUIRED` | 没有给定设备，零或多个槽位。 |
| 404 | `DEVICE_NOT_FOUND` | 没有匹配给定ID或JID的槽位。 |
| 503 | `DEVICE_MANAGER_UNAVAILABLE` | 服务器尚未完成初始化。 |

一个已存在但未登录通过选择的空档； 请求然后与 WhatsApp 错误失败，例如"您未登录"。

## 每台功能

| 功能 | 它是如何扩大范围 |
| - | - |
| Webhooks | 每个载荷都包含 `device_id`（账号 JID）和 `session_id`（槽位 ID）。每个槽位都可以拥有自己的 webhook：`PATCH /devices/{device_id}/webhook`。参见 [Webhook](https://gowa-docs.mintlify.site/zh/concepts/webhooks.md#%E6%AF%8F%E5%8F%B0%E7%BD%91%E7%BB%9C%E9%92%A9%E5%AD%90)。 |
| WebSocket | 连接到 `/ws?device_id=<id>` 来选择设备上下文. 当前的枢纽广播事件到每个已连接的套接字，因此客户端必须用事件的设备标识符过滤。必须信任浏览器来源。 |
| 预定发送 | 遵循创建它们的栏位；将它们与那个栏位的 `X-Device-Id` 一起列出。 |
| MCP | MCP 连接的 `X-Device-Id` 或每个工具调用的 `device_id` 参数。请参阅[MCP 服务器](https://gowa-docs.mintlify.site/zh/integrations/mcp.md)。 |
| Chatwoot | `CHATWOOT_DEVICE_ID` 用于单个收件箱，或每个设备配置一个收件箱。请参阅 [Chatwoot](https://gowa-docs.mintlify.site/zh/integrations/chatwoot.md)。 |

## 限制和注意事项

* WhatsApp 每个帐户最多允许四个关联的伴侣。每个GOWA配对的位置使用一个。
* WhatsApp 如果手机处于离线约14天，将取消连接伴侣。
* 配对后的历史同步是片面的，并且由 WhatsApp控制。GOWA 存储它在其聊天存储中收到的信息。
* 用户对应的聊天和消息读取使用登录帐户的存储身份。 在查找另一个位置的消息时，不要替换一个位置的设备头。重新配对的位置通过当前客户端接收事件。
* 每个槽位都是完整的 WhatsApp 连接。内存和 CPU 随着槽数和流量的增加而增加。


## Related topics

- [MCP 服务器](https://gowa-docs.mintlify.site/zh/integrations/mcp.md)
- [API 参考](https://gowa-docs.mintlify.site/zh/api-reference/introduction.md)
- [添加新设备](https://gowa-docs.mintlify.site/zh/api-reference/device/添加新设备.md)
- [注销活动设备 (保留设备栏位)](https://gowa-docs.mintlify.site/zh/api-reference/app/注销活动设备-保留设备栏位.md)
- [每台设备聊天woot webhook 端点](https://gowa-docs.mintlify.site/zh/api-reference/chatwoot/每台设备聊天woot-webhook-端点.md)


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