API 接口列表

更新时间:2024-02-23 PDF

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

提示

IM Server API 当前为 v1 版本，全部接口均使用 POST 请求方式。
如果您首次接入 IM Server API，强烈推荐先了解 API 调用方法。

API 默认行为与配置

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

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

API 调试工具

提示

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

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

用户管理

提示

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

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

用户黑/白名单服务

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

消息管理

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

会话管理

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

系统通知

提示

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

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

群组管理

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

群组禁言服务

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

超级群管理

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

超级群私有频道

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

超级群用户组

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

超级群禁言服务

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

聊天室管理

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

聊天室保活服务

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

聊天室用户与禁言管理

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

聊天室属性（KV）

提示

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

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

聊天室消息优先级服务

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

聊天室白名单服务

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

内容审核

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

推送与通知管理

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

翻译服务

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

文档内容是否对您有帮助？

如果遇到产品相关问题，您可提交工单寻求帮助