注意:使用服务端集成 REST API 发送单聊消息时,存在是否将消息同步至发送方(管理员帐号或者由管理员指定的某帐号)问题,同步方式包括在线终端和漫游,REST API 提供 SyncOtherMachine 参数用于说明是否进行同步,详细使用方式参见下文请求包示例。
以下视频将帮助您快速了解单发单聊消息相关功能:
https://console.tim.qq.com/v4/openim/sendmsg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
下表仅列出调用本接口时涉及修改的参数及其说明,更多参数详情请参考 REST API 简介。
参数 | 说明 |
---|---|
v4/openim/sendmsg | 请求接口 |
sdkappid | 创建应用时即时通信 IM 控制台分配的 SDKAppID |
identifier | 必须为 App 管理员帐号,更多详情请参见 App 管理员 |
usersig | App 管理员帐号生成的签名,具体操作请参见 生成 UserSig |
random | 请输入随机的32位无符号整数,取值范围0 - 4294967295 |
200次/秒。
本文以发送文本消息为例,如需发送其他类型的消息,只需将 MsgBody 字段改成相应消息类型即可,更多详情请参见 消息格式描述。
注意:若不希望将消息同步至 From_Account,则 SyncOtherMachine 填写2;若希望将消息同步至 From_Account,则 SyncOtherMachine 填写1。
{
"SyncOtherMachine": 2, // 消息不同步至发送方
"To_Account": "lumotuwe2",
"MsgLifeTime":60, // 消息保存60秒
"MsgRandom": 1287657,
"MsgTimeStamp": 1557387418,
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hi, beauty"
}
}
]
}
注意:若不希望将消息同步至 From_Account,则 SyncOtherMachine 填写2;若希望将消息同步至 From_Account,则 SyncOtherMachine 填写1。
{
"SyncOtherMachine": 2, // 消息不同步至发送方
"To_Account": "lumotuwe2",
"MsgLifeTime":60, // 消息保存60秒
"MsgRandom": 1287657,
"MsgTimeStamp": 1557387418,
"ForbidCallbackControl":[
"ForbidBeforeSendMsgCallback",
"ForbidAfterSendMsgCallback"], // 禁止回调控制选项
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hi, beauty"
}
}
]
}
注意:若不希望将消息同步至 From_Account,则 SyncOtherMachine 填写2。
{
"SyncOtherMachine": 2,
"From_Account": "lumotuwe1",
"To_Account": "lumotuwe2",
"MsgLifeTime":3600, // 消息保存一小时
"MsgRandom": 1287657,
"MsgTimeStamp": 1557387418,
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hi, beauty"
}
}
],
"OfflinePushInfo": {
"PushFlag": 0,
"Desc": "离线推送内容",
"Ext": "这是透传的内容",
"AndroidInfo": {
"Sound": "android.mp3"
},
"ApnsInfo": {
"Sound": "apns.mp3",
"BadgeMode": 1, // 这个字段缺省或者为 0 表示需要计数,为 1 表示本条消息不需要计数,即右上角图标数字不增加
"Title":"apns title", // apns title
"SubTitle":"apns subtitle", // apns subtitle
"Image":"www.image.com" // image url
}
}
}
注意:若希望将消息同步至 From_Account,则 SyncOtherMachine 填写1。
{
"SyncOtherMachine": 1, // 消息同步至发送方
"From_Account": "lumotuwe1",
"To_Account": "lumotuwe2",
"MsgRandom": 1287657,
"MsgTimeStamp": 1557387418,
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hi, beauty"
}
}
]
}
字段 | 类型 | 属性 | 说明 |
---|---|---|---|
SyncOtherMachine | Integer | 选填 | 1:把消息同步到 From_Account 在线终端和漫游上; 2:消息不同步至 From_Account; 若不填写默认情况下会将消息存 From_Account 漫游 |
From_Account | String | 选填 | 消息发送方 UserID(用于指定发送消息方帐号) |
To_Account | String | 必填 | 消息接收方 UserID |
MsgLifeTime | Integer | 选填 | 消息离线保存时长(单位:秒),最长为7天(604800秒) |
MsgRandom | Integer | 必填 | 消息随机数,后台用于同一秒内的消息去重。请确保该字段填的是随机数 |
MsgTimeStamp | Integer | 选填 | 消息时间戳,UNIX 时间戳(单位:秒) |
ForbidCallbackControl | Array | 选填 | 消息回调禁止开关,只对本条消息有效,ForbidBeforeSendMsgCallback 表示禁止发消息前回调,ForbidAfterSendMsgCallback 表示禁止发消息后回调 |
SendMsgControl | Array | 选填 | 消息发送控制选项,只对本条消息有效,"NoUnread"表示该条消息不计入未读数。 |
MsgBody | Object | 必填 | 消息内容,具体格式请参考 消息格式描述(注意,一条消息可包括多种消息元素,MsgBody 为 Array 类型) |
MsgType | String | 必填 | TIM 消息对象类型,目前支持的消息对象包括:TIMTextElem(文本消息),TIMFaceElem(表情消息),TIMLocationElem(位置消息),TIMCustomElem(自定义消息) |
MsgContent | Object | 必填 | 对于每种 MsgType 用不同的 MsgContent 格式,具体可参考 消息格式描述 |
OfflinePushInfo | Object | 选填 | 离线推送信息配置,具体可参考 消息格式描述 |
正常应答
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0,
"MsgTime": 1572870301,
"MsgKey": "89541_2574206_1572870301"
}
异常应答
{
"ActionStatus": "FAIL",
"ErrorInfo": "Fail to Parse json data of body, Please check it",
"ErrorCode": 90001
}
字段 | 类型 | 说明 |
---|---|---|
ActionStatus | String | 请求处理的结果,OK 表示处理成功,FAIL 表示失败 |
ErrorCode | Integer | 错误码,0表示成功,非0表示失败 |
ErrorInfo | String | 错误信息 |
MsgTime | Integer | 消息时间戳,UNIX 时间戳 |
MsgKey | String | 消息唯一标识,用于撤回。长度不超过50个字符 |
除非发生网络错误(例如502错误),否则该接口的 HTTP 返回码均为200。真正的错误码,错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码(60000到79999)参见 错误码 文档。
本 API 私有错误码如下:
错误码 | 描述 |
---|---|
20001 | 请求包非法 |
20002 | UserSig 或 A2 失效 |
20003 | 消息发送方或接收方 UserID 无效或不存在,请检查 UserID 是否已导入即时通信 IM |
20004 | 网络异常,请重试 |
20005 | 服务器内部错误,请重试 |
20006 | 触发发送单聊消息之前回调,App 后台返回禁止下发该消息 |
90001 | JSON 格式解析失败,请检查请求包是否符合 JSON 规范 |
90002 | JSON 格式请求包中 MsgBody 不符合消息格式描述,或者 MsgBody 不是 Array 类型,请参考 TIMMsgElement 对象 的定义 |
90003 | JSON 格式请求包体中缺少 To_Account 字段或者 To_Account 字段不是 String 类型 |
90005 | JSON 格式请求包体中缺少 MsgRandom 字段或者 MsgRandom 字段不是 Integer 类型 |
90006 | JSON 格式请求包体中 MsgTimeStamp 字段不是 Integer 类型 |
90007 | JSON 格式请求包体中 MsgBody 类型不是 Array 类型,请将其修改为 Array 类型 |
90009 | 请求需要 App 管理员权限 |
90010 | JSON 格式请求包不符合消息格式描述,请参考 TIMMsgElement 对象 的定义 |
90012 | To_Account 没有注册或不存在,请确认 To_Account 是否导入即时通信 IM 或者是否拼写错误 |
90026 | 消息离线存储时间错误(最多不能超过7天) |
90031 | JSON 格式请求包体中 SyncOtherMachine 字段不是 Integer 类型 |
90044 | JSON 格式请求包体中 MsgLifeTime 字段不是 Integer 类型 |
91000 | 服务内部错误,请重试 |
90992 | 服务内部错误,请重试;如果所有请求都返回该错误码,且 App 配置了第三方回调,请检查 App 服务器是否正常向即时通信 IM 后台服务器返回回调结果 |
93000 | JSON 数据包超长,消息包体请不要超过 8k |
90048 | 请求的用户帐号不存在 |
通过 REST API 在线调试工具 调试本接口。
批量发单聊消息(v4/openim/batchsendmsg)
查询单聊消息(v4/openim/admin_getroammsg)
撤回单聊消息(v4/openim/admin_msgwithdraw)
云服务器 可用的镜像类型有哪几个? 云服务器 镜像是一种用于业务连续性,灾难恢...
用户可在充值页面自助设置余额阈值,系统会在用户购买支付时进行余额扣费检查,...
阿里云OSS提供分片上传功能,可以将待上传的文件分成多个碎片(Part)分别上传,...
HTTPS监听器支持配置多个证书,您可以通过开启SNI配置单个HTTPS监听器绑定多个证...
Kafka不支持减少分区数,您可以通过删除原先的Topic,然后创建新Topic,重新设置...
相信有很多朋友曾经都遇到过自己的Web服务器受CC攻击,其实防治CC攻击Web服务器...
用途 用于事件驱动的自动化场景。当包含事件触发器的模版创建执行后,该执行初始...
为什么要优化 Ngin HTTPS 延迟 Nginx 常作为最常见的服务器,常被用作负载均衡 (...
2021阿里巴巴大数据技术公开课第一季将在7月21日开讲 本季直播将带领大数据开发...
邬贺铨院士于2020年10月15日在“IMT-2020(5G)大会—5G 创新发展高峰论坛”上的主...