API 接口列表
本文档列出了即时通讯(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/batch/add.json | 100 次/每秒 | 暂不支持 |
移除消息敏感词 | /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 次/每秒 | 暂不支持 |