• UIKit
  • SDK
  • 服务端 API
Chat/
服务端 API/
RESTful 接口/
服务端 API
  • 生成 UserSig
  • RESTful 接口
    • RESTful 接口概述
    • RESTful 接口列表
    • 消息相关
      • 发送消息
        • 向单个用户发送单聊消息
        • 向多个用户发送单聊消息
        • 群内发送普通消息
        • 群内发送系统消息
        • 直播群广播消息
        • 导入单聊消息
        • 导入群消息
      • 历史消息
        • 修改单聊历史消息
        • 修改群聊历史消息
        • 拉取单聊历史消息
        • 拉取群聊历史消息
      • 删除消息
        • 删除指定用户发送的消息
      • 撤回消息
        • 撤回单聊消息
        • 撤回群消息
      • 已读回执
        • 设置单聊消息已读
        • 拉取群消息已读回执详情
        • 拉取群消息已读回执
      • 消息扩展
        • 拉取单聊消息扩展
        • 设置单聊消息扩展
        • 拉取群消息扩展
        • 设置群消息扩展
      • 推送给所有用户
        • 全员推送接口
        • 推送给所有用户
        • 设置应用属性名称
        • 获取应用属性名称
        • 获取用户属性
        • 设置用户属性
        • 删除用户属性
        • 获取用户标签
        • 添加用户标签
        • 删除用户标签
        • 删除用户所有标签
    • 会话相关
      • 会话列表
        • 拉取会话列表
      • 未读会话数
        • 设置成员的未读消息数
        • 查询未读单聊消息数
      • 删除会话
        • 删除会话
      • 会话组标签
        • 创建会话组数据
        • 更新会话组数据
        • 删除会话组数据
        • 创建或更新会话标记数据
        • 查找会话组标记
        • 拉取会话组标记数据
    • 群相关
      • 群组管理
        • 获取应用内所有群组
        • 创建群组
        • 解散群组
        • 获取用户已加入的群
      • 群资料
        • 获取群资料
        • 修改群资料
        • 导入群资料
      • 群成员管理
        • 添加群成员
        • 删除群成员
        • 封禁群成员
        • 解禁群成员
        • 批量禁言和取消禁言
        • 获取被禁言群成员列表
        • 变更群主
        • 查询用户在群组中的身份
        • 导入群成员
      • 群成员信息
        • 获取群成员资料
        • 修改群成员资料
      • 群自定义属性
        • 获取群自定义属性
        • 修改群自定义属性
        • 清空群自定义属性
        • 重置群自定义属性
        • 删除群自定义属性
      • 直播群管理
        • 获取直播群在线人数
        • 获取直播群在线成员列表
        • 设置直播群成员标记
        • 获取封禁群成员列表
      • 社群管理
        • 创建话题
        • 删除话题
        • 获取话题资料
        • 修改话题资料
        • 导入话题资料
      • 群计数器
        • 获取群计数器
        • 更新群计数器
        • 删除群计数器
    • 用户管理
      • 账号管理
        • 导入单个账号
        • 导入多账号
        • 删除账号
        • 查询账号
      • 用户信息
        • 设置资料
        • 拉取资料
      • 用户状态
        • 账号登录状态失效
        • 查询账号在线状态
      • 好友管理
        • 添加好友
        • 导入好友
        • 更新好友
        • 删除好友
        • 删除所有好友
        • 验证好友
        • 拉取好友
        • 拉取指定好友
      • 好友列表
        • 添加列表
        • 删除列表
        • 拉取列表
      • 黑名单
        • 拉黑用户
        • 将用户移出黑名单
        • 拉取黑名单
        • 验证黑名单中的用户
    • 全员禁言管理
      • 设置全员禁言
      • 查询全员禁言
    • 运维管理
      • 拉取运维数据
      • 下载最新消息
      • 获取服务器 IP 地址
    • 智能机器人
      • 拉取智能机器人账号
      • 创建智能机器人账号
      • 删除智能机器人账号
  • 触发器
    • 回调概述
    • 回调命令列表
    • 运维管理回调
      • 接口超频告警回调
    • 在线状态回调
      • 状态变更回调
    • 关系链回调
      • 更新资料之后
      • 添加好友之前
      • 添加好友回应之前
      • 添加好友之后
      • 删除好友之后
      • 将用户加入黑名单后
      • 将用户移出黑名单后
    • 单聊消息回调
      • 发送单聊消息之前
      • 发送单聊消息之后
      • 设置单聊消息已读之后
      • 撤回单聊消息之后
    • 群回调
      • 创建群组之前
      • 创建群组之后
      • 申请入群之前
      • 拉人入群之前
      • 用户入群之后
      • 成员退群之后
      • 发送群消息之前
      • 发送群消息后
      • 群组满员之后
      • 群组解散之后
      • 群组资料变动之后
      • 撤回群消息之后回调
      • 直播群成员在线和离线状态回调
      • 发送群消息异常回调
      • 创建话题之前
      • 创建话题之后
      • 删除话题后
      • 话题信息变更回调
      • 群成员资料变更后回调
      • 群属性变更后回调
      • 已读回执后回调
      • 群主变更后回调
    • 回调相互认证配置指南
      • Apache 相互认证配置
      • Nginx 相互认证配置
    • 智能机器人回调
      • 智能机器人单聊消息自定义回调

