外观
HTTP 接口约定
各平台 SDK 已封装以下接口。常规接入从 SDK 指南开始；本节适合编写宿主换票服务、排查网络请求或实现与现有协议兼容的客户端。
每个接口都有独立页面：先说明用途与调用方，再列请求参数、调用示例、返回字段和使用注意事项。返回对象在当前页面展开，点击对象名称可直接定位。SDK 方法的入参与返回值见各平台方法参考。
先分清调用方
| 接口范围 | 调用方 | 凭证 |
|---|---|---|
POST /app/sdk/token、POST /app/sdk/users/upsert | 宿主后端 | Authorization: Bearer <sdkSecret> |
其余 /app/sdk/* 客户端接口 | SDK | Authorization: Bearer <IM Token> |
/app/auth/* | 随附宿主应用 | PHPSID Cookie，原生端也可用同名请求头 |
POST /app/sdk/trtc/room-callback | TRTC 服务端回调 | 回调签名；同路径 GET 仅检查地址是否可访问，见通话 |
sdkSecret 只保存在宿主后端。IM Token 用于证明当前 IM 用户身份；宿主登录会话和 IM Token 分开管理。使用自有账号系统时，无需实现随附宿主的注册、密码或验证码接口。
请求与返回
示例服务地址统一为 https://example.com。GET 参数放在 query，JSON 写请求使用 Content-Type: application/json，文件接口使用 multipart/form-data。参数表中的“必填”指本次请求必须携带；可空和可省略分别说明。
类型表中，string 是文本，例如 "linzhou"；integer 是整数，例如 30；boolean 是 true 或 false。[] 表示列表，null 表示当前没有这个值。object 的内部字段会在同页继续说明。
成功：
json
{"code":0,"msg":"ok","data":{"message":0,"notice":0}}业务失败：
json
{"code":1103,"msg":"token expired","data":null}先检查网络与 HTTP 状态，再检查 code。业务错误通常返回 HTTP 200；内部故障可返回 500，宿主未登录返回 401，短信限流还可能返回 429。不要仅用 HTTP 200 判断成功。常规 JSON 结果含 Cache-Control: no-store；验证码和 TRTC 回调另有返回格式。
ID、时间与布尔值
user.id是 IM 内部 ID，十进制字符串；user.user_id是宿主提供的外部用户 ID。对外调用用户参数使用user_id。group_id是公开群 ID，1–32 位字母、数字、.、_、-。不要使用数据库群行 ID。mid、conversation_seq、last_seq、read_seq等序号用十进制字符串保留精度。- 业务时间为 Unix 毫秒整数；换票响应的
expire_at为 Unix 秒。时长以字段的_ms或_seconds为准。 - 布尔参数使用 JSON
true/false，不要用字符串或0/1代替。 null有明确语义。共享群事件中的个人未读、置顶、免打扰等可能为null，表示该事件没有这个接收者的私有状态。
conversation_id 应直接使用服务端返回值。单聊格式为 friend_ 加外部 ID 的无填充 Base64URL；例如 linzhou 对应 friend_bGluemhvdQ。群聊格式为 group_ 加公开群 ID。
分页与幂等
目录列表分页返回 items、next_cursor、has_more。有下一页时，把 next_cursor 原样放进下一次请求的 cursor；这个值已包含账号与筛选条件，不能跨账号、跨接口或与新筛选条件混用。不支持自行指定 page、offset、limit。
消息历史用会话序号分页，搜索会话消息用 before_mid，详见各页。写入使用同一 client_message_id 或 request_id 重试时，必须保持原操作内容，不要把同一个 ID 用于另一条消息或另一次业务操作。HTTP 回包和实时事件中的同一 event_id 只处理一次。
常用错误码
| code | 含义 | 建议 |
|---|---|---|
| 1001 | SDK 后端密钥无效 | 核对服务端密钥及 Bearer 请求头 |
| 1002 | SDK 已禁用 | 检查管理后台能力配置 |
| 1003 | 用户停用 | 提示账号状态 |
| 1004 | 参数无效 | 核对字段类型、取值和操作要求 |
| 1005 | 请求过快 | 有界退避，避免循环请求 |
| 1101 / 1102 / 1103 | Token 缺失 / 无效 / 过期 | 通过宿主后端重新获取票据 |
| 1201 | 会话不可访问或不存在 | 更新列表与页面权限 |
| 1202 | 能力关闭 | 依据最新 capabilities 更新入口 |
| 1203 | 禁止发送或内容审核未通过 | 展示服务端 msg |
| 1204 / 1205 | 资料 / 申请不可访问 | 刷新对应页面 |
| 1206 | 已是好友 | 收敛为现有关系 |
| 1207 / 1208 | 消息不存在 / 无撤回权限 | 更新消息状态 |
| 1209 / 1210 / 1211 | 群操作禁止 / 邀请无效 / 关系受限 | 按当前权限更新操作 |
| 1213–1217 | 通话禁用、未找到、无权限、状态或设备冲突 | 见通话 |
| 1218 | 群已禁用 | 展示禁用状态 |
| 1500 | 服务内部或配置故障 | 检查服务日志 |