公众号用户发送广播消息
功能说明
App 管理员可以通过该接口向关注公众号的所有订阅者发送普通消息。
单个公众号的发送频率上限为1条/秒,每小时最多可发布2条广播消息。
如果5分钟内两条消息的内容相同,后面的消息将被当做重复消息而丢弃。
接口调用说明
请求 URL 示例
https://xxxxxx/v4/official_account_open_http_svc/send_official_account_msg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
请求参数说明
参数 | 说明 |
xxxxxx | SDKAppID 所在国家/地区对应的专属域名: 中国: console.tim.qq.com 新加坡: adminapisgp.im.qcloud.com 首尔: adminapikr.im.qcloud.com 法兰克福: adminapiger.im.qcloud.com 硅谷: adminapiusa.im.qcloud.com 雅加达: adminapiidn.im.qcloud.com |
v4/official_account_open_http_svc/send_official_account_msg | 请求接口 |
sdkappid | 创建应用时即时通信 IM 控制台分配的 SDKAppID |
identifier | |
usersig | |
random | 请输入随机的32位无符号整数,取值范围0 - 4294967295 |
contenttype | 请求格式固定值为 json |
最高调用频率
200次/秒。
请求包示例
基础形式
发送普通公众号消息。
{"Official_Account": "@TOA#_2C5SZEAEF","Random": 9875,"MsgBody": [ // 消息体,由一个 element 数组组成,详见字段说明,五分钟包体相同认为是重复消息{"MsgType": "TIMTextElem", // 文本"MsgContent": {"Text": "red packet"}},{"MsgType": "TIMFaceElem", // 表情"MsgContent": {"Index": 6,"Data": "abc\u0000\u0001"}}],"CloudCustomData": "your cloud custom data","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}}}
指定消息不更新最近联系人会话
如果消息中指定 SendMsgControl,设置 NoLastMsg 的情况下,表示不更新最近联系人会话。
{"Official_Account": "@TOA#_2C5SZEAEF","Random": 9875,"SendMsgControl":["NoLastMsg"],//指定消息不触发更新最近联系人会话。"MsgBody": [ // 消息体,由一个 element 数组组成,详见字段说明,五分钟包体相同认为是重复消息{"MsgType": "TIMTextElem", // 文本"MsgContent": {"Text": "red packet"}},{"MsgType": "TIMFaceElem", // 表情"MsgContent": {"Index": 6,"Data": "abc\u0000\u0001"}}]}
指定消息不回调
在回调开关打开的情况下,用户通过 ForbidCallbackControl 控制单条消息是否发起回调,默认情况发起回调。
{"Official_Account": "@TOA#_2C5SZEAEF","Random": 9875,"ForbidCallbackControl":["ForbidBeforeSendMsgCallback","ForbidAfterSendMsgCallback"], // 禁止回调控制选项"MsgBody": [ // 消息体,由一个 element 数组组成,详见字段说明,五分钟包体相同认为是重复消息{"MsgType": "TIMTextElem", // 文本"MsgContent": {"Text": "red packet"}},{"MsgType": "TIMFaceElem", // 表情"MsgContent": {"Index": 6,"Data": "abc\u0000\u0001"}}]}
指定消息不存离线及漫游
如果消息体中指定 OnlineOnlyFlag,只要值大于0,则消息表示只在线下发,不存离线和漫游。
{"Official_Account": "@TOA#_2C5SZEAEF","Random": 9875,"OnlineOnlyFlag": 1, // 表示只在线下发(只有在线订阅者才能收到),不存离线及漫游"MsgBody": [ // 消息体,由一个 element 数组组成,详见字段说明,五分钟包体相同认为是重复消息{"MsgType": "TIMTextElem", // 文本"MsgContent": {"Text": "red packet"}},{"MsgType": "TIMFaceElem", // 表情"MsgContent": {"Index": 6,"Data": "abc\u0000\u0001"}}]}
请求包字段说明
字段 | 类型 | 属性 | 说明 |
Official_Account | String | 必填 | 发送消息的公众号用户。 |
Random | Integer | 必填 | 无符号32位整数(取值范围:0 - 4294967295)。如果5分钟内两条消息的内容和 Random 随机值都相同的情况下,后一条消息将被当做重复消息而丢弃。 |
MsgBody | Array | 必填 | |
OfflinePushInfo | Object | 选填 | |
ForbidCallbackControl | Array | 选填 | 消息回调禁止开关,只对单条消息有效,ForbidBeforeSendMsgCallback 表示禁止发消息前回调,ForbidAfterSendMsgCallback 表示禁止发消息后回调 |
OnlineOnlyFlag | Integer | 选填 | 1表示消息仅发送在线订阅者,默认0表示发送所有订阅者 |
SendMsgControl | Array | 选填 | 消息发送权限,NoLastMsg 只对单条消息有效,表示不更新最近联系人会话(如果该消息 OnlineOnlyFlag 设置为1,则不允许使用该字段。) |
CloudCustomData | String | 选填 | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)。 |
应答包体示例
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"MsgTime": 1497249503,"MsgKey": "89541_1_1572870301"}
应答包字段说明
字段 | 类型 | 说明 |
ActionStatus | String | 请求处理的结果: OK:表示处理成功 FAIL:表示失败 |
ErrorCode | Integer | 错误码: 0:表示成功 非0:表示失败 |
ErrorInfo | String | 错误信息 |
MsgTime | Integer | 消息发送的时间戳,对应后台 server 时间 |
MsgKey | String | 消息唯一标识,用于撤回。长度不超过50个字符 |
错误码说明
除非发生网络错误(例如502错误),否则该接口的 HTTP 返回码均为200。真正的错误码,错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码(60000到79999)参见 错误码 文档。
本 API 私有错误码如下:
错误码 | 含义说明 |
10002 | 服务器内部错误,请重试。 |
10004 | 参数非法,请根据错误描述检查请求是否正确。 |
10007 | 操作权限不足。 |
10010 | 公众号用户不存在,或者曾经存在过,但是目前已经被解散。 |
10015 | 公众号用户 ID 非法,请检查公众号用户 ID 是否填写正确。 |
10016 | App 后台通过第三方回调拒绝本次操作。 |
10017 | 因被禁言而不能发送消息,请检查发送者是否被设置禁言。 |
10023 | 发消息的频率超限,请延长两次发消息时间的间隔。 |
80002 | 消息内容过长,目前最大支持12K字节的消息,请调整消息长度。 |
接口调试工具
参考
消息格式描述
可能触发的回调