常见问题
接入与鉴权
App Token 需要每次调用前都换取吗？
不需要。App Token 默认 7 天有效（可在运行策略中修改 app_token_ttl_seconds），请在服务端缓存并复用，到期前再换取新的。频繁换取会占用调用额度，每个 IP 每分钟最多换取 120 次。见鉴权与 App Token。
调用接口返回 401 unauthenticated 怎么办？
App Token 已经过期或失效，重新换取一次后重试即可。如果响应中的 details.reason 为 app_deleted 或 tenant_closed，说明应用已删除或租户已注销，不要再重试。
返回 403 ip_not_allowed 是什么原因？
应用设置了 IP 白名单，而请求的来源 IP 不在其中。请在控制台把业务服务端的出口 IP 加入白名单，见服务端凭据与 IP 白名单。
可以在网页或 App 中直接调用服务端 REST API 吗？
不可以。App Token 拥有整个应用的管理权限，泄露后任何人都能以任意用户的身份发消息。服务端 REST API 不支持浏览器跨域调用，客户端请使用用户自己的 User Token。
返回 429 rate_limited 怎么办？
请求超出了应用的调用额度。请按响应头 Retry-After 给出的秒数等待后重试，并检查是否有不必要的重复调用（如每次都换取 App Token）。业务量确实较大时，请联系我们提高配额，见限流与应用状态。
如何区分测试环境和生产环境？
为两个环境分别创建应用，各自有独立的 AppKey、凭据和数据。测试应用可以开放客户端自注册，方便调试。
用户与登录
我们已经有自己的账号体系，用户如何登录 IM？
推荐的做法：用户注册时，你的服务端调用接口创建一个同名的 IM 用户（不设置密码）；用户需要登录 IM 时，你的服务端在验证了用户身份后为他签发一次性登录凭证，客户端用凭证登录。这样 IM 不保存用户的密码，见登录与登录设备。
用户名有什么要求？可以用手机号吗？
用户名在应用内唯一、不区分大小写，规则见用户管理。建议使用你系统中不会变化的用户 ID，而不是手机号、邮箱等可能变化或属于个人信息的值。
一个用户可以同时在几台设备上登录？
默认最多 4 台，可以在运行策略中调整，并设置超出时是拒绝新登录还是踢掉最早登录的设备。还可以按平台分组（如手机、电脑各一台）分别限制，见多端登录。
消息
不是好友能互相发消息吗？
默认可以。如果你的业务要求只有好友之间才能单聊，在运行策略中开启“单聊要求双方为好友”（friend_check_enabled）。群聊不受影响。
消息会保存多久？
默认保存 90 天，可以在运行策略中修改 message_retention_days（1 到 3650 天）。调小后，超出保留期的消息会被删除且不能恢复。
服务端能撤回任意一条消息吗？
可以。用户自己撤回消息受撤回时限限制（默认 2 分钟），服务端调用撤回接口不受这个限制。见撤回、编辑与置顶。
如何导出聊天记录？
服务端可以按消息 ID 的顺序逐页导出应用内的全部消息（适合增量同步到你自己的存储），也可以按时间段查询某个会话的历史消息或某个用户发出的消息，见查询与导出消息和会话与历史消息。
如何发送图片、语音、视频和文件？
先把文件上传到 IM 服务，得到文件地址，再把地址写进对应类型消息的 body 中发送。上传分三步：创建上传、把内容直接上传到对象存储、完成上传，见上传文件和消息格式。
消息中的图片和文件会保存多久？
附件默认从上传时起保留 30 天，可以在运行策略中修改 attachment_retention_days。到期后文件被删除，消息本身仍然保留，换取下载地址时返回 file_expired。头像在使用期间一直保留；群文件默认在群存在期间一直保留。见文件概述。
拿到文件地址的人都能下载文件吗？
不能。消息中的文件地址本身不能下载，只有本应用登录的用户或你的服务端能用它换取短期有效的下载地址；群文件只有群成员能换取。头像是例外，它的公开地址可以直接访问。
重试发送消息会不会重复？
发送时带上你生成的 client_msg_id：同一发送者在同一会话中用相同的 client_msg_id 重试，返回第一次写入的消息，不会产生重复的消息，见发送消息。
回调
如何把聊天记录同步到自己的系统？
在控制台为应用配置事件回调，订阅消息相关的事件，IM 服务会在消息发出后把它推送到你的服务端；也可以用服务端接口逐页导出消息。见回调概述和事件回调。
能在用户发消息、加好友之前做自己的业务校验吗？
可以。配置同步回调后，IM 服务在用户发消息、加好友、入群等操作之前询问你的服务端，你可以放行、拒绝或改写内容。见同步回调。
如何确认回调请求来自 IM 服务？
每个回调请求都带签名，请按验证回调请求校验签名和时间戳，不通过的请求直接拒绝。
聊天室、音视频与推送
聊天室和群组有什么区别？
群组有固定的成员，成员离线时消息会保存下来，上线后补齐；聊天室没有固定成员，只有正在聊天室中的用户收到消息，不保存离线消息，适合直播间这类人数多、流动快的场景。见聊天室管理。
音视频通话需要另外接入音视频服务吗？
不需要。呼叫、振铃、接听等信令和通话记录都由 IM 服务处理，音视频数据由平台提供的媒体服务承载，开通后即可使用。见音视频通话。
用户收不到离线推送怎么办？
依次检查：控制台中是否配置了对应通道的推送凭据，用户的设备是否登记了推送令牌，用户是否开启了免打扰或会话免打扰，以及控制台推送统计中的失败原因。见离线推送和排查收不到推送。
计费
如何计费？
每个应用订阅一个套餐，按租户每月出一张账单。在控制台可以查看套餐的额度、每日和每月的用量、账单和收款记录。见套餐与账单。
额度用完了或欠费会怎样？
额度用满时，相应的操作被拒绝（例如不能再创建用户），已有的数据和服务不受影响。账单逾期未付时，应用会先变为只读，再被暂停服务，结清后恢复。见套餐与账单和限流与应用状态。
其他
有客户端 SDK 吗？
网页中可以使用 Web SDK（含 React、Vue 绑定），Android、iOS App 可以使用 Flutter SDK；Android、iOS 原生等平台的 SDK 正在开发中，见客户端 SDK。
删除应用后还能恢复吗？
不能。应用删除后，它的全部用户、好友、群组和消息都会被清除，app_name 也不能再次使用。如果只是暂时不想提供服务，请停用应用，停用后可以随时恢复。
如何联系技术支持？
请把出错请求的 X-Request-ID（响应头或错误响应中的 request_id）、请求时间和应用的 AppKey 发送给我们，见关于我们。
独立 RTC 频道
不建群也能多人音视频吗？
可以使用独立频道。服务端指定 channel_id 创建，登录用户按开放规则或一次性票据加入，不产生 IM 群、呼叫邀请或通话记录。
频道 ID 是否就能授权加入？
open 频道还需要本应用登录及准入检查；ticket 频道另需服务端签给该用户的有效票据。知道频道 ID 或媒体房间名不能绕过这些条件。
能同时参与通话和频道吗？
同一应用用户的占用是共享的，同时只能占用一个资源。离开后媒体仍在清理时可能暂时忙线，不应随机换加入键重试。
小程序和 UniApp 都支持频道音视频吗？
UniApp H5 已提供专用入口；UniApp App 原生桥接尚未提供。小程序有频道查询，但无兼容 LiveKit 的媒体适配，channels.supported 为 false。完整状态见平台表。
加入后会自动打开麦克风、系统来电界面或后台服务吗？
默认不采集，用户操作后才启用。频道不自动显示 CallKit / 系统振铃；Android / Flutter 后台持续采集保障仍需专项适配。