RESTful 接口概述

REST API 是即时通信 IM 提供给 App 后台的 HTTP 管理接口,其主要目的在于为 App 后台提供一个后台管理入口。目前即时通信 IM 支持的 REST API 请参见 REST API 接口列表。 除了 REST API,App 控制台也可实现简单的数据管理、单发/群发消息,开发者可以在控制台进行简单的数据管理、查看及测试。相比之下,REST API 接口较为原始,但管理能力却更为强大。 为了安全性,REST API 仅提供 HTTPS 接口。

前提条件

要调用 REST API,您必须已完成:
1. 在即时通信 IM 控制台创建 App,具体方法参见 应用接入指引
2. 为您的 App 指定管理员帐号,具体方法参见 基础配置 的帐号体系集成。
注意
调用 REST API 时请务必使用 App 管理员帐号,否则会导致不必要的调用错误。

调用方法

请求 URL

REST API 的 URL 格式如下:
https://xxxxxx/$ver/$servicename/$command?sdkappid=$SDKAppID&identifier=$identifier&usersig=$usersig&random=99999999&contenttype=json
其中各个参数的含义以及取值如下(参数名称及其取值均区分大小写):
参数
含义
取值
https
请求协议
请求协议为 HTTPS,请求方式为 POST
xxxxxx
域名。
当域名dns被运营商劫持,可使用备域名。
中国:console.tim.qq.com,备域名 adminapi.my-imcloud.com
新加坡:adminapisgp.im.qcloud.com,备域名 adminapisgp.my-imcloud.com
首尔:adminapikr.im.qcloud.com,备域名 adminapikr.my-imcloud.com
法兰克福:adminapiger.im.qcloud.com,备域名 adminapiger.my-imcloud.com
硅谷:adminapiusa.im.qcloud.com,备域名 adminapiusa.my-imcloud.com
雅加达:adminapiidn.im.qcloud.com,备域名 adminapiidn.my-imcloud.com
ver
协议版本号
固定为v4
servicename
内部服务名,不同的 servicename 对应不同的服务类型
示例:
v4/im_open_login_svc/account_import,其中im_open_login_svcservicename
更多详情请参见 REST API 接口列表
command
命令字,与 servicename 组合用来标识具体的业务功能
示例:
v4/im_open_login_svc/account_import,其中account_importcommand
更多详情请参见 REST API 接口列表
sdkappid
App 在即时通信 IM 控制台获取的应用标识
在申请接入时获得
identifier
用户名,调用 REST API 时必须为 App 管理员帐号
参见 App 管理员
usersig
用户名对应的密码
random
标识当前请求的随机数参数
32位无符号整数随机数,取值范围0 - 4294967295
contenttype
请求格式
固定值为json
注意
App 服务端在调用 REST API 时,identifier 必须为 App 管理员帐号。
App 可以在每次调用 REST API 时都生成管理员帐号的 UserSig,亦可生成一个固定的 UserSig 重复使用,但请特别注意 UserSig 的有效期。

