推广员消息管理接口 | 微信开放文档

# 推广员消息管理接口

# 一、触达推广员

商家可以调用接口向已绑定的推广员定向下发模板消息，用于及时进行激励提醒和业务相关的通知。

# 1.群发消息

# 接口说明

本接口仅适用于向已绑定的推广员群发消息（单次发送人数>=50），群发人数小于 50 的情况请使用单发消息能力。注：群发消息后可通过「第二节」接口查询消息送达结果、通过「第三节」接口查询消息的点击效果。

# 请求地址

POST https://api.weixin.qq.com/promoter/sendmsg?access_token=ACCESS_TOKEN

# 请求参数

参数	类型	是否必填	说明
msg_type	uint3	是	消息类型，枚举值参考小程序推广员消息模板汇总
content	string	是	消息内容，为json格式的字符串，不同类型对应的字符串示例见模板列表
appid	string	否	消息体跳转appid（需与调用接口的appid在同OPEN账号下），不填默认为调起接口的appid
path	string	是	消息体跳转path，确保path无误，否则会报页面不存在
list_type	uint32	否	1：发送给所填role_id下的所有推广员，2：发送给所填retail_id下的所有推广员，3：发送给所填id对应的推广员，0或不填则发送给全部推广员。请保证所填参数的正确性，错误的参数不会发送
role_id	uint32数组	否	list_type为1时必填，取值可以参考查询推广员身份api返回的结果
retail_id	string数组	否	list_type为2时必填，取值可以参考查询推广员身份api返回的结果
id	string数组	否	list_type为3时必填，取值可以参考查询推广员身份api返回的结果

# 请求示例

// list_type不传
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折，两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx"
}

// list_type为1
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折，两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "list_type" : 1,
  "role_id" : [ 1, 2 ]
}

// list_type为2
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折，两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "list_type" : 2,
  "retail_id" : [ "xxxxx", "xxxxx" ]
}

// list_type为3
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折，两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "list_type" : 3,
  "id" : [ "1", "2" ]
}

# 返回值

属性	类型	说明
errcode	int32	错误码
errmsg	string	错误信息
msg_id	string	消息 id

# 返回数据示例

{
  "msg_id": "123456",
  "errcode": 0,
  "errmsg": "OK"
}

注：消息参数类型限制

first：10个以内字符（数字/字母/符号/汉字），仅支持一次换行
thing：20个以内字符（数字/字母/符号/汉字）
time：24小时制时间格式（支持+年月日），支持时间段，两个时间点之间用“~”符号连接
amount：一个币种符号+10位以内纯数字，可带小数，结尾可带“元”
number：32位以内数字

# 2.单发消息

本接口适用于向单个已绑定的推广员发送消息，发送后实时返回送达结果。注：单发消息无需通过「第二节」接口查询送达结果；无法通过「第三节」接口查询单发消息的点击情况，只能查到消息类型维度（dimonsion=1）的整体点击情况。

# 请求地址

POST https://api.weixin.qq.com/promoter/singlesendmsg?access_token=ACCESS_TOKEN

# 请求参数

参数	类型	是否必填	说明
msg_type	uint3	是	消息类型，枚举值参考小程序推广员消息模板汇总
content	string	是	消息内容，为json格式的字符串，不同类型对应的字符串示例见模板列表
appid	string	否	消息体跳转appid（需与调用接口的appid在同OPEN账号下），不填默认为调起接口的appid
path	string	是	消息体跳转path，确保path无误，否则会报页面不存在
openid	string	否	推广员openid或unionid

# 请求示例

{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折，两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "id" : "1"
}
或
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折，两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "openid" : "xxxxxxxxxxxx"
}

# 返回值

属性	类型	说明
errcode	int32	错误码
errmsg	string	错误信息

# 返回数据示例

{
  "errcode": 0,
  "errmsg": "OK"
}

# 二、查询送达结果

# 接口说明

商家向推广员群发消息（发送推广员数>=50）后，可通过接口查询消息的送达情况，从而优化消息的送达率。注1：由于消息异步下发，建议发送消息后等待几分钟后（percent字段的值为100）再调本接口查询。注2：消息送达结果的查询有效期为7天，需在消息发送后7天内查询。

