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 次/每秒 | 暂不支持 |