HTTP 请求包体格式

REST API 仅支持 POST 方法,其请求包体为 JSON 格式,具体的包体格式参见每个 API 的详细描述。 需要特别注意的是,POST 包体不能为空,即使某条协议包体中不需要携带任何信息,也需要携带一个空的 JSON 对象,即{}

HTTP 返回码

除非发生网络错误(例如502错误),否则 REST API 的调用结果均为200,真正的 API 调用错误码与错误信息在 HTTP 应答包体中返回。

HTTP 应答包体格式

REST API 的应答包体也是 JSON 格式,其格式符合如下特征:
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0
// REST API 其他应答内容
}
应答包体中必然包含 ActionStatus、ErrorInfo、ErrorCode 这三个属性,其含义如下:
字段
类型
说明
ActionStatus
String
请求处理的结果,OK 表示处理成功,FAIL 表示失败,如果为 FAIL,ErrorInfo 带上失败原因
ErrorInfo
String
失败原因
ErrorCode
Integer
错误码,0为成功,其他为失败,可查询 错误码表 得到具体的原因

调用示例

以下为通过 REST API 来 获取 App 中所有群组 示例。
HTTPS 请求:
POST /v4/group_open_http_svc/get_appid_group_list?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json HTTP/1.1
Host: console.tim.qq.com
Content-Length: 22
{
"Limit": 2
}
HTTPS应答:
HTTP/1.1 200 OK
Server: nginx/1.7.10
Date: Fri, 09 Oct 2015 02:59:55 GMT
Content-Length: 156
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: X-Requested-With
Access-Control-Allow-Methods: POST

{
"ActionStatus": "OK",
"ErrorCode": 0,
"GroupIdList": [
{
"GroupId": "@TGS#1YTTZEAEG"
},
{
"GroupId": "@TGS#1KVTZEAEZ"
}
],
"TotalCount": 58530
}

REST API 公共错误码

错误码
含义说明
60002
HTTP 解析错误 ,请检查 HTTP 请求 URL 格式
60003
HTTP 请求 JSON 解析错误,请检查 JSON 格式
60004
请求 URL 或 JSON 包体中帐号或签名错误
60005
请求 URL 或 JSON 包体中帐号或签名错误
60006
SDKAppID 失效,请核对 SDKAppID 有效性
60007
REST 接口调用频率超过限制,请降低请求频率
60008
服务请求超时或 HTTP 请求格式错误,请检查并重试
60009
请求资源错误,请检查请求 URL
60010
请求需要 App 管理员权限
60011
SDKAppID 请求频率超限,请降低请求频率
60012
REST 接口需要带 SDKAppID,请检查请求 URL 中的 SDKAppID
60013
HTTP 响应包 JSON 解析错误
60014
置换帐号超时
60015
请求包体帐号类型错误,请确认帐号为字符串格式
60016
SDKAppID 被禁用。
60017
请求被禁用。
60018
请求过于频繁,请稍后重试。
60019
请求过于频繁,请稍后重试。
60020
您的套餐包已到期并停用,请登录 即时通信 IM 购买页面 重新购买套餐包。购买后,将在5分钟后生效。
60021
RestAPI 调用来源 IP 非法。

FAQ

REST API 请求有概率超时,收不到任何响应

1. 即时通信 IM 后台 REST 接口设置的超时时间是 3s,调用方设置的超时时间应该长于 3s。
2. telnet console.tim.qq.com 443 确认能否连接服务端口。
3. 使用 curl -I https://console.tim.qq.com 简单测试看状态码是否为200。
4. 确认机器的 dns server 配置是内网 dns server,还是公共 dns server。如果是内网 dns server,请确保 dns server 网络出口和本机器网络出口 IP 所在地域运营商一致。
5. 建议业务调用方使用“长连接+连接池”模式。
说明
由于 HTTPS 短连接建连耗时比较大,每次请求都有TCP + tls 握手开销,所以建议 REST API 长连接接入。 使用标准 HTTP 库的场景:HTTP1.0 需要指定请求头部 Connection: keep-alive,HTTP1.1 默认支持长连接;基于 TCP 封装 HTTPS 请求的场景,可以复用 TCP 连接来收发请求。