API 概览
IM PaaS Open API 面向应用服务器（App Server），用于管理用户、好友、消息、群组、超级群、聊天室、会话、回调与推送。当前契约共 230 个接口，全部为 POST，统一以 /im/v2 为路径前缀，使用 App-Key / App-Secret 签名鉴权与统一响应信封。
230
Open API 接口
20
功能模块
43
错误码
22
回调事件
交互流程
客户端不直接调用 Open API：客户端使用服务端签发的 Token 连接 IM Server 长连接；需要服务端权威数据的动作（注册用户、签发 Token、建群、封禁、查询历史等）由你的 App Server 通过 Open API 完成；IM Server 再通过回调把消息与事件推回 App Server。
核心概念
鉴权与签名
App-Key + Nonce + Timestamp + SHA1 签名，±5 分钟窗口与 Nonce 防重放。
域名与环境
私有化部署地址、HTTPS 建议、路径前缀与 X-Request-Id。
数据格式
JSON 请求体、统一响应信封、分页与幂等约定。
状态码
全部错误码、HTTP 状态映射与重试建议。
限频与限制
协议容量、鉴权窗口、分页上限与接口级限制。
服务端回调
投递策略、签名校验、事件结构与投递日志。
服务端 SDK
多语言签名 helper 与请求封装参考实现。
消息类型
26 种内置类型 / 38 个 objectName 的分类、计数、存储与推送策略。
API 接口列表
按模块检索全部 230 个接口。
接口约定
| 项目 | 约定 |
|---|---|
| 请求方法 | 全部接口均为 POST；业务参数放在 JSON 请求体 |
| 路径前缀 | /im/v2；完整地址 = 域名 + 路径前缀 + 接口路径 |
| 鉴权 | 请求头 App-Key / Nonce / Timestamp / Signature（见 鉴权与签名） |
| 请求体 | JSON（UTF-8）；当前实现不支持 application/x-www-form-urlencoded（见 数据格式） |
| 响应信封 | { code, msg?, data?, requestId? }；code = 0 表示成功，非 0 见错误码表 |
| 错误码 | 43 个错误码，HTTP 状态与错误码一一对应（见 状态码） |
| 回调 | 22 个回调事件，至少一次投递、HMAC-SHA256 签名（见 服务端回调） |
| 版本 | IDL v1.0.0；每个接口标注 since 起始版本 |
快速入门
- 创建应用，获取 App-Key / App-Secret
在控制台创建应用；App-Key 用于标识调用方，App-Secret 仅由 App Server 持有，用于生成请求签名。
- 注册用户并签发 Token
调用 注册用户 创建账号，再调用 签发用户 JWT；把 Token 下发给客户端用于连接 IM Server，不要下发 App-Secret。
- 创建群组并发送第一条消息
- 配置回调地址
- 联调与排障
模块
| 模块 | 接口数 | 其中幂等 | 说明 |
|---|---|---|---|
| 用户 | 33 | 6 | 用户模块覆盖账号注册与资料、Token 签发与吊销、在线状态、封禁与注销、私聊白名单/禁言、标签与订阅、推送免打扰以及代聊能力。 |
| 好友关系链 | 8 | 4 | 好友模块提供双向好友关系的建立与删除、好友列表与关系校验、批量清理、添加好友验证等级以及好友备注/扩展属性。 |
| 黑名单 | 3 | 2 | 黑名单模块提供加入、移出与列表查询三个幂等接口；黑名单关系用于阻断被拉黑用户的消息投递。 |
| 消息 | 30 | 2 | 消息模块覆盖单聊/群/聊天室/系统通知发送、撤回、历史与搜索、已读人数、投递轨迹、扩展 KV、消息修改、回应、模板消息、流式消息、广播与翻译。 |
| 群组 | 28 | 8 | 群组模块覆盖群创建与资料、成员增删与退群/解散、管理员与成员禁言、加入策略、全员禁言白名单、批量导入、群成员资料与特别关注、群备注。 |
| 超级群 | 18 | 0 | 超级群模块覆盖加入策略、用户组（创建/删除/成员/按用户查询/绑定频道）以及私有频道（创建/删除/类型/成员/与用户组绑定）。 |
| 聊天室 | 35 | 12 | 聊天室模块覆盖创建与销毁、信息与在线成员、保活与销毁策略、房间 KV、成员禁言/封禁/白名单、全员禁言、消息优先级与 RTC 房间绑定。 |
| 会话 | 20 | 3 | 会话模块提供会话列表、置顶/草稿/提醒级别设置、未读清零以及会话标签的添加、移除与查询。 |
| 在线状态 | 1 | 0 | 在线状态模块当前提供批量查询接口，单次最多查询 100 个用户的在线状态。 |
| 敏感词 | 2 | 0 | 敏感词模块提供敏感词配置查询与全量覆盖设置（词条与处置动作）。 |
| 回调配置与投递 | 4 | 1 | 回调模块提供回调配置查询/设置、投递日志查询与失败投递手动重试；回调事件的投递、签名与事件结构见本页上文的回调体系说明。 |
| 服务开通 | 2 | 1 | 服务开通模块提供应用服务开通项与配额查询、设置；服务关闭后相关接口返回 1021。 |
| 运营统计 | 2 | 0 | 统计模块提供应用维度统计与按天运营趋势（DAU、消息量、在线峰值、错误率）。 |
| AI 助理代理 | 11 | 2 | Agent 模块提供 Agent 配置的增删改查、用户使用限制管理以及对话生成/回复建议（转发到应用配置的 AI 服务端点）。 |
| 机器人 | 8 | 2 | 机器人模块提供机器人账号的创建、查询、列表、更新与删除；运行时对话能力依赖外部模型。 |
| 推送通道 | 7 | 1 | 推送模块提供推送发送、推送日志、按天/按次统计以及推送备注名的设置、查询与删除。 |
| sensitiveword | 4 | 4 | sensitiveword模块，共 4 个接口。 |
| statusmessage | 2 | 0 | statusmessage模块，共 2 个接口。 |
| entrust | 1 | 0 | entrust模块，共 1 个接口。 |
| ultragroup | 11 | 6 | ultragroup模块，共 11 个接口。 |