跳到主要内容

API 接口列表

本文档列出了即时通讯（IM）服务端提供的 API 接口、调试工具、及注意事项。

提示
  • IM Server API 全部接口均使用 POST 请求方式。
  • 如果您首次接入 IM Server API，强烈推荐先了解 API 调用方法。

API 默认行为与配置​

集成 IM Server API 需要注意以下默认行为：

  1. 应用服务端可调用 IM Server API 直接发送消息。如果以用户身份向群组、聊天室发送消息，不要求已加入群组或聊天室。
  2. 应用服务端调用 IM Server API 的行为不会在北极星的连接信息中生成记录。但通过 Server API 发送的消息均可通过北极星的消息流转查询。
  3. 如果应用配置了敏感词过滤、消息回调服务、第三方审核，请注意调用 Server API 发送的消息默认不进行过滤。如有需要，您需要在控制台免费基础功能页面启用 Server API 发送消息过滤敏感词。
  4. 如果应用启用了全量消息路由，请注意调用 Server API 发送的消息默认不进行路由。如有需要，您需要在控制台免费基础功能页面启用 Server API 发送消息实时路由。
  5. Server API 的部分接口为即时通讯的高级、扩展特性或付费增值提供的接口。需要为开通服务后才能使用。您可以在控制台的免费基础功能页面与 IM 服务管理页面找到大部分服务配置开关，也可以在阅读相关 API 接口文档时找到具体细节。

API 调试工具​

提示

本文档已列出了 API 接口在控制台「北极星」调试地址（需登录开发者账号）。

  • 控制台「北极星」开发者工具箱的 IM Server API 调试 页面提供了大部分 API 接口的调试功能。请注意区分开发环境与生产环境。

用户管理​

提示

IM Server API 的主要功能之一是注册用户 。您需要使用 App 的用户 ID 换取 Token，App 用户才能接入即时通讯服务。

功能/文档页面API URL频率限制北极星 API 调试地址
注册用户/user/getToken.json200 次/每秒，可调频API 调试
作废 Token/user/token/expire.json100 次/每秒，可调频API 调试
获取用户信息/user/info.json100 次/每秒，可调频API 调试
修改用户信息/user/refresh.json100 次/每秒，可调频API 调试
注销用户/user/deactivate.json100 用户/每秒暂不支持
查询已注销用户/user/deactivate/query.json100 次/每秒暂不支持
重新激活用户 ID/user/reactivate.json100 用户/每秒暂不支持
封禁用户/user/block.json100 次/每秒，可调频API 调试
解除用户封禁/user/unblock.json100 次/每秒，可调频API 调试
获取封禁用户列表/user/block/query.json100 次/每秒，可调频API 调试
用户状态/user/checkOnline.json100 次/每秒，可调频API 调试
设置用户单聊禁言/user/chat/fb/set.json100 次/每秒，可调频API 调试
查询单聊禁言用户列表/user/chat/fb/querylist.json100 次/每秒，可调频API 调试
设置用户标签/user/tag/set.json100 次/每秒，可调频API 调试
批量设置用户标签/user/tag/batch/set.json10 次/每秒，可调频API 调试
获取用户标签/user/tags/get.json100 次/每秒，可调频API 调试

用户黑/白名单服务​

功能/文档页面API URL频率限制北极星 API 调试地址
添加用户到黑名单/user/blacklist/add.json100 次/每秒，可调频API 调试
从黑名单中移除用户/user/blacklist/remove.json100 次/每秒，可调频API 调试
获取某用户的黑名单列表/user/blacklist/query.json100 次/每秒，可调频API 调试
为用户开启白名单/user/whitesetting/set.json100 次/每秒API 调试
查询用户白名单服务状态/user/whitesetting/query.json100 次/每秒API 调试
添加用户到白名单/user/whitelist/add.json100 次/每秒，可调频API 调试
从用户白名单中移除用户/user/whitelist/remove.json100 次/每秒，可调频API 调试
获取用户的白名单列表/user/whitelist/query.json100 次/每秒，可调频API 调试

