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

# API 参考

> GOWA REST API的基本URL、认证、设备选择、请求格式和响应信封。

## 基本网址

```text theme={null}
http://<host>:3000<APP_BASE_PATH>
```

默认值为 `http://localhost:3000`。设置 `APP_BASE_PATH=/gowa` 后，除 `/health` 外，所有路由都会移至 `/gowa` 下。

## 认证

设置`APP_BASIC_AUTH` 时，除`/health`、`/statics/*`、Chatwoot webhook 和 MCP OAuth 端点外，每条路都需要 HTTP Basic Autth。 见 [Authentication](https://gowa-docs.mintlify.site/zh/api-reference/authentication.md)。

## 设备选择

大多数路由都在 WhatsApp 设备上运行。请使用 `X-Device-Id` 标题(栏位 ID 或 JID)，或 `device_id` 查询参数。 当服务器只有一个设备时，你可以省略它；更多则需要它。

| 去除范围 | 未设备范围 |
| - | - |
| `/app/*` (但`/app/info` 和 `/app/metrics`)，`/send/*`, `/message/*`, `/chat/*`, `/chats`, `/user/*`, `/group/*`, `/newsletter/*`, `/call/*` | `/devices*`, `/app/info`, `/app/metrics`, `/health`, `/mcp`, `/chatwoot/*` |

见 [Multi-device](https://gowa-docs.mintlify.site/zh/concepts/multidevice.md)。

## 端点组

| 组别 | 目的 |
| - | - |
| 设备 | 创建、列出、登录、注销和删除设备槽；每台设备的 Web 钩子和Chatwoot 配置。 |
| 应用 | 登录 (QR, 配对代码, 密码), 注销, 重新连接, 状态, 服务器信息和处理, 内存, 磁盘和设备计量。 |
| 发送 | 文本、媒体、联系人、位置、链接、民意测验、展示；排定时间；即时试验交互式发送。 |
| 留言 | React，编辑，撤销，删除，读取，静态，前进，下载媒体。 |
| 聊天 | 列出聊天和消息；pin、归档、正在消失的计时器、历史请求。 |
| 用户 | 个人资料信息，头像，推送名字，隐私，联系人，小组，号码检查。 |
| 组别 | 创建参与者、管理员、加入请求、设置、邀请链接。 |
| 通讯 | 关注、取消关注、频道信息、目录、消息、计数器、实时更新和媒体下载。 |
| 来电 | 拒绝来电。 |

此选项卡中的端点页面来自GOWA 的 OpenAPI 规格。权威性合同是 [`docs/openapi.yaml` ](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/openapi.yaml) 服务器存储库。 此网站使用 `openapi.yml` 的同步副本，包括`/send/interactive`。[交互式指南](https://gowa-docs.mintlify.site/zh/examples/interactive-messages.md) 记录当前限制。

## 请求

* JSON 请求体：`Content-Type: application/json`。
* 文件上传: `multipart/form-data`
* 电话号码：带有国家代码的数字 (`628123456789`) 或完整的 JID (`...@s.whatsapp.net`, `...@g.us`)

## 回应

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": {}
}
```

`code`是`SUCCESS`或一个错误代码；`results` 持有数据。请参阅 [Errors](https://gowa-docs.mintlify.site/zh/api-reference/errors.md)。

## 示例

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

## 联系人姓名

`GET /user/my/contacts` 会返回每个联系人的首选显示名称。在 v9.9.0 之后的 GOWA `main` 分支中，可调用 `GET /user/my/contacts/detailed`，将存储的 `full_name`、`first_name`、`push_name` 和 `business_name` 作为独立字段获取。GOWA 会省略空名称；当设备中存在映射时，电话号码 JID 的结果中还会包含 `lid`。结果包含所选设备的个人联系人，并按 `jid` 排序。

```bash theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  http://localhost:3000/user/my/contacts/detailed
```

## 其他接口

* **[WebSocket](https://gowa-docs.mintlify.site/zh/api-reference/websocket.md)** 在 `/ws` 处用于在线仪表板事件。
* 供 AI 智能体使用的 **MCP**，位于 `/mcp`（[MCP 服务器](https://gowa-docs.mintlify.site/zh/integrations/mcp.md)）。
* **Webhooks** 推送到您的 URLs([Webhooks](https://gowa-docs.mintlify.site/zh/concepts/webhooks.md))。


## Related topics

- [API 认证](https://gowa-docs.mintlify.site/zh/api-reference/authentication.md)
- [错误](https://gowa-docs.mintlify.site/zh/api-reference/errors.md)
- [速率限制](https://gowa-docs.mintlify.site/zh/api-reference/rate-limits.md)
- [转至](https://gowa-docs.mintlify.site/zh/api-reference/sdks/go.md)
- [Python](https://gowa-docs.mintlify.site/zh/api-reference/sdks/python.md)


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