# 【小程序直播】长期订阅相关接口

# 一、长期订阅状态同步接口

用户订阅小程序直播后会触发事件通知

# 长期订阅状态同步接口

# 消息参数

# Object

属性 类型 说明
ToUserName string 小程序的原始ID
FromUserName string 发送者的openid
CreateTime number 消息创建时间(整型)
MsgType string 固定 event
Event string 固定 wxalive_follow_notify
room_id number 房间号
user_openid string 订阅者的openid
time number 订阅的时间戳
live_status number 订阅或者取消订阅时直播间状态,取值:101(直播中),102(未开始),103(已结束)
action string 订阅行为

action 的合法值

说明
add_follow 订阅
del_follow 取消订阅

# 消息数据包示例

XML 格式

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>1546924844</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[wxalive_follow_notify]]></Event>
  <FollowNotify>
    <room_id>1</room_id>
    <user_openid>![CDATA[xxx]]</user_openid>
    <time>1546924844</time>
    <live_status>101</live_status>
    <action>![CDATA[add_follow]]</action>
  </FollowNotify>
 </xml>

# 二、长期订阅群发接口

# 1. 获取长期订阅用户

# 接口说明

调用此接口获取长期订阅用户列表

# 调用频率

调用额度:5000次/一天

# 请求方法

POST

# 请求URL

https://api.weixin.qq.com/wxa/business/get_wxa_followers?access_token=

# 请求参数示例: json

{    
    "limit": 200,
    "page_break":0 
}

# 请求参数含义

参数 类型 必填 说明
limit Number 获取长期订阅用户的个数限制,默认200,最大2000
page_break Number 翻页标记,获取第一页时不带,第二页开始需带上上一页返回结果中的page_break

# 正确返回示例

{  
    "followers": [
        {
            "openid": "openid1",
            "subscribe_time": 1606270612,
            "room_status": 101,
            "room_id": 1
        },

        {
            "openid": "openid2",
            "subscribe_time": 1606270612,
            "room_status": 101,
            "room_id": 1
        }
    ],
    "page_break": 1606270612,
    "errcode": 0,
    "errmsg": "ok",
}

# 返回参数含义

参数 说明
followers 长期订阅用户列表
openid 长期订阅用户OpenId
subscribe_time 长期订阅用户订阅时间
room_id 用户订阅时所处房间
room_status 用户订阅时房间状态
page_break 翻页标记,获取下一页时带上该值
errcode 接口返回码,0表示成功,非0则失败
errmsg 接口返回提示信息

# 2. 长期订阅群发接口

# 接口说明

向长期订阅用户群发直播间开始事件

# 调用频率

调用额度:5000次/一天;群发订阅用户个数限制:2000/次

# 请求方法

POST

# 请求URL

https://api.weixin.qq.com/wxa/business/push_message?access_token=

# 请求参数示例:json

{
    "room_id": 1,
    "user_openid":["openid1", "openid2"] 
}

# 请求参数含义

参数 类型 必填 说明
room_id Number 直播开始事件的房间ID
user_openid Array<String> 接收该群发开播事件的订阅用户OpenId列表

# 正确返回示例

{
    "message_id":"message_id",
    "errcode": 0,
    "errmsg": "ok",
}

# 返回参数含义

参数 说明
message_id 此次群发消息的标识ID,用于对应【长期订阅群发结果回调】的message_id
errcode 接口返回码,0表示成功,非0则失败。若errcode=0仅表明触发接口成功,最终群发结果请看【长期订阅群发结果回调】
errmsg 接口返回提示信息

# 3. 长期订阅群发结果回调

# 回调说明

异步返回长期订阅群发最终结果

# 回调URL配置

【mp.weixin.qq.com】->【小程序】->【开发】->【开发管理】->【开发设置】->【消息推送】

# 消息参数

# Object

属性 类型 说明
ToUserName String 小程序的原始ID
FromUserName String 发送者的OpenId
CreateTime Number 消息创建时间(整型)
MsgType String 固定 event
Event String 固定 wxalive_push_message_notify
message_id String 群发消息的标识ID
room_id Number 房间号
total_count Number 群发消息user_openid的总数
success_count Number 群发消息成功数量
openid_error_count Number openid错误数量
relation_error_count Number 用户未关注此小程序导致出错数量
user_recv_limit_count Number 用户接收消息超出限制导致出错数量
internal_error_count Number 其他错误数量

# 消息数据包示例

XML 格式

<xml>
   <ToUserName><![CDATA[xxx]]></ToUserName>
   <FromUserName><![CDATA[xxx]]></FromUserName>
   <CreateTime>1606273828</CreateTime>
   <MsgType><![CDATA[event]]></MsgType>
   <Event><![CDATA[wxalive_push_message_notify]]></Event>
   <PushMessageApiNotify>
      <message_id><![CDATA[1622047360795164672]]></message_id>
      <room_id>xxx</room_id>
      <total_count>xxx</total_count>
      <success_count>xxx</success_count>
      <openid_error_count>xxx</openid_error_count>
      <relation_error_count>xxx</relation_error_count>
      <user_recv_limit_count>xxx</user_recv_limit_count>
      <internal_error_count>xxx</internal_error_count>
   </PushMessageApiNotify>
</xml>