wmq
af49d22ca7
Add Telegram, WhatsApp and email account management, realtime messaging, contextual multilingual AI, customer intelligence, knowledge workflows, enterprise controls, a unified design system and complete repository documentation.
82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# API 目录
|
||
|
||
API 统一位于 `/api`，内部渠道回调位于 `/internal/webhooks`。除注册、登录、健康检查和签名 Webhook 外，业务接口均要求 `Authorization: Bearer <token>`。
|
||
|
||
成功响应采用统一数据包装；错误响应包含可展示消息和 HTTP 状态。调用方必须处理 `401`、`403`、`404`、`409`、`429` 和 `5xx`。
|
||
|
||
## 认证与安全
|
||
|
||
- `POST /api/auth/register`、`POST /api/auth/login`
|
||
- `GET /api/auth/me`
|
||
- `POST /api/auth/ws-ticket`：生成短期 WebSocket 票据
|
||
- `POST /api/auth/change-password`
|
||
- `POST /api/auth/logout-all`
|
||
- `GET|POST|DELETE /api/api-keys`
|
||
|
||
## 消息与会话
|
||
|
||
- `GET /api/conversations`
|
||
- `GET /api/conversations/:id`
|
||
- `GET /api/conversations/:id/messages/page`：游标分页
|
||
- `POST /api/conversations/:id/messages`：发送文本/回复
|
||
- `POST /api/conversations/:id/media`
|
||
- `POST /api/conversations/:id/album`
|
||
- `POST /api/conversations/:id/read`
|
||
- `POST /api/conversations/:id/presence`
|
||
- `POST /api/conversations/:id/messages/action`
|
||
- `PATCH /api/conversations/:id/messages/:messageId`
|
||
- `GET /api/conversations/:id/messages/:messageId/attachment`
|
||
- `POST /api/conversations/:id/actions`：归档、静音、清空、删除等会话动作
|
||
|
||
## 渠道
|
||
|
||
- `GET /api/channels`
|
||
- Telegram：`/api/channels/telegram/start` 以及 `phone`、`code`、`password`、`state`
|
||
- WhatsApp：`/api/channels/whatsapp/start`、状态、联系人、代理、设备、资料、指标和备份
|
||
- 邮箱：`POST /api/channels/email/connect`
|
||
- 通用：设为默认、状态、日志、删除和渠道测试
|
||
- 可靠投递：Webhook 投递记录/重放、出站任务/重试
|
||
|
||
## WhatsApp 群组
|
||
|
||
- `GET /api/conversations/:id/whatsapp/group`
|
||
- `POST /api/conversations/:id/whatsapp/group/action`
|
||
|
||
动作由服务端白名单控制，包括成员、管理员、名称、描述和邀请链接管理。
|
||
|
||
## AI
|
||
|
||
- `POST /api/ai/translate`
|
||
- `POST /api/ai/analyze`
|
||
- `POST /api/ai/replies`
|
||
- `POST /api/ai/summarize`
|
||
- `POST /api/ai/text-action`
|
||
- `POST /api/ai/adoptions`
|
||
- `GET|PATCH /api/ai/translations`
|
||
- `GET /api/conversations/:id/ai-status`
|
||
- `POST /api/conversations/:id/messages/:messageId/analyze`
|
||
|
||
AI 接口是业务增强能力。模型超时或限流不应阻断原始消息收发。
|
||
|
||
## 客户经营与管理
|
||
|
||
- 客户：列表、详情、导入、导出、查重、合并和基础 CRUD。
|
||
- 商机、任务等资源：统一 CRUD 路由。
|
||
- 团队：成员、邀请、角色、操作日志和登录记录。
|
||
- 设置、通知、知识库、计费、仪表盘、分析与全局搜索。
|
||
|
||
## Webhook
|
||
|
||
- `POST /internal/webhooks/telegram/:tenantId/:channelId`
|
||
- `POST /internal/webhooks/whatsapp/:tenantId/:channelId`
|
||
|
||
生产调用必须携带对应签名。处理器同时校验 URL 中租户/渠道与数据库归属，事件应携带稳定 ID 以实现幂等。
|
||
|
||
## 健康检查
|
||
|
||
- `GET /health/live`：进程存活。
|
||
- `GET /health/ready`：依赖就绪。
|
||
- Nginx 暴露 `/health` 供容器健康检查。
|
||
|
||
接口的请求/响应类型以 `src/services/`、`src/types/` 和 `server/src/index.js` 为当前实现准则。正式对外开放 API 前，应从路由生成 OpenAPI 3 文档并进行契约测试。
|