发起全员/标签推送
全员/标签推送支持发送特定内容,还可根据标签、属性,针对特定用户群体发送个性化内容,例如会员活动、区域通知等,助力拉新、转化、促活等各个阶段运营工作的有效进行,同时支持推送送达报表,自助推送故障排查工具,具体效果请参见 效果展示。
注意:
1. 账号必须曾经登录过或者手动导入过,才可以接收到全员/标签推送的消息。
2. 全员推送不支持消息修改。
功能说明
支持向全部用户发送推送。
支持按用户属性发送推送。
支持按用户标签发送推送。
管理员推送消息,接收方看到消息发送者是管理员。
管理员指定某一账号向其他账号推送消息,接收方看到发送者不是管理员,而是管理员指定的账号。
支持漫游,漫游存储时长与普通消息的存储时长一致。
由于全员/标签推送需要下发的账号数量巨大,下发完全部账号需要一定时间(根据账号总数而定)。
支持通过 OnlineOnlyFlag 设置为1,则可以只发送推送,不保存会话和漫游以及未读消息。
接口调用说明
请求 URL 示例
https://xxxxxx/v4/timpush/push?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json
请求参数说明
参数 | 说明 |
https | 请求协议:HTTPS 请求方式:POST |
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/timpush/push | 请求接口。 |
usersig | |
identifier | |
sdkappid | 创建应用时,即时通信控制台分配的 SdkAppid。 |
random | 请输入随机的32位无符号整数,取值范围0 - 4294967295。 |
contenttype | 固定值为: json |
调用频率
本接口包含全员、属性、标签推送,默认每天最多调用100次,每两次推送间隔必须大于1s。
注意:
请求包示例
全员推送示例
管理员进行全员推送:
{"From_Account": "admin","MsgRandom": 3674128,"OnlineOnlyFlag": 0, // 0表示存漫游和未读,推送并发限制200人/秒;1表示不存漫游和未读"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0表示进行离线推送,1表示不进行离线推送"Title": "离线推送标题","Desc": "离线推送内容"}}
管理员指定某一账号进行全员推送(示例中发送方账号为 xiaoming):
{"From_Account": "xiaoming","MsgRandom": 3674128,"OnlineOnlyFlag": 0, // 0表示存漫游和未读,推送并发限制200人/秒;1表示不存漫游和未读"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0表示进行离线推送,1表示不进行离线推送"Title": "离线推送标题","Desc": "离线推送内容"}}
注意:
From_Account 为消息推送方账号,支持指定为任意存在的账号。如果未指定发送方或指定的发送方不存在,则默认取接口调用方账号。
只推送在线用户(在线推送):
{"From_Account": "xiaoming","MsgRandom": 3674128,"OnlineOnlyFlag": 1, // 0表示存漫游和未读,推送并发限制200人/秒;1表示不存漫游和未读"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 1 // 0表示进行离线推送,1表示不进行离线推送}}
注意:
OnlineOnlyFlag为1表示只进行推送(在线推送+离线推送),OfflinePushInfo.PushFlag为1表示不进行离线推送。因此上述实例表示只推送在线用户。
按用户标签推送示例
管理员给带有关注“股票A”和“股票B”标签的用户推送消息:
{"From_Account": "admin","MsgRandom": 124032,"OnlineOnlyFlag": 0, // 0表示存漫游和未读,推送并发限制200人/秒;1表示不存漫游和未读"Condition": {"TagsAnd": ["股票A","股票B"]},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0表示进行离线推送,1表示不进行离线推送"Title": "离线推送标题","Desc": "离线推送内容"}}
注意:
From_Account 为消息推送方账号,支持指定为任意存在的账号。如果未指定发送方或指定的发送方不存在,则默认取接口调用方账号。
管理员给关注“股票A”或“股票B”的用户推送消息:
{"From_Account": "admin","MsgRandom": 124032,"OnlineOnlyFlag": 0, // 0表示存漫游和未读,推送并发限制200人/秒;1表示不存漫游和未读"Condition": {"TagsOr": ["股票A","股票B"]},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0表示进行离线推送,1表示不进行离线推送"Title": "离线推送标题","Desc": "离线推送内容"}}
管理员给关注“股票A”或“股票B”,并且没有关注“股票C”和“股票D”的用户推送消息:
{"From_Account": "admin","MsgRandom": 124032,"OnlineOnlyFlag": 0, // 0表示存漫游和未读,推送并发限制200人/秒;1表示不存漫游和未读"Condition": {"TagsAnd": ["股票A","股票B"],"TagsNot": ["股票C","股票D"] // 最终推送范围:("股票A"或"股票B")且非("股票C"且"股票D")},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0表示进行离线推送,1表示不进行离线推送"Title": "离线推送标题","Desc": "离线推送内容"}}
按用户属性推送
管理员给在深圳的超白金会员用户推送消息:
{"From_Account": "admin","MsgRandom": 389475,"OnlineOnlyFlag": 0, // 0表示存漫游和未读,推送并发限制200人/秒;1表示不存漫游和未读"Condition": {"AttrsAnd": {"会员等级": "超白金会员","city": "深圳"}},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0表示进行离线推送,1表示不进行离线推送"Title": "离线推送标题","Desc": "离线推送内容"}}
注意:
From_Account 为消息推送方账号,支持指定为任意存在的账号。如果未指定发送方或指定的发送方不存在,则默认取接口调用方账号。
管理员给深圳用户或者超白金用户推送消息:
{"From_Account": "admin","MsgRandom": 389475,"OnlineOnlyFlag": 0, // 0表示存漫游和未读,推送并发限制200人/秒;1表示不存漫游和未读"Condition": {"AttrsOr": {"会员等级": "超白金用户","city": "深圳"}},"MsgBody": [{"MsgType": "TIMTextElem","MsgContent": {"Text": "hi, beauty"}}],"OfflinePushInfo": {"PushFlag": 0, // 0表示进行离线推送,1表示不进行离线推送"Title": "离线推送标题","Desc": "离线推送内容"}}
请求包字段说明
字段 | 类型 | 属性 | 说明 |
From_Account | String | 选填 | 消息推送方账号(支持指定为任意存在的账号) 如果未指定发送方或指定的发送方不存在,则默认取接口调用方账号。 |
MsgRandom | Integer | 必填 | 32位无符号整数随机数,取值范围0 - 4294967295 后台用于同一秒内的消息去重,请确保是随机数。 |
OnlineOnlyFlag | Integer | 选填 | 默认为 0,表示存漫游和未读,推送并发限制200人/秒。 1 表示不存历史消息且不计未读。 |
Condition | Object | 选填 | |
MsgBody | Array | 必填 | |
MsgType | String | 必填 | TIM 消息对象类型,目前支持的消息对象包括: TIMTextElem(文本消息) TIMLocationElem(位置消息) TIMFaceElem(表情消息) TIMCustomElem(自定义消息) TIMSoundElem(语音消息) TIMImageElem(图像消息) TIMFileElem(文件消息) TIMVideoFileElem(视频消息) |
MsgContent | Object | 必填 | |
OfflinePushInfo | Object | 选填 |
Condition 字段说明
字段 | 类型 | 属性 | 说明 |
TagsOr | String Array | 选填 | 标签条件的并集,数组长度不超过10个。 |
TagsAnd | String Array | 选填 | 标签条件的交集,数组长度不超过10个。 |
TagsNot | String Array | 选填 | 标签条件的非集(多个标签之间,先取多标签的并集,再对该结果取补集),数组长度不超过10个。 推送条件仅有 TagsNot 时, 会先取30天的活跃用户,再用 TagsNot 取反进行推送。 |
AttrsOr | Object | 选填 | 属性条件的并集,数组长度不超过10个。 |
AttrsAnd | Object | 选填 | 属性条件的交集,数组长度不超过10个。 |
说明:建议标签和属性不要混用,推送目标的范围比较容易混乱。不同的标签条件、不同的属性属性条件可以混用。
例如:"Condition" : {"TagAnd" : [ "tag1", "tag2"], "TagOr" : ["tag3", "tag4"], "TagNot" : ["tag5", "tag6"] }
先计算 "TagAnd" 字段的结果 tag1 或 tag2=A ;
再计算 "TagOr" 字段的结果 tag3 且 tag4=B ;
再计算 "TagNot" 字段的结果 非 (tag5 或 tag6)=C ;
"Condition" 的最终结果为 A 且 B 且 C 。
应答包体示例
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"TaskId": "667015d4_537529d8_2000005e80aa873_d03ac87_56f5e750"}
应答包字段说明
字段 | 类型 | 说明 |
ActionStatus | String | 请求处理的结果: OK:表示处理成功 FAIL:表示失败 |
ErrorCode | Integer | 错误码 |
ErrorInfo | String | 错误信息 |
TaskId | String | 推送任务 ID |
错误码说明
除非发生网络错误(例如502错误),否则该接口的 HTTP 返回码均为200。真正的错误码,错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。公共错误码(60000到79999)参见 错误码 文档。
本 API 私有错误码如下:
错误码 | 含义说明 |
90001 | JSON 格式解析失败,请检查请求包是否符合 JSON 规范。 |
90002 | |
90005 | JSON 格式请求包体中缺少 MsgRandom 字段或者 MsgRandom 字段不是 Integer 类型。 |
90007 | JSON 格式请求包体中 MsgBody 类型不是 Array 类型,请将其修改为 Array 类型。 |
90009 | 请求需要 App 管理员权限。 |
90010 | |
90020 | 标签长度超过限制(不能超过50字节)。 |
90022 | 推送条件中的 TagsOr 和 TagsAnd 有重复标签。 |
90024 | 推送过于频繁,每两次推送间隔必须大于1秒。 |
90026 | 消息离线存储时间错误。 |
90032 | 推送条件中的 tag 数量大于10,或添加标签请求中的标签数量大于10。 |
90033 | 属性无效。 |
90039 | 按属性推送和按标签推送不可同时存在。 |
90040 | 推送条件中其中1个 tag 为空。 |
90045 | 未开通全员/标签推送功能。 |
90047 | 推送次数超过当天限额(默认为100次)。 |
90056 | 全员推送的请求体过大,目前支持最大10K长度。 |
91000 | 服务内部错误,请重试。 |
接口调试工具
参考
设置应用属性名称
获取应用属性名称
设置用户属性
删除用户属性
获取用户属性
添加用户标签
获取用户标签
删除用户标签
清空用户标签
推送撤回