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

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

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

# 长期订阅状态同步接口

# 消息参数

# 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>