跳到主要内容

API 接口列表

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

提示
  • IM Server API 当前为 v1 版本，全部接口均使用 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 次/每秒暂不支持
获取用户标签/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 调试地址
发送单聊普通消息/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 调试地址
禁言指定群成员/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 次/每秒暂不支持

翻译服务​

功能/文档页面API URL频率限制北极星 API 调试地址
获取 JWT Token/jwt/getToken.json100 次/每秒暂不支持