用户信息托管​

功能/文档页面API URL频率限制北极星 API 调试地址
设置用户信息/user/profile/set.json100 次/每秒，可调频暂不支持
清理用户资料/user/profile/clean.json100 次/每秒，可调频暂不支持
批量查询用户资料/user/profile/batch/query.json100 次/每秒，可调频暂不支持
分页获取应用全部用户列表/user/profile/query.json100 次/每秒暂不支持

好友管理（信息托管）​

功能/文档页面API URL频率限制北极星 API 调试地址
添加好友/friend/add.json100 次/每秒，可调频暂不支持
解除好友/friend/delete.json100 次/每秒，可调频暂不支持
清理好友/friend/clean.json100 次/每秒，可调频暂不支持
设置好友自定义属性/friend/profile/set.json100 次/每秒，可调频暂不支持
获取用户好友列表/friend/get.json100 次/每秒，可调频暂不支持
检查好友关系/friend/check.json100 次/每秒，可调频暂不支持
设置添加好友验证等级/friend/permission/set.json100 次/每秒，可调频暂不支持
查询添加好友验证等级/friend/permission/get.json100 次/每秒，可调频暂不支持

消息管理​

功能/文档页面API URL频率限制北极星 API 调试地址
发送单聊普通消息/message/private/publish.json6000 条消息/每分钟，按收件人数量计算条数，可调频API 调试
发送单聊模板消息/message/private/publish_template.json6000 条消息/每分钟，按收件人数量计算条数，可调频API 调试
发送单聊状态消息/statusmessage/private/publish.json6000 条消息/每分钟，按收件人数量计算条数，可调频API 调试
发送群聊消息/message/group/publish.json20 条/每秒，按目标群组数量计算条数，可调频API 调试
发送群聊状态消息/statusmessage/group/publish.json20 条/每秒，按目标群组数量计算条数，可调频API 调试
发送超级群消息/message/ultragroup/publish.json100 条/每秒，按目标群组数量计算条数；单个频道限 20 条/每秒，可调频API 调试
发送聊天室消息/message/chatroom/publish.json100 条/每秒，按目标聊天室数量计算条数，可调频API 调试
发送全体聊天室广播消息/message/chatroom/broadcast.json1 次/每秒，可调频API 调试
设置单群聊消息扩展/message/expansion/set.json100 次/每秒，其中群聊消息扩展最多 20 次，可调频API 调试
删除单群聊消息扩展/message/expansion/delete.json100 次/每秒，其中群聊消息扩展最多 20 次，可调频API 调试
获取单群聊消息扩展/message/expansion/query.json100 次/每秒，可调频API 调试
撤回消息/message/recall.json100 次/每秒，可调频API 调试
获取历史消息日志/message/history.json100 次/每秒API 调试
删除历史消息日志/message/history/delete.json100 次/每秒API 调试
清除消息/conversation/message/history/clean.json100 次/每秒，可调频API 调试

会话管理​

功能/文档页面API URL频率限制北极星 API 调试地址
会话置顶/conversation/top/set.json100 次/每秒暂不支持

系统通知​

提示

下表中频率限制一栏标注「共享」的项目均使用 /push.json 接口，共享该接口频率限额，即 2 次/每小时，3 次/每自然日，可调频。

功能/文档页面API URL频率限制北极星 API 调试地址
发送系统通知普通消息/message/system/publish.json100 条/每秒，按收件人数量计算条数，可调频API 调试
发送系统通知模板消息/message/system/publish_template.json100 条/每秒，按收件人数量计算条数，可调频API 调试
撤回单条系统通知/message/recall.json100 次/每秒API 调试
发送全量用户落地通知/message/broadcast.json2 次/每小时，3 次/每自然日，可调频API 调试
发送在线用户广播/message/online/broadcast.json60 次/每分钟API 调试
发送全量用户不落地通知/push.json2 次/每小时，3 次/每自然日（共享），可调频API 调试
发送标签用户通知/push.json2 次/每小时，3 次/每自然日（共享），可调频API 调试
发送应用包名通知/push.json2 次/每小时，3 次/每自然日（共享），可调频API 调试
撤回全量用户落地通知/message/broadcast/recall.json2 次/每小时，3 次/每自然日暂不支持
发送指定用户不落地通知/push/user.json100 条/每秒，按收件人数量计算条数，可调频API 调试

