310 lines
14 KiB
Markdown
310 lines
14 KiB
Markdown
# 通用 IM 业务流程与接口频率限制说明
|
||
|
||
更新时间：2026-05-26
|
||
|
||
## 1. 文档目标
|
||
|
||
本文用于新的 IM 子系统重构设计，目标是在功能保持一致的前提下，将现有 IM 业务抽象成通用流程，便于后续拆分服务、设计数据模型、规划 Kafka 消费链路、控制腾讯云 IM REST API 调用频率。
|
||
|
||
## 2. 总体架构
|
||
|
||
通用 IM 链路由以下组件组成：
|
||
|
||
| 组件 | 职责 |
|
||
| --- | --- |
|
||
| App 客户端 | 用户通过 App 使用腾讯云 IM SDK 发送和接收消息 |
|
||
| 腾讯云 IM | 负责即时消息投递、账号体系、消息格式、离线推送、服务端 REST API、回调触发 |
|
||
| App 后台 | 接收腾讯云 IM 回调，识别需要管理后台处理的消息，并写入 Kafka |
|
||
| Kafka | 解耦 App 后台与管理后台 IM 子系统，承接入站消息、推送消息、异步任务 |
|
||
| IM 子系统 / 管理后台 | 消费 Kafka 消息，维护本地会话、消息、工单、分配、状态流转和客服操作 |
|
||
| 本地数据库 | 作为管理后台 IM 业务的长期数据源，保存消息流水、会话状态、工单状态、操作记录 |
|
||
| Redis / 缓存 | 保存在线状态、分配触发标记、限流计数、幂等键、临时游标 |
|
||
| WebSocket / 站内通知 | 将新消息、分配变化、发送结果、状态变化推送给管理后台前端 |
|
||
|
||
## 3. 总体消息流
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["用户在 App 发送 IM 消息"] --> B["腾讯云 IM SDK 投递消息"]
|
||
B --> C["腾讯云 IM 回调 App 后台"]
|
||
C --> D["App 后台校验回调并识别管理后台相关消息"]
|
||
D --> E["App 后台写入 Kafka"]
|
||
E --> F["IM 子系统消费 Kafka"]
|
||
F --> G["幂等校验与消息解析"]
|
||
G --> H["写入本地消息表"]
|
||
H --> I["更新会话、工单、未读数、最后消息时间"]
|
||
I --> J["触发分配、提醒或状态流转"]
|
||
J --> K["管理后台客服前端展示"]
|
||
```
|
||
|
||
核心原则：
|
||
|
||
1. App 客户端消息先进入腾讯云 IM。
|
||
2. 腾讯云 IM 将消息回调给 App 后台。
|
||
3. App 后台不直接写管理后台业务库，而是将管理后台关心的消息写入 Kafka。
|
||
4. 管理后台 IM 子系统消费 Kafka 后入库，并维护本地会话、工单和客服状态。
|
||
5. 管理后台后续展示、检索、统计、客服处理，应以本地数据库为主数据源。
|
||
|
||
## 4. 核心数据模型
|
||
|
||
新子系统建议至少抽象以下数据对象：
|
||
|
||
| 对象 | 说明 |
|
||
| --- | --- |
|
||
| IM 账号 | 业务用户、品牌账号、客服账号在腾讯云 IM 中的账号映射 |
|
||
| 消息 Message | 本地保存的消息流水，包含方向、发送方、接收方、消息类型、消息体、腾讯消息 ID、业务扩展字段 |
|
||
| 会话 Conversation | 用户与品牌/客服之间的当前会话指针，包含未读数、最后消息时间、当前工单 ID |
|
||
| 工单 Ticket / ChatRecord | 一次客服处理过程，包含状态、负责人、团队、首次响应时间、关闭时间 |
|
||
| 分配记录 Assignment | 自动分配、手动接手、转接、释放、代班等操作记录 |
|
||
| 节点日志 NodeLog | 工单生成、分配、首次回复、转接、未解决、转化中、关闭等关键节点 |
|
||
| 推送任务 PushTask | 运营或策略创建的 IM 推送任务 |
|
||
| 推送记录 PushRecord | 单个用户、单条内容的实际待发送记录和发送结果 |
|
||
|
||
## 5. 入站消息流程
|
||
|
||
### 5.1 用户发送消息
|
||
|
||
1. 用户在 App 中通过腾讯云 IM SDK 发送文本、图片、视频、自定义卡片或其他消息。
|
||
2. 腾讯云 IM 完成消息投递，并根据配置触发服务端回调。
|
||
3. App 后台接收腾讯云 IM 回调，完成签名、来源、事件类型和消息结构校验。
|
||
4. App 后台判断该消息是否需要管理后台处理。
|
||
5. 需要管理后台处理的消息，由 App 后台写入 Kafka。
|
||
6. IM 子系统消费 Kafka，执行幂等校验，解析消息体。
|
||
7. IM 子系统写入本地消息流水，并更新会话和工单状态。
|
||
8. 若消息产生新的待处理工单，则进入分配流程。
|
||
9. 管理后台前端通过列表查询、WebSocket 或站内通知看到新消息。
|
||
|
||
### 5.2 幂等与顺序
|
||
|
||
腾讯云回调、App 后台写 Kafka、Kafka 消费都可能出现重试，因此 IM 子系统必须做幂等处理。
|
||
|
||
建议幂等键优先级：
|
||
|
||
1. 腾讯云 IM 消息唯一标识。
|
||
2. 发送方、接收方、消息随机数、消息序列号、消息时间组合。
|
||
3. App 后台写入 Kafka 时生成的业务事件 ID。
|
||
|
||
同一会话内需要尽量按消息时间和腾讯云消息顺序展示。若存在乱序到达，应允许入库后按消息时间、序列号或腾讯消息 ID 排序展示。
|
||
|
||
## 6. 客服处理流程
|
||
|
||
### 6.1 会话和工单状态
|
||
|
||
通用状态建议如下：
|
||
|
||
| 状态 | 说明 |
|
||
| --- | --- |
|
||
| 待接入 | 用户有新消息，尚未分配或尚未被客服处理 |
|
||
| 服务中 | 客服已接入并正在处理 |
|
||
| 已转接 | 工单被转给其他客服或团队，等待新处理人接手 |
|
||
| 未解决 | 客服标记暂未解决，需要后续跟进 |
|
||
| 转化中 | 进入转化或商机跟进阶段 |
|
||
| 已关闭 | 本次客服处理结束 |
|
||
|
||
状态值可以由新子系统自行定义，但需要保证列表筛选、统计口径、自动关闭、转接和重新打开逻辑一致。
|
||
|
||
### 6.2 自动分配
|
||
|
||
自动分配通常在新消息入库后触发：
|
||
|
||
1. 找到待接入工单。
|
||
2. 根据品牌、站点、团队、语言、业务线等条件确定可服务团队。
|
||
3. 获取在线客服列表。
|
||
4. 按客服接单上限、当前处理数、最近分配时间等规则筛选。
|
||
5. 选择目标客服并更新工单负责人。
|
||
6. 写入分配记录和节点日志。
|
||
7. 通知管理后台前端。
|
||
|
||
建议将分配能力独立成可重试任务，避免 Kafka 入站消费被复杂分配逻辑拖慢。
|
||
|
||
### 6.3 客服打开会话
|
||
|
||
客服打开会话时，系统通常需要：
|
||
|
||
1. 校验客服是否在线、是否有处理权限。
|
||
2. 查询会话和工单详情。
|
||
3. 拉取本地消息列表。
|
||
4. 清理当前客服视角下的未读数。
|
||
5. 必要时将工单从待接入或已转接推进到服务中。
|
||
6. 记录读取、接手或首次处理节点。
|
||
|
||
### 6.4 客服发送消息
|
||
|
||
客服发送消息的通用链路：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["客服在管理后台发送消息"] --> B["IM 子系统校验权限、会话、工单状态"]
|
||
B --> C["组装腾讯云 IM 消息体"]
|
||
C --> D["调用腾讯云 REST API"]
|
||
D --> E{"腾讯云返回结果"}
|
||
E -->|成功| F["写入本地消息流水并更新会话"]
|
||
E -->|失败| G["记录失败原因并进入重试或人工处理"]
|
||
F --> H["通知管理后台前端发送成功"]
|
||
G --> I["通知管理后台前端发送失败"]
|
||
```
|
||
|
||
发送前建议校验：
|
||
|
||
1. 当前客服必须具备客服身份。
|
||
2. 当前客服必须有该会话或工单处理权限。
|
||
3. 工单不能处于已关闭状态，除非业务允许重新打开。
|
||
4. 消息体大小、消息类型、媒体文件大小必须符合业务和腾讯云限制。
|
||
5. 对运营推送和客服消息应区分业务来源，方便统计和风控。
|
||
|
||
### 6.5 转接、释放和自动关闭
|
||
|
||
通用处理规则：
|
||
|
||
1. 手动转接给个人：校验当前处理人权限，更新负责人，记录转接节点。
|
||
2. 手动转接给团队：记录目标团队，等待团队内客服接手或自动分配。
|
||
3. 客服离线释放：如果负责人离线且有未读用户消息，可释放为待分配。
|
||
4. 超时未处理释放：待接入或已转接超过配置时间后，重新进入分配池。
|
||
5. 自动关闭：服务中会话在配置时间内无新用户消息或无新客服动作时，自动关闭。
|
||
|
||
## 7. 运营 IM 推送流程
|
||
|
||
运营推送与客服消息都可能调用腾讯云 IM REST API，但应在业务上区分：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["后台创建推送任务"] --> B["审核或直接进入待发送"]
|
||
B --> C["按标签、站点、产品、用户状态筛选目标人群"]
|
||
C --> D["生成 PushRecord"]
|
||
D --> E["写入 Kafka 推送队列"]
|
||
E --> F["推送消费者限速发送"]
|
||
F --> G["调用 sendmsg 或 batchsendmsg"]
|
||
G --> H["保存腾讯云返回结果"]
|
||
H --> I["汇总任务完成状态"]
|
||
```
|
||
|
||
建议：
|
||
|
||
1. 大批量运营推送优先评估 `batchsendmsg`，减少单发接口压力。
|
||
2. 推送消费者必须按 SDKAppID 和接口维度做限速。
|
||
3. 推送记录需要保存发送状态、错误码、重试次数、腾讯云返回结果。
|
||
4. 发送失败应区分可重试错误和不可重试错误。
|
||
5. 推送消息应写入业务扩展字段，便于后续归因和统计。
|
||
|
||
## 8. 本地存储与历史消息
|
||
|
||
管理后台 IM 子系统建议以本地数据库作为长期主数据源。
|
||
|
||
腾讯云 IM 漫游消息适合用于消息补偿、短期核对或异常排查，不建议作为客服记录、统计报表和审计的唯一长期来源。原因是历史消息存储时长与套餐、增值服务和控制台配置有关，且可能产生额外费用。
|
||
|
||
建议本地保存：
|
||
|
||
1. 入站用户消息。
|
||
2. 客服发送消息。
|
||
3. 系统提示消息。
|
||
4. 运营推送消息及发送结果。
|
||
5. 转接、关闭、分配、未解决、转化等节点日志。
|
||
|
||
## 9. 腾讯云 IM 接口频率限制说明
|
||
|
||
以下为腾讯云官方文档口径，实际限制可能随套餐、数据中心、控制台配置和商务协议变化，最终以腾讯云控制台和合同为准。
|
||
|
||
### 9.1 通用限制
|
||
|
||
| 项目 | 限制 |
|
||
| --- | --- |
|
||
| 单聊、群聊单条消息长度 | 最大 12KB |
|
||
| UserID | 长度不超过 32 字节，不支持特殊字符，建议使用英文字母或数字 |
|
||
| REST API 通用调用频率 | 多数 REST API 默认最高 200 次/秒 |
|
||
| 导入多个账号、删除账号、查询账号 | 默认最高 100 次/秒 |
|
||
| 查询在线状态 | 单次请求最多查询 500 个用户 |
|
||
| 批量发单聊消息 | 单次最多给 500 个用户发送 |
|
||
| 导入多个账号 | 单次最多导入 100 个用户名 |
|
||
| 单个用户好友数 | 默认支持 3000 个好友 |
|
||
| 单个用户黑名单数 | 最多 1000 人 |
|
||
|
||
### 9.2 常用 REST API 频率
|
||
|
||
| 接口 | 默认频率限制 | 叠加包增量 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `v4/openim/sendmsg` 单发单聊消息 | 200 次/秒 | 每个叠加包 +100 次/秒 | 体验版和开发版每日累计发送量限制为 1000 条/天 |
|
||
| `v4/openim/batchsendmsg` 批量发单聊消息 | 200 次/秒，同时 12000 条/分钟 | 每个叠加包 +6000 条/分钟 | 条数按接收方数量计算，一次发给 500 人计 500 条 |
|
||
| `v4/profile/portrait_set` 设置资料 | 200 次/秒 | 每个叠加包 +100 次/秒 | 用于更新头像、昵称等资料 |
|
||
| `v4/profile/portrait_get` 拉取资料 | 200 次/秒 | 每个叠加包 +100 次/秒 | 用于查询资料 |
|
||
| `v4/openim/query_online_status` 查询在线状态 | 200 次/秒 | 每个叠加包 +100 次/秒 | 单次最多查询 500 个用户 |
|
||
| `v4/openim/get_c2c_unread_msg_num` 查询单聊未读数 | 200 次/秒 | 每个叠加包 +100 次/秒 | 如新系统需要同步未读数需注意限频 |
|
||
| `v4/group_open_http_svc/send_group_msg` 群内发普通消息 | 200 次/秒 | 每个叠加包 +100 次/秒 | 单个群发送频率上限为 40 条/秒 |
|
||
| `v4/sns/black_list_get` 拉取黑名单 | 200 次/秒 | 每个叠加包 +100 次/秒 | 关系链相关能力需控制调用频率 |
|
||
|
||
### 9.3 调频收费说明
|
||
|
||
腾讯云 IM 服务端 API 调频属于增值服务。官方公告口径为：
|
||
|
||
| 数据中心 | 服务端 API 调用频率叠加包价格 |
|
||
| --- | --- |
|
||
| 国内数据中心 | 10 元/个/日，日结后付费 |
|
||
| 境外数据中心 | 20 元/个/日，日结后付费 |
|
||
|
||
注意事项：
|
||
|
||
1. 调频对单个 SDKAppID 生效，多个 SDKAppID 需要分别配置。
|
||
2. 每个调频项按当日配置的最高数值计费，次日出账。
|
||
3. 体验版不支持调整服务端 API 调用频率上限。
|
||
4. 如果新子系统存在大规模运营推送，必须提前评估 `sendmsg` 与 `batchsendmsg` 的峰值。
|
||
|
||
## 10. 新子系统设计建议
|
||
|
||
### 10.1 按接口维度做限流
|
||
|
||
建议在 IM 子系统服务端增加统一腾讯云 IM Client，并在 Client 内按以下维度做限流：
|
||
|
||
1. SDKAppID。
|
||
2. API 路径，例如 `openim/sendmsg`、`openim/batchsendmsg`。
|
||
3. 业务来源，例如客服消息、运营推送、系统通知。
|
||
|
||
Kafka 消费者不能只依赖消费并发控制，否则高峰期可能瞬间打满腾讯云 API 限频。
|
||
|
||
### 10.2 单发和批量发送分流
|
||
|
||
建议策略：
|
||
|
||
| 场景 | 推荐接口 |
|
||
| --- | --- |
|
||
| 客服一对一即时回复 | `openim/sendmsg` |
|
||
| 系统给单个用户发送提示 | `openim/sendmsg` |
|
||
| 运营批量推送相同或相似内容 | 优先评估 `openim/batchsendmsg` |
|
||
| 需要强个性化卡片、每人内容不同 | 可用 `sendmsg`，但必须限速 |
|
||
|
||
### 10.3 错误处理和重试
|
||
|
||
建议将发送结果分为：
|
||
|
||
1. 成功：腾讯云返回 `ErrorCode=0` 且业务认为发送完成。
|
||
2. 部分成功：批量发送时部分账号失败，需要保存失败账号列表。
|
||
3. 可重试失败：网络异常、超时、腾讯云内部错误、限频。
|
||
4. 不可重试失败：账号不存在、消息体非法、权限错误、消息包超长。
|
||
|
||
重试建议采用延迟重试，并设置最大重试次数。超过次数后进入失败表或死信队列，供人工排查。
|
||
|
||
### 10.4 回调链路可观测性
|
||
|
||
入站链路建议记录以下指标：
|
||
|
||
1. 腾讯云回调接收量。
|
||
2. App 后台写 Kafka 成功量和失败量。
|
||
3. Kafka 积压量。
|
||
4. IM 子系统消费延迟。
|
||
5. 入库成功量和幂等重复量。
|
||
6. 会话创建量、工单创建量、分配成功量。
|
||
|
||
发送链路建议记录：
|
||
|
||
1. 每个 API 的 QPS。
|
||
2. 限流等待时间。
|
||
3. 腾讯云错误码分布。
|
||
4. 发送成功率。
|
||
5. 可重试失败量和最终失败量。
|
||
|
||
## 11. 参考来源
|
||
|
||
- 腾讯云 IM 使用限制：https://cloud.tencent.com/document/product/269/32429
|
||
- 腾讯云 IM 单发单聊消息：https://cloud.tencent.com/document/product/269/2282
|
||
- 腾讯云 IM 批量发单聊消息：https://cloud.tencent.com/document/product/269/1612
|
||
- 腾讯云 IM 服务端 API 调频收费公告：https://cloud.tencent.com/document/product/269/93324
|
||
|