接入概述

服务端 REST API（OpenAPI）供你的业务服务端调用，用来管理用户、好友、群组和聊天室，发送和查询消息，上传和管理文件，查询在线状态和通话等。本页说明所有接口共用的约定，阅读具体接口前请先了解。

使用服务端 SDK

Go、Python 和 Node.js 可以直接使用服务端 SDK，它替你管理 App Token、重试、分页和回调校验。

请求地址

所有接口的地址都由三部分组成：

https://{host}/{org_name}/{app_name}/{接口路径}

部分	说明
host	服务的接入域名，开通服务时提供；私有化部署时为你部署的服务地址
org_name	租户的唯一标识，注册时由系统生成，不能修改
app_name	应用名称，创建应用时填写，租户内唯一，不能修改

org_name 和 app_name 用 # 连起来就是应用的 AppKey，例如 1100250925#demo，客户端登录时使用它。

文档中的请求示例使用以下环境变量，复制到终端前先设置好：

export IM_API="https://api.example.com"    # 接入地址，不带末尾的斜杠
export ORG="1100250925"                    # org_name
export APP="demo"                          # app_name
export APP_TOKEN="<App Token>"             # 见《鉴权与 App Token》

请求头

请求头	说明
Authorization	Bearer <App Token>，换取 App Token 的接口除外，见鉴权与 App Token
Content-Type	有请求体时必须为 application/json
X-Request-ID	可选。你为这次请求生成的唯一标识，最长 64 个字符，只能包含字母、数字和 -、_、.；不传时由服务端生成。响应头中总会返回 X-Request-ID，排查问题时请提供它

数据格式

• JSON：请求体和响应体都是 JSON，字段名使用小写加下划线（如 created_at）。请求体必须是一个 JSON 对象，最大 1 MiB。请求中出现接口不认识的字段、字段类型不对，都返回 400 invalid_argument，便于尽早发现拼写错误。
• ID 是字符串：所有 ID（如 message_id、group_id、app_id）都以字符串返回，请求中也传字符串。ID 是 64 位整数，超出 JavaScript 能精确表示的范围，按数字处理会丢失精度。
• 时间：以 UTC 时间的 RFC 3339 格式返回，精确到毫秒，如 2026-09-25T08:30:00.000Z，请按用户所在时区显示。表示时长的字段以秒为单位，字段名以 _seconds 结尾。
• 用户标识：接口中一律用用户名（username）表示用户。用户名不区分大小写，服务端统一转为小写，响应中的用户名都是小写。
• 空值：可选字段没有值时一般返回 null，而不是省略字段；个别响应（如批量操作中每一项的结果）只包含有值的字段，以接口文档为准。
• 缓存：接口的响应都是实时数据，请不要在中间层缓存。

响应与状态码

成功时返回 2xx 状态码：

状态码	含义
200 OK	成功，响应体为结果
201 Created	创建成功，响应体为创建的对象
204 No Content	成功，没有响应体（如删除）

失败时返回 4xx 或 5xx 状态码和统一的错误结构，程序请根据 code 判断错误类型，message 只用于展示和记录：

{
  "error": {
    "code": "not_found",
    "message": "用户不存在",
    "request_id": "QHDK7PQXPV3LFKEFLF37DST5RR"
  }
}

部分错误另带 details 对象说明具体原因。全部错误码见错误码。

分页

列表接口使用游标分页：

参数	位置	说明
limit	查询参数	每页条数，默认 20，取值 1 到 100（个别接口另有说明）
cursor	查询参数	下一页的游标，第一页不传

响应中 items 为本页数据，next_cursor 为下一页的游标，没有下一页时为 null。个别接口（如查询通话列表、查询会话免打扰）没有下一页时返回空字符串 ""，请统一以 next_cursor 为 null 或空字符串判断没有下一页：

{
  "items": [{ "username": "alice" }],
  "next_cursor": "40c8blUXcfK_XCDGHVSvyWRqlgXc27iUTSJmxGuuazqyS9K3..."
}