群组管理​

功能/文档页面API URL频率限制北极星 API 调试地址
创建群组/group/create.json100 次/每秒，可调频API 调试
解散群组/group/dismiss.json100 次/每秒，可调频API 调试
加入群组/group/join.json100 次/每秒，可调频API 调试
退出群组/group/quit.json100 次/每秒，可调频API 调试
查询群组成员/group/user/query.json100 次/每秒，可调频API 调试
同步用户所在群组/group/sync.json100 次/每秒，可调频暂不支持
查询用户所在群组/user/group/query.json100 次/每秒，可调频API 调试
刷新群组信息/group/refresh.json100 次/每秒，可调频API 调试

群组管理（用户信息托管）​

功能/文档页面API URL频率限制北极星 API 调试地址
创建群组/entrust/group/create.json100 次/每秒，可调频暂不支持
设置群组资料/entrust/group/profile/update.json100 次/每秒，可调频暂不支持
批量查询群组资料/entrust/group/profile/query.json100 次/每秒，可调频暂不支持
加入群组/entrust/group/join.json100 次/每秒，可调频暂不支持
导入群组/entrust/group/import.json100 次/每秒，可调频暂不支持
退出群组/entrust/group/quit.json100 次/每秒，可调频暂不支持
踢出群组/entrust/group/member/kick.json100 次/每秒暂不支持
指定用户踢出所有群组/entrust/group/member/kick/all.json100 次/每秒，可调频暂不支持
解散群组/entrust/group/dismiss.json100 次/每秒，可调频暂不支持
转让群组/entrust/group/transfer/owner.json100 次/每秒，可调频暂不支持
设置群管理员/entrust/group/manager/add.json100 次/每秒，可调频暂不支持
移除群管理员/entrust/group/manager/remove.json100 次/每秒，可调频暂不支持
分页获取群成员信息/entrust/group/member/query.json100 次/每秒，可调频暂不支持
获取指定群成员信息/entrust/group/member/specific/query.json100 次/每秒，可调频暂不支持
设置群成员资料/entrust/group/member/set.json100 次/每秒，可调频暂不支持
设置用户指定群特别关注用户/entrust/group/member/follow.json100 次/每秒，可调频暂不支持
删除用户指定群组中的特别关注用户/entrust/group/member/unfollow.json100 次/每秒，可调频暂不支持
查询用户指定群组特别关注成员列表/entrust/group/member/followed/get.json100 次/每秒，可调频暂不支持
设置用户指定群组名称备注名/entrust/group/remarkname/set.json100 次/每秒，可调频暂不支持
删除用户指定群组名称备注名/entrust/group/remarkname/delete.json100 次/每秒，可调频暂不支持
查询用户指定群组名称备注名/entrust/group/remarkname/query.json100 次/每秒，可调频暂不支持
分页查询应用下群组信息/entrust/group/query.json100 次/每秒暂不支持
分页查询用户加入的群组/entrust/joined/group/query.json100 次/每秒暂不支持

群组禁言服务​

功能/文档页面API URL频率限制北极星 API 调试地址
禁言指定群成员/group/user/gag/add.json100 次/每秒，可调频API 调试
取消指定群成员禁言/group/user/gag/rollback.json100 次/每秒，可调频API 调试
查询群成员禁言列表/group/user/gag/list.json100 次/每秒，可调频API 调试
设置群组全体禁言/group/ban/add.json100 次/每秒，可调频API 调试
取消群组全体禁言/group/ban/rollback.json100 次/每秒，可调频API 调试
查询群组全体禁言/group/ban/query.json100 次/每秒，可调频API 调试
加入群组全体禁言白名单/group/user/ban/whitelist/add.json100 次/每秒，可调频API 调试
移出群组全体禁言白名单/group/user/ban/whitelist/rollback.json100 次/每秒，可调频API 调试
查询群组全体禁言白名单/group/user/ban/whitelist/query.json100 次/每秒，可调频API 调试

