# 通用 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

