HTTP 接口约定 | 泡泡 IM 开发文档

各平台 SDK 已封装以下接口。常规接入从 SDK 指南开始；本节适合编写宿主换票服务、排查网络请求或实现与现有协议兼容的客户端。
每个接口都有独立页面：先说明用途与调用方，再列请求参数、调用示例、返回字段和使用注意事项。返回对象在当前页面展开，点击对象名称可直接定位。SDK 方法的入参与返回值见各平台进阶控制。
如果只是把聊天功能接进自己的网站或 App，先看 SDK 快速接入。消息收发、好友和群管理等操作已由 SDK 界面处理；只有自己的后端需要获取 IM 凭证，或有明确的自定义业务需求时，再查相应 HTTP 接口。
sdkSecret 由安装向导生成，只提供给宿主后端；获取与更换方式及五种后端语言示例见 SDK 接入指南。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 的内部字段会在同页继续说明。
先检查网络与 HTTP 状态，再检查 code。业务错误通常返回 HTTP 200；内部故障可返回 500，宿主未登录返回 401，短信限流还可能返回 429。不要仅用 HTTP 200 判断成功。常规 JSON 结果含 Cache-Control: no-store；验证码等二进制资源另有返回格式。
conversation_id 应直接使用服务端返回值。单聊格式为 friend_ 加外部 ID 的无填充 Base64URL；例如 linzhou 对应 friend_bGluemhvdQ。群聊格式为 group_ 加公开群 ID。
目录列表分页返回 items、next_cursor、has_more。有下一页时，把 next_cursor 原样放进下一次请求的 cursor；这个值已包含账号与筛选条件，不能跨账号、跨接口或与新筛选条件混用。不支持自行指定 page、offset、limit。系统通知使用独立的 before_seq / after_seq 范围分页，见读取系统通知。
消息历史用会话序号分页，搜索会话消息用 before_mid，详见各页。写入使用同一 client_message_id 或 request_id 重试时，必须保持原操作内容，不要把同一个 ID 用于另一条消息或另一次业务操作。HTTP 回包和实时事件中的同一 event_id 只处理一次。
SDK 与宿主客户端复用 clientRequestHeaders() 中的 X-Popo-Installation-Id。这是本应用的随机安装标识，不是推送 Token、通话设备 ID 或永久硬件 ID。清理媒体缓存不应删除它；卸载、清除应用数据或浏览器站点存储后可能变化。
发送消息、上传媒体、修改资料、好友申请、群管理和建立通话等受限写操作必须携带有效安装标识（1–128 位 ASCII 字母、数字、.、_、:、-），缺失或格式无效返回 1004。各接口的 Header 表和请求示例已列出该请求头；完整范围以服务端 config/restrictions.php 为准，不按所有 POST 请求统一拦截。
服务端命中账号、设备或 IP 的操作限制时返回 1220，提示「当前操作受限」。已有登录态仍可浏览、同步和接收实时消息，已读、举报、退出及系统通知状态操作仍可用。客户端展示 msg，保留登录状态，不因 1220 循环换票或自动重试；限制到期或被解除后，下一次请求即可恢复。安装标识仅用于操作来源与限制判断，不能代替身份认证；IP 由服务端及可信代理链解析。
账号的「限制操作并禁止登录」只额外拦截新登录（宿主登录接口返回 3005）。已有 Session 可继续换取 SDK Token；有效 Token 的 HTTP 请求和 WebSocket 重连、同步、收消息保持可用，受限写操作统一返回 1220。1003 继续用于账号注销或身份不可用，不用于封禁期间的已有会话。