超级群管理​

功能/文档页面API URL频率限制北极星 API 调试地址
创建超级群/ultragroup/create.json100 次/每秒，可调频API 调试
加入超级群/ultragroup/join.json100 次/每秒，可调频API 调试
退出超级群/ultragroup/quit.json100 次/每秒，可调频API 调试
解散超级群/ultragroup/dis.json100 次/每秒，可调频API 调试
刷新超级群信息/ultragroup/refresh.json100 次/每秒，可调频API 调试
创建频道/ultragroup/channel/create.json100 次/每秒，可调频API 调试
删除频道/ultragroup/channel/del.json100 次/每秒，可调频API 调试
查询频道列表/ultragroup/channel/get.json100 次/每秒，可调频API 调试
获取指定超级群消息内容/ultragroup/msg/get.json5 次/每秒暂不支持
修改超级群消息/ultragroup/msg/modify.json100 次/每分钟暂不支持
搜索超级群消息/ultragroup/hismsg/query.json100 次/每分钟暂不支持
搜索超级群消息上下文/ultragroup/hismsg/msgid/query.json100 次/每分钟暂不支持
设置超级群消息扩展/ultragroup/message/expansion/set.json100 次/每秒，可调频暂不支持
删除超级群消息扩展/ultragroup/message/expansion/delete.json100 次/每秒，可调频暂不支持
获取超级群消息扩展/ultragroup/message/expansion/query.json100 次/每秒，可调频暂不支持
查询用户是否为群成员/ultragroup/member/exist.json100 次/每秒，可调频暂不支持
设置群/频道默认免打扰/ultragroup/notdisturb/set.json100 次/每秒，可调频暂不支持
查询默认免打扰配置/ultragroup/notdisturb/get.json100 次/每秒暂不支持

超级群私有频道​

功能/文档页面API URL频率限制北极星 API 调试地址
变更频道类型/ultragroup/channel/type/change.json100 次/每秒，可调频暂不支持
添加私有频道成员/ultragroup/channel/private/users/add.json100 次/每秒，可调频暂不支持
删除私有频道成员/ultragroup/channel/private/users/del.json100 次/每秒，可调频暂不支持
查询私有频道成员列表/ultragroup/channel/private/users/get.json100 次/每秒，可调频暂不支持
查询用户所属的私有频道/ultragroup/user/channel/query.json100 次/每秒暂不支持

超级群用户组​

功能/文档页面API URL频率限制北极星 API 调试地址
创建用户组/ultragroup/usergroup/add.json100 次/每秒暂不支持
删除用户组/ultragroup/usergroup/del.json100 次/每秒暂不支持
查询用户组列表/ultragroup/usergroup/query.json100 次/每秒暂不支持
添加用户/ultragroup/usergroup/user/add.json100 次/每秒暂不支持
移出用户/ultragroup/usergroup/user/del.json100 次/每秒暂不支持
查询用户所属用户组/ultragroup/user/usergroup/query.json100 次/每秒暂不支持
绑定频道与用户组/ultragroup/channel/usergroup/bind.json100 次/每秒暂不支持
解绑频道与用户组/ultragroup/channel/usergroup/unbind.json100 次/每秒暂不支持
查询频道绑定的用户组/ultragroup/channel/usergroup/query.json100 次/每秒暂不支持
查询用户组绑定的频道/ultragroup/usergroup/channel/query.json100 次/每秒暂不支持

超级群禁言服务​