游标由服务端生成，请原样传回，不要解析或拼接。游标只在同一种查询中有效：改变筛选条件后请从第一页开始。数量有限的列表（如用户的登录设备）不分页，只返回 items。

部分接口按自己的方式翻页（如按消息序号翻页的历史消息），以接口文档为准。

并发修改与 version

可修改的对象带有版本号（如用户的 version、群组的 info_version），每次修改加一。修改时可以在请求中带上读取到的版本号 version：

• 带 version 时，只有版本号一致才会修改，否则返回 409 version_conflict，说明数据已被其他请求修改，请重新读取后再决定是否修改；
• 不带 version 时直接覆盖（个别接口要求必须带，以接口文档为准）。

只修改请求中出现的字段，没有出现的字段保持不变。

批量接口

批量接口（如批量创建用户、批量添加好友、批量发送消息）一次最多处理 100 项（个别接口另有说明）。各项分别处理、互不影响：部分失败时整体仍返回 200 OK，响应中列出每一项的结果，失败的项带错误码和说明。响应的具体格式以各接口的文档为准，例如批量创建用户分别列出成功和失败的项：

{
  "created": [{ "username": "bob", "status": "active" }],
  "failed": [{ "username": "alice", "code": "already_exists", "message": "用户名已被占用" }]
}

批量接口按项数计入调用额度，见限流与应用状态。

重试与幂等

网络超时后，你无法确定上一次请求是否已经成功。重试前请了解接口的幂等性，各接口的文档会写明重复调用的结果，常见规则：

• 创建：用唯一的名称或 ID 防止重复，重复提交返回 409 already_exists，可视为上次已成功；
• 删除：重复删除时，不同接口返回 404 not_found、204 No Content，或 200 OK 且 changed 为 false（如删除好友、移出黑名单），以接口文档为准，都可视为上次已成功；
• 设置状态（如封禁、禁言、加入黑名单）：重复调用的结果相同；
• 发送消息：带上你生成的 client_msg_id，重试时返回第一次写入的消息，不会重复发送，见发送消息。

对 429 rate_limited 请按 Retry-After 响应头等待后重试；对 5xx 和网络错误请用指数退避重试。

接口一览

分类	内容
用户	创建、查询、修改、删除用户，密码与封禁，登录凭证与登录设备，全局禁言
好友与黑名单	好友关系、好友申请、黑名单、加好友方式
群组	群的创建与管理、群成员、群黑名单、入群申请与邀请
消息	发送单聊和群聊消息，查询与导出，撤回、编辑与置顶
会话	会话列表、历史消息、未读数与已读、删除会话
文件	上传消息附件、头像和群文件，换取下载地址，查询和删除文件，群文件列表，存储用量
聊天室	聊天室的创建、查询、修改与解散，聊天室属性，在线成员、禁言、封禁和白名单，发送、查询和撤回聊天室消息
音视频	查询通话、结束通话和移出成员、通话统计
离线推送	用户的推送设置、会话免打扰和推送设备
内容安全	审核配置与词库、审核记录与结论、用户违规与统计、代用户举报
在线状态	查询用户是否在线、在哪些平台在线，最近在线时间
事件回调	回调概述、验证回调请求、事件回调、同步回调

独立 RTC 频道约定

频道服务端管理路径为 /{org_name}/{app_name}/rtc/channels，使用 App Token；客户端加入 / 心跳 / 续凭据 / 退出使用 /client/v1/rtc/… 与 User Token，见频道概述。管理端不能替客户端领取媒体凭据。

channel_id 为业务指定且区分大小写的字符串。session ID 和毫秒累计也必须保留字符串。频道资料、票据、成员及媒体授权响应为 no-store，票据只放 HTTPS JSON 请求体。

创建用固定频道 ID 重放；移出和撤销票据用固定 operation_id；客户端加入用固定 client_session_id。相同键不能换参数或身份复用。票据签发不幂等，不自动重试；响应丢失不代表没有签发。关闭 / 退出返回 202 表示异步清理中。