# 请求地址

POST https://api.weixin.qq.com/promoter/getmsg?access_token=ACCESS_TOKEN

# 请求参数

参数	类型	是否必填	说明
msg_id	string	是	消息id，发送模板消息接口返回的值

# 请求示例

{
  "msg_type" : 1
}

# 返回值

属性	类型	说明
send_cnt	uint32	发送总数
percent	uint32	当前已发送比例
fail_cnt	uint32	失败总数，在全部发送完后更新，发送进度参考percent
fail_info	数组	包含推广员唯一id和失败错误码，失败数量超过一千会生成文件，不会返回明细
fail_info_url	string	fail_info文件url
msg_type	uint32	消息类型，枚举值参考小程序推广员消息模板汇总
content	string	消息内容，为json格式的字符串，不同类型对应的字符串示例见模板列表
appid	string	消息体跳转appid，不填默认为调起接口的appid
path	string	消息体跳转path
list_type	uint32	下发类型（0：全量下发，1：按role_id下发，2：按retail_id下发，3：按推广员id下发）
role_id	uint32数组	list_type为1有值
retail_id	string数组	list_type为2有值
id	string数组	list_type为3有值
errcode	int32	错误码
errmsg	string	错误信息

# 返回数据示例

{
  "send_cnt" : 2,
  "fail_cnt" : 1,
  "fail_info" : [
    {
      "id" : "123",
      "errcode" : 103010
    }
  ],
  "fail_info_url" : "https://xxxxxxxxxx",
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折，两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "list_type" : 1,
  "role_id" : [ 1, 2 ],
  "errcode": 0,
  "errmsg": "OK"
}

# 三、分析点击效果

# 接口说明

商家确认消息已送达用户后，次日可通过本接口查询消息的点击情况。注1：本接口仅支持查询群发消息（单次群发人数>=50）和消息类型维度的消息数据；注2：消息点击数据仅滚动 7 天，即消息发出 7 天后，消息点击的数据将保持不变；消息的存储时间为 3 个月，即消息发出 90 天后，将不可通过本接口查到消息的点击数据。

# 请求地址

POST https://api.weixin.qq.com/promoter/getmsgclickdata?access_token=ACCESS_TOKEN

# 请求参数

参数	类型	是否必填	说明
send_date	string	是	消息发送日期，格式为yyyy-MM-dd
dimonsion	uint32	是	消息点击数据统计维度，0：按消息id统计（群发数小于50没有数据），1：按消息类型统计
msg_type	uint3	是	消息类型，枚举值参考小程序推广员消息模板汇总
msg_id	string	否	消息id，发送模板消息接口返回的值（dimonsion为0时生效）
begin_send_time	uint32	否	消息发送开始时间戳，必须属于send_date所在自然日（dimonsion为0时生效）
end_send_time	uint32	否	消息发送结束时间戳，必须属于send_date所在自然日（dimonsion为0时生效）

# 请求示例

{
  "send_date" : "2023-08-04",
  "dimonsion" : 0,
  "msg_type" : 1,
  "begin_send_time" : 1691114400,
  "end_send_time" : 1691128800
}
或
{
  "send_date" : "2023-08-04",
  "dimonsion" : 1,
  "msg_type" : 1
}

# 返回值

属性	类型	说明
click_uv	uint32	消息点击人数
click_pv	uint32	消息点击次数
msg_type	uint32	消息类型，枚举值参考小程序推广员消息模板汇总
msg_id	string	消息id，发送模板消息接口返回的值
send_time	uint32	消息发送时间
errcode	int32	错误码
errmsg	string	错误信息

# 返回数据示例

dimonsion为0时返回：
{
  "data_list" : [
    {
      "msg_id" : "123456",
      "send_time" : 1691114400,
      "click_uv" : 123,
      "click_pv" : 200
    }
  ],
  "errcode": 0,
  "errmsg": "OK"
}

dimonsion为1时返回：
{
  "data_list" : [
    {
      "msg_type" : 1,
      "click_uv" : 123,
      "click_pv" : 200
    }
  ],
  "errcode": 0,
  "errmsg": "OK"
}