功能/文档页面API URL频率限制北极星 API 调试地址
禁言指定超级群成员/ultragroup/userbanned/add.json100 次/每秒，可调频API 调试
取消指定超级群成员禁言/ultragroup/userbanned/del.json100 次/每秒，可调频API 调试
查询超级群成员禁言列表/ultragroup/userbanned/get.json100 次/每秒，可调频API 调试
设置超级群全体禁言/ultragroup/globalbanned/set.json100 次/每秒，可调频API 调试
查询超级群全体禁言/ultragroup/globalbanned/get.json100 次/每秒，可调频API 调试
加入超级群全体禁言白名单/ultragroup/banned/whitelist/add.json100 次/每秒，可调频API 调试
移出超级群全体禁言白名单/ultragroup/banned/whitelist/del.json100 次/每秒，可调频API 调试
查询超级群全体禁言白名单/ultragroup/banned/whitelist/get.json100 次/每秒，可调频API 调试

聊天室管理​

功能/文档页面API URL频率限制北极星 API 调试地址
创建聊天室/chatroom/create_new.json100 次/每秒暂不支持
设置聊天室销毁类型/chatroom/destroy/set.json100 次/每秒暂不支持
销毁聊天室/chatroom/destroy.json100 次/每秒，可调频API 调试
查询聊天室信息/chatroom/get.json100 次/每秒暂不支持
绑定音视频房间/chatroom/correlation/rtc.json100 次/每秒API 调试
创建聊天室（已废弃）/chatroom/create.json100 次/每秒，可调频API 调试
查询聊天室信息（已废弃）/chatroom/query.json100 次/每秒，可调频API 调试

聊天室保活服务​

功能/文档页面API URL频率限制北极星 API 调试地址
保活聊天室/chatroom/keepalive/add.json100 次/每秒API 调试
取消保活聊天室/chatroom/keepalive/remove.json100 次/每秒API 调试
查询保活聊天室/chatroom/keepalive/query.json100 次/每秒API 调试

聊天室用户与禁言管理​

功能/文档页面API URL频率限制北极星 API 调试地址
获取聊天室成员/chatroom/user/query.json100 次/每秒，可调频API 调试
查询是否在聊天室中/chatroom/user/exist.json100 次/每秒，可调频API 调试
批量查询是否在聊天室中/chatroom/users/exist.json100 次/每秒，可调频API 调试
禁言指定聊天室用户/chatroom/user/gag/add.json100 次/每秒，可调频API 调试
取消禁言指定聊天室用户/chatroom/user/gag/rollback.json100 次/每秒，可调频API 调试
查询聊天室禁言用户列表/chatroom/user/gag/list.json100 次/每秒，可调频API 调试
设置聊天室全体禁言/chatroom/ban/add.json100 次/每秒，可调频API 调试
取消聊天室全体禁言/chatroom/ban/rollback.json100 次/每秒，可调频API 调试
查询聊天室全体禁言列表/chatroom/ban/query.json100 次/每秒，可调频API 调试
查询聊天室全体禁言状态/chatroom/ban/check.json100 次/每秒，可调频API 调试
加入聊天室全体禁言白名单/chatroom/user/ban/whitelist/add.json100 次/每秒，可调频API 调试
移出聊天室全体禁言白名单/chatroom/user/ban/whitelist/rollback.json100 次/每秒，可调频API 调试
查询聊天室全体禁言白名单/chatroom/user/ban/whitelist/query.json100 次/每秒，可调频API 调试
全局禁言用户/chatroom/user/ban/add.json100 次/每秒，可调频API 调试
取消全局禁言用户/chatroom/user/ban/remove.json100 次/每秒，可调频API 调试
查询全局禁言用户列表/chatroom/user/ban/query.json100 次/每秒，可调频API 调试
封禁聊天室用户/chatroom/user/block/add.json100 次/每秒，可调频API 调试
解除封禁聊天室用户/chatroom/user/block/rollback.json100 次/每秒，可调频API 调试
查询聊天室封禁用户/chatroom/user/block/list.json100 次/每秒，可调频API 调试

聊天室属性（KV）​

提示

下表中频率限制一栏标注「共享」的没有独立的接口频率限额。设置单个聊天室属性与批量设置聊天室属性接口共享 100 个属性每秒的限额。删除单个聊天室属性与批量删除聊天室属性接口共享 100 个属性每秒的限额。

功能/文档页面API URL频率限制北极星 API 调试地址
设置聊天室属性（KV）/chatroom/entry/set.json100 个属性/每秒（共享），可调频API 调试
批量设置聊天室属性（KV）/chatroom/entry/batch/set.json100 个属性/每秒（共享）暂不支持
删除聊天室属性（KV）/chatroom/entry/remove.json100 个属性/每秒（共享），可调频API 调试
批量删除聊天室属性（KV）/chatroom/entry/batch/remove.json100 个属性/每秒（共享）暂不支持
查询聊天室属性（KV）/chatroom/entry/query.json100 次/每秒，可调频API 调试

聊天室消息优先级服务​

功能/文档页面API URL频率限制北极星 API 调试地址
添加低级别消息类型/chatroom/message/priority/add.json100 次/每秒，可调频API 调试
移除低级别消息类型/chatroom/message/priority/remove.json100 次/每秒，可调频API 调试
查询低级别消息类型/chatroom/message/priority/query.json100 次/每秒，可调频API 调试

聊天室白名单服务​

功能/文档页面API URL频率限制北极星 API 调试地址
加入聊天室用户白名单/chatroom/user/whitelist/add.json100 次/每秒，可调频API 调试
移出聊天室用户白名单/chatroom/user/whitelist/remove.json100 次/每秒，可调频API 调试
查询聊天室用户白名单/chatroom/user/whitelist/query.json100 次/每秒，可调频API 调试
加入聊天室消息白名单/chatroom/whitelist/add.json100 次/每秒，可调频API 调试
移出聊天室消息白名单/chatroom/whitelist/delete.json100 次/每秒，可调频API 调试
查询聊天室消息白名单/chatroom/whitelist/query.json100 次/每秒，可调频API 调试

内容审核​

功能/文档页面API URL频率限制北极星 API 调试地址
添加消息敏感词/sensitiveword/add.json100 次/每秒，可调频API 调试
批量添加消息敏感词/sensitiveword/batch/add.json100 次/每秒暂不支持
移除消息敏感词/sensitiveword/delete.json100 次/每秒，可调频API 调试
批量移除消息敏感词/sensitiveword/batch/delete.json100 次/每秒，可调频API 调试
查询消息敏感词/sensitiveword/list.json100 次/每秒，可调频API 调试

推送与通知管理​

功能/文档页面API URL频率限制北极星 API 调试地址
设置指定会话免打扰/conversation/notification/set.json100 次/每秒，可调频API 调试
查询指定会话免打扰/conversation/notification/get.json100 次/每秒API 调试
设置指定会话类型免打扰/conversation/type/notification/set.json100 次/每秒暂不支持
查询指定会话类型免打扰/conversation/type/notification/get.json100 次/每秒暂不支持
设置用户免打扰时段/user/blockPushPeriod/set.json100 次/每秒，可调频暂不支持
删除用户免打扰时段/user/blockPushPeriod/delete.json100 次/每秒，可调频暂不支持
查询用户免打扰时段/user/blockPushPeriod/get.json100 次/每秒，可调频暂不支持
推送 Plus/push/custom.json20 次/每小时，100 次/每自然日API 调试
推送聚合统计/stat/getDayPushData1 次/每秒API 调试
单次推送统计/stat/getPushIdData1 次/每秒API 调试
设置用户级推送备注名/user/remarks/set.json100 次/每秒，可调频暂不支持
删除用户级推送备注名/user/remarks/del.json100 次/每秒，可调频暂不支持
查询用户级推送备注名/user/remarks/get.json100 次/每秒，可调频暂不支持
设置群成员推送备注名/group/remarks/set.json100 次/每秒，可调频暂不支持
删除群成员推送备注名/group/remarks/del.json100 次/每秒，可调频暂不支持
查询群成员推送备注名/group/remarks/get.json100 次/每秒，可调频暂不支持
最后于 更新