一、小程序訂閱消息
小程序訂閱消息 | 微信開放文檔
功能介紹
消息能力是小程序能力中的重要組成,我們?yōu)殚_發(fā)者提供了訂閱消息能力,以便實現(xiàn)服務(wù)的閉環(huán)和更優(yōu)的體驗。
- 訂閱消息推送位置:服務(wù)通知
- 訂閱消息下發(fā)條件:用戶自主訂閱
- 訂閱消息卡片跳轉(zhuǎn)能力:點擊查看詳情可跳轉(zhuǎn)至該小程序的頁面
消息類型
1. 一次性訂閱消息
一次性訂閱消息用于解決用戶使用小程序后,后續(xù)服務(wù)環(huán)節(jié)的通知問題。用戶自主訂閱后,開發(fā)者可不限時間地下發(fā)一條對應(yīng)的服務(wù)消息;每條消息可單獨訂閱或退訂。
2. 長期訂閱消息
一次性訂閱消息可滿足小程序的大部分服務(wù)場景需求,但線下公共服務(wù)領(lǐng)域存在一次性訂閱無法滿足的場景,如航班延誤,需根據(jù)航班實時動態(tài)來多次發(fā)送消息提醒。為便于服務(wù),我們提供了長期性訂閱消息,用戶訂閱一次后,開發(fā)者可長期下發(fā)多條消息。
目前長期性訂閱消息僅向政務(wù)民生、醫(yī)療、交通、金融、教育等線下公共服務(wù)開放,后期將逐步支持到其他線下公共服務(wù)業(yè)務(wù)。
3. 設(shè)備訂閱消息
設(shè)備訂閱消息是一種特殊類型的訂閱消息,它屬于長期訂閱消息類型,且需要完成「設(shè)備接入」才能使用。
設(shè)備訂閱消息用于在設(shè)備觸發(fā)某些需要人工介入的事件時(例如設(shè)備發(fā)生故障、設(shè)備耗材不足等),向用戶發(fā)送消息通知。詳見設(shè)備訂閱消息文檔。
使用說明
步驟一:獲取模板 ID
在微信公眾平臺手動配置獲取模板 ID:
登錄?https://mp.weixin.qq.com?獲取模板,如果沒有合適的模板,可以申請?zhí)砑有履0?,審核通過后可使用。
步驟二:獲取下發(fā)權(quán)限
一次性訂閱消息、長期訂閱消息,詳見接口?wx.requestSubscribeMessage
設(shè)備訂閱消息,詳見接口?wx.requestSubscribeDeviceMessage
步驟三:調(diào)用接口下發(fā)訂閱消息
一次性訂閱消息、長期訂閱消息,詳見服務(wù)端接口?subscribeMessage.send,次數(shù)限制:開通支付能力的小程序下發(fā)上限是3kw/日,沒開通的是1kw/日。
設(shè)備訂閱消息,詳見服務(wù)端接口?hardwareDevice.send
注意事項
- 用戶勾選 “總是保持以上選擇,不再詢問” 之后,下次訂閱調(diào)用 wx.requestSubscribeMessage 不會彈窗,保持之前的選擇,修改選擇需要打開小程序設(shè)置進(jìn)行修改。
訂閱消息事件推送
1、當(dāng)用戶觸發(fā)訂閱消息彈框后,用戶的相關(guān)行為事件結(jié)果會推送至開發(fā)者所配置的服務(wù)器地址或微信云托管服務(wù)。
XML格式示例
<xml>
<ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
<FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
<CreateTime>1610969440</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe_msg_popup_event]]></Event>
<SubscribeMsgPopupEvent>
<List>
<TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
<SubscribeStatusString><![CDATA[accept]]></SubscribeStatusString>
<PopupScene>2</PopupScene>
</List>
<List>
<TemplateId><![CDATA[9nLIlbOQZC5Y89AZteFEux3WCXRRRG5Wfzkpssu4bLI]]></TemplateId>
<SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
<PopupScene>2</PopupScene>
</List>
</SubscribeMsgPopupEvent>
</xml>
JSON 格式示例
{
"ToUserName": "gh_123456789abc",
"FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
"CreateTime": "1620973045",
"MsgType": "event",
"Event": "subscribe_msg_popup_event",
"List": [ {
"TemplateId": "hD-ixGOhYmUfjOnI8MCzQMPshzGVeux_2vzyvQu7O68",
"SubscribeStatusString": "accept",
"PopupScene": "0"
}],
}
若 "List" 只有一個對象,則只返回對象本身;若 "List" 多于一個對象,則返回一個包含所有對象的數(shù)組。
參數(shù)說明
參數(shù) | 說明 |
---|---|
ToUserName | 小程序帳號ID |
FromUserName | 用戶openid |
CreateTime | 時間戳 |
TemplateId | 模板id(一次訂閱可能有多個id) |
SubscribeStatusString | 訂閱結(jié)果(accept接收;reject拒收) |
PopupScene | 彈框場景,0代表在小程序頁面內(nèi) |
2、當(dāng)用戶在手機端服務(wù)通知里消息卡片右上角“...”管理消息時,相應(yīng)的行為事件會推送至開發(fā)者所配置的服務(wù)器地址或微信云托管服務(wù)。(目前只推送取消訂閱的事件,即對消息設(shè)置“拒收”)
XML 格式示例
<xml>
<ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
<FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
<CreateTime>1610969440</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe_msg_change_event]]></Event>
<SubscribeMsgChangeEvent>
<List> <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
<SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
</List>
</SubscribeMsgChangeEvent>
</xml>
JSON 格式示例
{
"ToUserName": "gh_123456789abc",
"FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
"CreateTime": "1610968440",
"MsgType": "event",
"Event": "subscribe_msg_change_event",
"List": [ {
"TemplateId":"BEwX0BOT3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
"SubscribeStatusString": "reject"
}],
}
若 "List" 只有一個對象,則只返回對象本身;若 "List" 多于一個對象,則返回一個包含所有對象的數(shù)組。
參數(shù)說明
參數(shù) | 說明 |
---|---|
ToUserName | 小程序帳號ID |
FromUserName | 用戶openid |
CreateTime | 時間戳 |
TemplateId | 模板id(一次訂閱可能有多個id) |
SubscribeStatusString | 訂閱結(jié)果(reject拒收) |
3、調(diào)用訂閱消息接口發(fā)送消息給用戶的最終結(jié)果,會推送下發(fā)結(jié)果事件至開發(fā)者所配置的服務(wù)器地址或微信云托管服務(wù)。
XML格式示例
<xml>
<ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
<FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
<CreateTime>1610969468</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe_msg_sent_event]]></Event>
<SubscribeMsgSentEvent>
<List> <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
<MsgID>1700827132819554304</MsgID>
<ErrorCode>0</ErrorCode>
<ErrorStatus><![CDATA[success]]></ErrorStatus>
</List>
</SubscribeMsgSentEvent>
</xml>
JSON 格式示例
{
"ToUserName": "gh_123456789abc",
"FromUserName": "o7esq5PHRGBQYmeNyfG064wEFVpQ",
"CreateTime": "1620963428",
"MsgType": "event",
"Event": "subscribe_msg_sent_event",
"List": {
"TemplateId": "BEwX0BO-T3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
"MsgID": "1864323726461255680",
"ErrorCode": "0",
"ErrorStatus": "success"
}
}
參數(shù)說明
參數(shù) | 說明 |
---|---|
ToUserName | 小程序帳號ID |
FromUserName | 用戶openid |
CreateTime | 時間戳 |
TemplateId | 模板id(一次訂閱可能有多個id) |
MsgID | 消息id(調(diào)用接口時也會返回) |
ErrorCode | 推送結(jié)果狀態(tài)碼(0表示成功) |
ErrorStatus | 推送結(jié)果狀態(tài)碼對應(yīng)的含義 |
注意:失敗僅包含因異步推送導(dǎo)致的系統(tǒng)失敗
訂閱消息語音提醒
從基礎(chǔ)庫?2.18.0?開始支持
當(dāng)前小程序訂閱消息通知與微信消息的通知的提示音是一樣的,對于部分訂閱消息模板,增加語音提醒能力,播報語料部分字段支持開發(fā)者定義。
當(dāng)開發(fā)者調(diào)用wx.requestSubscribeMessage時僅訂閱1條消息且該模板支持開啟語音提醒,用戶在訂閱時可以選擇開啟語音提醒。開啟后將在接收訂閱消息時會同步播報語音提醒。
當(dāng)用戶開啟了語音提醒,開發(fā)者通過wx.getSetting獲取的該模板的訂閱狀態(tài)為'acceptWithAudio'。
訂閱彈窗樣式如下:
當(dāng)前支持開啟語音提醒的模板及播報語料如下:
標(biāo)題 | 類型 | 類目 | 播報語料 |
---|---|---|---|
收款到賬通知 | 長期訂閱 | 金融業(yè)-銀行、金融業(yè)-收單商戶服務(wù) | 小程序示例收款10元,其中“小程序示例”會播報為下發(fā)小程序的小程序簡稱,10會播報為模版中的收款金額 |
以下情況會導(dǎo)致語音提醒無法播報:
- 用戶將服務(wù)通知設(shè)置為免打擾
- 用戶開啟了手機靜音模式或手機音量過低
- 用戶未打開微信新消息通知,可引導(dǎo)用戶前往微信-“我”-“設(shè)置”-“新消息通知”中打開
- 用戶未打開系統(tǒng)對微信的通知
- 用戶開啟了低電量模式
- 用戶版本過低:需要iOS 8.0.6與安卓8.0.3及以上
訂閱消息添加提醒
從基礎(chǔ)庫?2.22.0?開始支持
用戶在訂閱小程序長期訂閱消息時,可以根據(jù)自己的使用情況添加提醒。添加后,用戶在收到消息時,在微信內(nèi)將由橫幅通知提醒。
當(dāng)用戶添加了提醒,開發(fā)者通過wx.getSetting獲取的該模板的訂閱狀態(tài)為'acceptWithForcePush'。
訂閱彈窗樣式如下:
二、wx.requestSubscribeMessage(Object object)
wx.requestSubscribeMessage(Object object) | 微信開放文檔
功能描述
調(diào)起客戶端小程序訂閱消息界面,返回用戶訂閱消息的操作結(jié)果。當(dāng)用戶勾選了訂閱面板中的“總是保持以上選擇,不再詢問”時,模板消息會被添加到用戶的小程序設(shè)置頁,通過?wx.getSetting?接口可獲取用戶對相關(guān)模板消息的訂閱狀態(tài)。
注意事項
- 一次性模板 id 和永久模板 id 不可同時使用。
- 低版本基礎(chǔ)庫2.4.4~2.8.3 已支持訂閱消息接口調(diào)用,僅支持傳入一個一次性 tmplId / 永久 tmplId。
- 2.8.2?版本開始,用戶發(fā)生點擊行為或者發(fā)起支付回調(diào)后,才可以調(diào)起訂閱消息界面。
- 2.10.0?版本開始,開發(fā)版和體驗版小程序?qū)⒔故褂媚0逑?formId。
- 一次授權(quán)調(diào)用里,每個tmplId對應(yīng)的模板標(biāo)題不能存在相同的,若出現(xiàn)相同的,只保留一個。
- 2.10.0?版本開始,支持訂閱語音消息提醒,詳情
參數(shù)
Object object
屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 |
---|---|---|---|---|
tmplIds | Array | 是 | 需要訂閱的消息模板的id的集合,一次調(diào)用最多可訂閱3條消息(注意:iOS客戶端7.0.6版本、Android客戶端7.0.7版本之后的一次性訂閱/長期訂閱才支持多個模板消息,iOS客戶端7.0.5版本、Android客戶端7.0.6版本之前的一次訂閱只支持一個模板消息)消息模板id在[微信公眾平臺(mp.weixin.qq.com)-功能-訂閱消息]中配置。每個tmplId對應(yīng)的模板標(biāo)題需要不相同,否則會被過濾。 | |
success | function | 否 | 接口調(diào)用成功的回調(diào)函數(shù) | |
fail | function | 否 | 接口調(diào)用失敗的回調(diào)函數(shù) | |
complete | function | 否 | 接口調(diào)用結(jié)束的回調(diào)函數(shù)(調(diào)用成功、失敗都會執(zhí)行) |
object.success 回調(diào)函數(shù)
參數(shù)
Object res
屬性 | 類型 | 說明 |
---|---|---|
errMsg | String | 接口調(diào)用成功時errMsg值為'requestSubscribeMessage:ok' |
[TEMPLATE_ID: string] | String | [TEMPLATE_ID]是動態(tài)的鍵,即模板id,值包括'accept'、'reject'、'ban'、'filter'。'accept'表示用戶同意訂閱該條id對應(yīng)的模板消息,'reject'表示用戶拒絕訂閱該條id對應(yīng)的模板消息,'ban'表示已被后臺封禁,'filter'表示該模板因為模板標(biāo)題同名被后臺過濾。例如 { errMsg: "requestSubscribeMessage:ok", zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: "accept"} 表示用戶同意訂閱zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE這條消息 |
object.fail 回調(diào)函數(shù)
參數(shù)
Object res
屬性 | 類型 | 說明 |
---|---|---|
errMsg | String | 接口調(diào)用失敗錯誤信息 |
errCode | Number | 接口調(diào)用失敗錯誤碼 |
錯誤碼
errCode | errMsg | 說明 |
---|---|---|
10001 | TmplIds can't be empty | 參數(shù)傳空了 |
10002 | Request list fail | 網(wǎng)絡(luò)問題,請求消息列表失敗 |
10003 | Request subscribe fail | 網(wǎng)絡(luò)問題,訂閱請求發(fā)送失敗 |
10004 | Invalid template id | 參數(shù)類型錯誤 |
10005 | Cannot show subscribe message UI | 無法展示 UI,一般是小程序這個時候退后臺了導(dǎo)致的 |
20001 | No template data return, verify the template id exist | 沒有模板數(shù)據(jù),一般是模板 ID 不存在 或者和模板類型不對應(yīng) 導(dǎo)致的 |
20002 | Templates type must be same | 模板消息類型 既有一次性的又有永久的 |
20003 | Templates count out of max bounds | 模板消息數(shù)量超過上限 |
20004 | The main switch is switched off | 用戶關(guān)閉了主開關(guān),無法進(jìn)行訂閱 |
20005 | This mini program was banned from subscribing messages | 小程序被禁封 |
20013 | Reject DeviceMsg Template | 不允許通過該接口訂閱設(shè)備消息 |
示例代碼
wx.requestSubscribeMessage({
tmplIds: [''],
success (res) { }
})
三、發(fā)送訂閱消息
發(fā)送訂閱消息 | 微信開放文檔
發(fā)送訂閱消息
?調(diào)試工具
接口應(yīng)在服務(wù)器端調(diào)用,詳細(xì)說明參見服務(wù)端API。
本接口支持云調(diào)用。需開發(fā)者工具版本 >=?
1.02.1904090
(最新穩(wěn)定版下載),wx-server-sdk
?>=?0.4.0
接口說明
接口英文名
sendMessage
功能描述
該接口用于發(fā)送訂閱消息。
調(diào)用方式
HTTPS 調(diào)用
POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token=ACCESS_TOKEN
云調(diào)用
-
出入?yún)⒑虷TTPS調(diào)用相同,調(diào)用方式可查看云調(diào)用說明文檔
-
接口方法為: openapi.subscribeMessage.send
第三方調(diào)用
-
調(diào)用方式以及出入?yún)⒑虷TTPS相同,僅是調(diào)用的token不同
-
該接口所屬的權(quán)限集id為:18
-
服務(wù)商獲得其中之一權(quán)限集授權(quán)后,可通過使用authorizer_access_token代商家進(jìn)行調(diào)用
請求參數(shù)
屬性 | 類型 | 必填 | 說明 |
---|---|---|---|
access_token | string | 是 | 接口調(diào)用憑證,該參數(shù)為 URL 參數(shù),非 Body 參數(shù)。使用access_token或者authorizer_access_token |
template_id | string | 是 | 所需下發(fā)的訂閱模板id |
page | string | 否 | 點擊模板卡片后的跳轉(zhuǎn)頁面,僅限本小程序內(nèi)的頁面。支持帶參數(shù),(示例index?foo=bar)。該字段不填則模板無跳轉(zhuǎn) |
touser | string | 是 | 接收者(用戶)的 openid |
data | string | 是 | 模板內(nèi)容,格式形如 { "key1": { "value": any }, "key2": { "value": any } }的object |
miniprogram_state | string | 是 | 跳轉(zhuǎn)小程序類型:developer為開發(fā)版;trial為體驗版;formal為正式版;默認(rèn)為正式版 |
lang | string | 是 | 進(jìn)入小程序查看”的語言類型,支持zh_CN(簡體中文)、en_US(英文)、zh_HK(繁體中文)、zh_TW(繁體中文),默認(rèn)為zh_CN |
返回參數(shù)
屬性 | 類型 | 說明 |
---|---|---|
errcode | number | 錯誤碼 |
errmsg | string | 錯誤信息 |
其他說明
訂閱消息參數(shù)值內(nèi)容限制說明
參數(shù)類別 | 參數(shù)說明 | 參數(shù)值限制 | 說明 |
---|---|---|---|
thing.DATA | 事物 | 20個以內(nèi)字符 | 可漢字、數(shù)字、字母或符號組合 |
number.DATA | 數(shù)字 | 32位以內(nèi)數(shù)字 | 只能數(shù)字,可帶小數(shù) |
letter.DATA | 字母 | 32位以內(nèi)字母 | 只能字母 |
symbol.DATA | 符號 | 5位以內(nèi)符號 | 只能符號 |
character_string.DATA | 字符串 | 32位以內(nèi)數(shù)字、字母或符號 | 可數(shù)字、字母或符號組合 |
time.DATA | 時間 | 24小時制時間格式(支持+年月日),支持填時間段,兩個時間點之間用“~”符號連接 | 例如:15:01,或:2019年10月1日 15:01 |
date.DATA | 日期 | 年月日格式(支持+24小時制時間),支持填時間段,兩個時間點之間用“~”符號連接 | 例如:2019年10月1日,或:2019年10月1日 15:01 |
amount.DATA | 金額 | 1個幣種符號+10位以內(nèi)純數(shù)字,可帶小數(shù),結(jié)尾可帶“元” | 可帶小數(shù) |
phone_number.DATA | 電話 | 17位以內(nèi),數(shù)字、符號 | 電話號碼,例:+86-0766-66888866 |
car_number.DATA | 車牌 | 8位以內(nèi),第一位與最后一位可為漢字,其余為字母或數(shù)字 | 車牌號碼:粵A8Z888掛 |
name.DATA | 姓名 | 10個以內(nèi)純漢字或20個以內(nèi)純字母或符號 | 中文名10個漢字內(nèi);純英文名20個字母內(nèi);中文和字母混合按中文名算,10個字內(nèi) |
phrase.DATA | 漢字 | 5個以內(nèi)漢字 | 5個以內(nèi)純漢字,例如:配送中 |
enum.DATA | 枚舉值 | 只能上傳枚舉值范圍內(nèi)的字段值 | 調(diào)用接口獲取參考枚舉值 |
符號表示除中文、英文、數(shù)字外的常見符號,不能帶有換行等控制字符。 時間格式支持HH:MM:SS或者HH:MM。 日期包含年月日,為y年m月d日,y年m月、m月d日格式,或者用‘-’、‘/’、‘.’符號連接,如2018-01-01,2018/01/01,2018.01.01,2018-01,01-01。 每個模板參數(shù)都會以類型為前綴,例如第一個數(shù)字模板參數(shù)為number01.DATA,第二個為number02.DATA
例如,模板的內(nèi)容為
姓名: {{name01.DATA}}
金額: {{amount01.DATA}}
行程: {{thing01.DATA}}
日期: {{date01.DATA}}
則對應(yīng)的json為
{
"touser": "OPENID",
"template_id": "TEMPLATE_ID",
"page": "index",
"data": {
"name01": {
"value": "某某"
},
"amount01": {
"value": "¥100"
},
"thing01": {
"value": "廣州至北京"
} ,
"date01": {
"value": "2018-01-01"
}
}
}
調(diào)用示例
示例說明: HTTPS請求示例
請求數(shù)據(jù)示例
{
"touser": "OPENID",
"template_id": "TEMPLATE_ID",
"page": "index",
"miniprogram_state":"developer",
"lang":"zh_CN",
"data": {
"number01": {
"value": "339208499"
},
"date01": {
"value": "2015年01月05日"
},
"site01": {
"value": "TIT創(chuàng)意園"
} ,
"site02": {
"value": "廣州市新港中路397號"
}
}
}
返回數(shù)據(jù)示例
{
"errcode":0,
"errmsg":"ok"
}
示例說明: 云函數(shù)調(diào)用示例
請求數(shù)據(jù)示例
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
try {
const result = await cloud.openapi.subscribeMessage.send({
"touser": 'OPENID',
"page": 'index',
"lang": 'zh_CN',
"data": {
"number01": {
"value": '339208499'
},
"date01": {
"value": '2015年01月05日'
},
"site01": {
"value": 'TIT創(chuàng)意園'
},
"site02": {
"value": '廣州市新港中路397號'
}
},
"templateId": 'TEMPLATE_ID',
"miniprogramState": 'developer'
})
return result
} catch (err) {
return err
}
}
返回數(shù)據(jù)示例
{
"errcode":0,
"errmsg":"ok"
}
錯誤碼
錯誤碼 | 錯誤碼取值 | 解決方案 |
---|---|---|
40001 | invalid credential? access_token isinvalid or not latest | 獲取 access_token 時 AppSecret 錯誤,或者 access_token 無效。請開發(fā)者認(rèn)真比對 AppSecret 的正確性,或查看是否正在為恰當(dāng)?shù)墓娞栒{(diào)用接口 |
40003 | invalid openid | 不合法的 OpenID ,請開發(fā)者確認(rèn) OpenID (該用戶)是否已關(guān)注公眾號,或是否是其他公眾號的 OpenID |
40014 | invalid access_token | 不合法的 access_token ,請開發(fā)者認(rèn)真比對 access_token 的有效性(如是否過期),或查看是否正在為恰當(dāng)?shù)墓娞栒{(diào)用接口 |
40037 | invalid template_id | 不合法的 template_id |
85107 |
四、開放接口
開放接口 | 微信開放文檔
開發(fā)者可調(diào)用接口完成模板選用和消息下發(fā),同時可以授權(quán)給第三方開發(fā)。
1 addTemplate 選用模板
2 deleteTemplate 刪除模板
3 getCategory 獲取公眾號類目
4 getPubTemplateKeyWordsById 獲取模板中的關(guān)鍵詞
5 getPubTemplateTitleList 獲取所屬類目的公共模板
6 getTemplateList 獲取私有模板列表
7 send 發(fā)送訂閱通知
同時可以接收事件推送
addTemplate選用模板
從公共模板庫中選用模板,到私有模板庫中
請求地址
POST https://api.weixin.qq.com/wxaapi/newtmpl/addtemplate?access_token=ACCESS_TOKEN
請求參數(shù)
屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 |
---|---|---|---|---|
access_token | string | 是 | 接口調(diào)用憑證 | |
tid | string | 是 | 模板標(biāo)題 id,可通過getPubTemplateTitleList接口獲取,也可登錄公眾號后臺查看獲取 | |
kidList | Array.<number> | 是 | 開發(fā)者自行組合好的模板關(guān)鍵詞列表,關(guān)鍵詞順序可以自由搭配(例如 [3,5,4] 或 [4,5,3]),最多支持5個,最少2個關(guān)鍵詞組合 | |
sceneDesc | string | 是 | 服務(wù)場景描述,15個字以內(nèi) |
返回值
Object
返回的 JSON 數(shù)據(jù)包
屬性 | 類型 | 說明 |
---|---|---|
errcode | number | 錯誤碼 |
errmsg | string | 錯誤信息 |
priTmplId | string | 添加至帳號下的模板id,發(fā)送訂閱通知時所需 |
errcode 的合法值
值 | 說明 | 最低版本 |
---|---|---|
200014 | 模版 tid 參數(shù)錯誤 | |
200020 | 關(guān)鍵詞列表 kidList 參數(shù)錯誤 | |
200021 | 場景描述 sceneDesc 參數(shù)錯誤 | |
200011 | 此賬號已被封禁,無法操作 | |
200013 | 此模版已被封禁,無法選用 | |
200012 | 私有模板數(shù)已達(dá)上限,上限 50 個 |
請求數(shù)據(jù)示例
{
"tid":"401",
"kidList":[1,2],
"sceneDesc": "測試數(shù)據(jù)"
}
返回數(shù)據(jù)示例
{
"errmsg": "ok",
"errcode": 0,
"priTmplId": "9Aw5ZV1j9xdWTFEkqCpZ7jWySL7aGN6rQom4gXINfJs"
}
deleteTemplate刪除模板
刪除私有模板庫中的模板
請求地址
POST https://api.weixin.qq.com/wxaapi/newtmpl/deltemplate?access_token=ACCESS_TOKEN
請求參數(shù)
屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 |
---|---|---|---|---|
access_token | string | 是 | 接口調(diào)用憑證 | |
priTmplId | string | 是 | 要刪除的模板id |
返回值
Object
返回的 JSON 數(shù)據(jù)包
屬性 | 類型 | 說明 |
---|---|---|
errcode | number | 錯誤碼 |
errmsg | string | 錯誤信息 |
errcode 的合法值
值 | 說明 | 最低版本 |
---|---|---|
20001 | 系統(tǒng)錯誤(包含該賬號下無該模板等) | |
20002 | 參數(shù)錯誤 | |
200014 | 模版 tid 參數(shù)錯誤 |
請求數(shù)據(jù)示例
{
"priTmplId": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"
}
返回數(shù)據(jù)示例
{
"errmsg": "ok",
"errcode": 0
}
getCategory獲取公眾號類目
獲取公眾號所屬類目,可用于查詢類目下的公共模板
請求地址
GET https://api.weixin.qq.com/wxaapi/newtmpl/getcategory?access_token=ACCESS_TOKEN
請求參數(shù)
屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 |
---|---|---|---|---|
access_token | string | 是 | 接口調(diào)用憑證 |
返回值
Object
返回的 JSON 數(shù)據(jù)包
屬性 | 類型 | 說明 |
---|---|---|
errcode | number | 錯誤碼 |
errmsg | string | 錯誤信息 |
data | Array.<Objtect> | 類目列表 |
data 的結(jié)構(gòu)
屬性 | 類型 | 說明 |
---|---|---|
id | number | 類目id,查詢公共模板庫時需要 |
name | string | 類目的中文名 |
errcode 的合法值
值 | 說明 | 最低版本 |
---|---|---|
20001 | 系統(tǒng)錯誤 |
請求數(shù)據(jù)示例
{
}
返回數(shù)據(jù)示例
{
"errcode": 0,
"errmsg": "ok",
"data": [
{
"id": 616,
"name": "公交"
}
]
}
getPubTemplateKeyWordsById獲取模板中的關(guān)鍵詞
獲取公共模板下的關(guān)鍵詞列表
請求地址
GET https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatekeywords?access_token=ACCESS_TOKEN
請求參數(shù)
屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 |
---|---|---|---|---|
access_token | string | 是 | 接口調(diào)用憑證 | |
tid | string | 是 | 模板標(biāo)題 id,可通過接口獲取 |
返回值
Object
返回的 JSON 數(shù)據(jù)包
屬性 | 類型 | 說明 |
---|---|---|
errcode | number | 錯誤碼 |
errmsg | string | 錯誤信息 |
count | number | 公共模板列表總數(shù) |
data | Array.<Objtect> | 關(guān)鍵詞列表 |
data 的結(jié)構(gòu)
屬性 | 類型 | 說明 |
---|---|---|
kid | number | 關(guān)鍵詞 id,選用模板時需要 |
name | string | 關(guān)鍵詞內(nèi)容 |
example | string | 關(guān)鍵詞內(nèi)容對應(yīng)的示例 |
rule | string | 參數(shù)類型 |
errcode 的合法值
值 | 說明 | 最低版本 |
---|---|---|
20001 | 系統(tǒng)錯誤 |
請求數(shù)據(jù)示例
參數(shù)在 URL 的 query 里面,例如: https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatekeywords?access_token=ACCESS_TOKEN&tid=99
{
"tid": "99"
}
返回數(shù)據(jù)示例
{
"errcode": 0,
"errmsg": "ok",
"data": [
{
"kid": 1,
"name": "物品名稱",
"example": "名稱",
"rule": "thing"
}
]
}
getPubTemplateTitleList獲取類目下的公共模板
獲取類目下的公共模板,可從中選用模板使用
請求地址
GET https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatetitles?access_token=ACCESS_TOKEN
請求參數(shù)
屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 |
---|---|---|---|---|
ids | string | 是 | 類目 id,多個用逗號隔開 | |
start | number | 是 | 用于分頁,表示從 start 開始,從 0 開始計數(shù) | |
limit | number | 是 | 用于分頁,表示拉取 limit 條記錄,最大為 30 |
返回值
Object
返回的 JSON 數(shù)據(jù)包
屬性 | 類型 | 說明 |
---|---|---|
errcode | number | 錯誤碼 |
errmsg | string | 錯誤信息 |
count | number | 公共模板列表總數(shù) |
data | Array.<Objtect> | 模板標(biāo)題列表 |
data 的結(jié)構(gòu)
屬性 | 類型 | 說明 |
---|---|---|
tid | number | 模版標(biāo)題 id |
title | string | 模版標(biāo)題 |
type | number | 模版類型,2 為一次性訂閱,3 為長期訂閱 |
categoryId | number | 模版所屬類目 id |
errcode 的合法值
值 | 說明 | 最低版本 |
---|---|---|
200016 | start 參數(shù)錯誤 | |
200017 | limit 參數(shù)錯誤 | |
200018 | 類目 ids 缺失 | |
200019 | 類目 ids 不合法 |
請求數(shù)據(jù)示例
參數(shù)在 URL 的 query 里面,例如:https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatetitles?access_token=ACCESS_TOKEN&ids="2,616"&start=0&limit=1
{
"ids": "2,616",
"start": 0,
"limit": 1
}
返回數(shù)據(jù)示例
{
"errcode": 0,
"errmsg": "ok",
"count": 55,
"data": [
{
"tid": 99,
"title": "付款成功通知",
"type": 2,
"categoryId": "616"
}
]
}
getTemplateList獲取私有模板列表
獲取私有的模板列表
請求地址
GET https://api.weixin.qq.com/wxaapi/newtmpl/gettemplate?access_token=ACCESS_TOKEN
請求參數(shù)
屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 |
---|---|---|---|---|
access_token | string | 是 | 接口調(diào)用憑證 |
返回值
Object
返回的 JSON 數(shù)據(jù)包
屬性 | 類型 | 說明 |
---|---|---|
errcode | number | 錯誤碼 |
errmsg | string | 錯誤信息 |
data | Array.<Objtect> | 個人模板列表 |
data 的結(jié)構(gòu)
屬性 | 類型 | 說明 |
---|---|---|
priTmplId | string | 添加至帳號下的模板 id,發(fā)送訂閱通知時所需 |
title | string | 模版標(biāo)題 |
content | string | 模版內(nèi)容 |
example | string | 模板內(nèi)容示例 |
type | number | 模版類型,2 為一次性訂閱,3 為長期訂閱 |
errcode 的合法值
值 | 說明 | 最低版本 |
---|---|---|
20001 | 系統(tǒng)錯誤 |
請求數(shù)據(jù)示例
{
}
返回數(shù)據(jù)示例
{
"errcode": 0,
"errmsg": "ok",
"data": [
{
"priTmplId": "9Aw5ZV1j9xdWTFEkqCpZ7mIBbSC34khK55OtzUPl0rU",
"title": "報名結(jié)果通知",
"content": "會議時間:{{date2.DATA}}\n會議地點:{{thing1.DATA}}\n",
"example": "會議時間:2016年8月8日\n會議地點:TIT會議室\n",
"type": 2
}
]
}
send發(fā)送訂閱通知
發(fā)送訂閱通知
請求地址
POST https://api.weixin.qq.com/cgi-bin/message/subscribe/bizsend?access_token=ACCESS_TOKEN
請求參數(shù)
屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 |
---|---|---|---|---|
access_token | string | 是 | 接口調(diào)用憑證 | |
touser | string | 是 | 接收者(用戶)的 openid | |
template_id | string | 是 | 所需下發(fā)的訂閱模板id | |
page | string | 否 | 跳轉(zhuǎn)網(wǎng)頁時填寫 | |
miniprogram | Array.<Objtect> | 否 | 跳轉(zhuǎn)小程序時填寫,格式如{ "appid": "pagepath": { "value": any } } | |
data | Object | 是 | 模板內(nèi)容,格式形如 { "key1": { "value": any }, "key2": { "value": any } } |
page 和 miniprogram 同時不填,無跳轉(zhuǎn);page 和 miniprogram 同時填寫,優(yōu)先跳轉(zhuǎn)小程序;
返回值
Object
返回的 JSON 數(shù)據(jù)包
屬性 | 類型 | 說明 |
---|---|---|
errcode | number | 錯誤碼 |
errmsg | string | 錯誤信息 |
errcode 的合法值
值 | 說明 | 最低版本 |
---|---|---|
40003 | touser字段openid為空或者不正確 | |
40037 | 訂閱模板id為空不正確 | |
43101 | 用戶拒絕接受消息,如果用戶之前曾經(jīng)訂閱過,則表示用戶取消了訂閱關(guān)系 | |
47003 | 模板參數(shù)不準(zhǔn)確,可能為空或者不滿足規(guī)則,errmsg會提示具體是哪個字段出錯 | |
41030 | page路徑不正確 |
請求數(shù)據(jù)示例
{
"touser": "OPENID",
"template_id": "TEMPLATEID",
"page": "mp.weixin.qq.com",
"miniprogram":{
"appid":"APPID",
"pagepath":"index?foo=bar"
},
"data": {
"name1": {
"value": "廣州騰訊科技有限公司"
},
"thing8": {
"value": "廣州騰訊科技有限公司"
},
"time7": {
"value": "2019年8月8日"
}
}
}
返回數(shù)據(jù)示例
{
"errcode": 0,
"errmsg": "ok",
}
訂閱通知參數(shù)值內(nèi)容限制說明
參數(shù)類別 | 參數(shù)說明 | 參數(shù)值限制 | 說明 |
---|---|---|---|
thing.DATA | 事物 | 20個以內(nèi)字符 | 可漢字、數(shù)字、字母或符號組合 |
number.DATA | 數(shù)字 | 32位以內(nèi)數(shù)字 | 只能數(shù)字,可帶小數(shù) |
letter.DATA | 字母 | 32位以內(nèi)字母 | 只能字母 |
symbol.DATA | 符號 | 5位以內(nèi)符號 | 只能符號 |
character_string.DATA | 字符串 | 32位以內(nèi)數(shù)字、字母或符號 | 可數(shù)字、字母或符號組合 |
time.DATA | 時間 | 24小時制時間格式(支持+年月日),支持填時間段,兩個時間點之間用“~”符號連接 | 例如:15:01,或:2019年10月1日 15:01 |
date.DATA | 日期 | 年月日格式(支持+24小時制時間),支持填時間段,兩個時間點之間用“~”符號連接 | 例如:2019年10月1日,或:2019年10月1日 15:01 |
amount.DATA | 金額 | 1個幣種符號+10位以內(nèi)純數(shù)字,可帶小數(shù),結(jié)尾可帶“元” | 可帶小數(shù) |
phone_number.DATA | 電話 | 17位以內(nèi),數(shù)字、符號 | 電話號碼,例:+86-0766-66888866 |
car_number.DATA | 車牌 | 8位以內(nèi),第一位與最后一位可為漢字,其余為字母或數(shù)字 | 車牌號碼:粵A8Z888掛 |
name.DATA | 姓名 | 10個以內(nèi)純漢字或20個以內(nèi)純字母或符號 | 中文名10個漢字內(nèi);純英文名20個字母內(nèi);中文和字母混合按中文名算,10個字內(nèi) |
phrase.DATA | 漢字 | 5個以內(nèi)漢字 | 5個以內(nèi)純漢字,例如:配送中 |
符號表示除中文、英文、數(shù)字外的常見符號,不能帶有換行等控制字符。 時間格式支持HH:MM:SS或者HH:MM。 日期包含年月日,為y年m月d日,y年m月、m月d日格式,或者用‘-’、‘/’、‘.’符號連接,如2018-01-01,2018/01/01,2018.01.01,2018-01,01-01。 每個模板參數(shù)都會以類型為前綴,例如第一個數(shù)字模板參數(shù)為number01.DATA,第二個為number02.DATA
例如,模板的內(nèi)容為
姓名: {{name01.DATA}}
金額: {{amount01.DATA}}
行程: {{thing01.DATA}}
日期: {{date01.DATA}}
則對應(yīng)的json為
{
"touser": "OPENID",
"template_id": "TEMPLATE_ID",
"page": "index",
"data": {
"name01": {
"value": "某某"
},
"amount01": {
"value": "¥100"
},
"thing01": {
"value": "廣州至北京"
},
"date01": {
"value": "2018-01-01"
}
}
}
事件推送
用戶操作訂閱通知彈窗
場景:用戶在圖文等場景內(nèi)訂閱通知的操作
參數(shù) | 描述 |
---|---|
ToUserName | 公眾號微信號 |
FromUserName | 用戶 openid |
CreateTime | 時間戳 |
TemplateId | 模板 id(一次訂閱可能有多條通知,帶有多個 id) |
SubscribeStatusString | 用戶點擊行為(同意、取消發(fā)送通知) |
PopupScene | 場景 |
SubscribeStatusString 的合法值
值 | 說明 |
---|---|
accept | 用戶點擊“同意” |
reject | 用戶點擊“取消” |
PopupScene 的合法值
值 | 說明 |
---|---|
1 | 彈窗來自 H5 頁面 |
2 | 彈窗來自圖文消息 |
XML 示例文章來源:http://www.zghlxwxcb.cn/news/detail-674013.html
<xml>
<ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
<FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
<CreateTime>1610969440</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe_msg_popup_event]]></Event>
<SubscribeMsgPopupEvent>
<List>
<TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
<SubscribeStatusString><![CDATA[accept]]></SubscribeStatusString>
<PopupScene>2</PopupScene>
</List>
<List>
<TemplateId><![CDATA[9nLIlbOQZC5Y89AZteFEux3WCXRRRG5Wfzkpssu4bLI]]></TemplateId>
<SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
<PopupScene>2</PopupScene>
</List>
</SubscribeMsgPopupEvent>
</xml>
用戶管理訂閱通知
場景:用戶在服務(wù)通知管理頁面做通知管理時的操作
參數(shù) | 描述 |
---|---|
ToUserName | 公眾號微信號 |
FromUserName | 用戶 openid |
CreateTime | 時間戳 |
TemplateId | 模板 id(一次訂閱可能有多條通知,帶有多個 id) |
SubscribeStatusString | 用戶點擊行為(僅推送用戶拒收通知) |
SubscribeStatusString 的合法值
值 | 說明 |
---|---|
reject | 用戶點擊“取消” |
XML 示例
<xml>
<ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
<FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
<CreateTime>1610969440</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe_msg_change_event]]></Event>
<SubscribeMsgChangeEvent>
<List>
<TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
<SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
</List>
</SubscribeMsgChangeEvent>
</xml>
發(fā)送訂閱通知
場景:調(diào)用 bizsend 接口發(fā)送通知
參數(shù) | 描述 |
---|---|
ToUserName | 公眾號微信號 |
FromUserName | 用戶 openid |
CreateTime | 時間戳 |
TemplateId | 模板 id(一次訂閱可能有多條通知,帶有多個 id) |
MsgID | 消息 id |
ErrorCode | 推送結(jié)果狀態(tài)碼(0表示成功) |
ErrorStatus | 推送結(jié)果狀態(tài)碼文字含義 |
*失敗僅包含因異步推送導(dǎo)致的系統(tǒng)失敗
XML 示例
<xml>
<ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
<FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
<CreateTime>1610969468</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe_msg_sent_event]]></Event>
<SubscribeMsgSentEvent>
<List>
<TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
<MsgID>1700827132819554304</MsgID>
<ErrorCode>0</ErrorCode>
<ErrorStatus><![CDATA[success]]></ErrorStatus>
</List>
</SubscribeMsgSentEvent>
</xml>
五、報錯
1、公眾號訂閱消息發(fā)送報47003錯誤
訂閱通知參數(shù)值內(nèi)容限制說明文章來源地址http://www.zghlxwxcb.cn/news/detail-674013.html
參數(shù)類別 | 參數(shù)說明 | 參數(shù)值限制 | 說明 |
---|---|---|---|
thing.DATA | 事物 | 20個以內(nèi)字符 | 可漢字、數(shù)字、字母或符號組合 |
number.DATA | 數(shù)字 | 32位以內(nèi)數(shù)字 | 只能數(shù)字,可帶小數(shù) |
letter.DATA | 字母 | 32位以內(nèi)字母 | 只能字母 |
symbol.DATA | 符號 | 5位以內(nèi)符號 | 只能符號 |
character_string.DATA | 字符串 | 32位以內(nèi)數(shù)字、字母或符號 | 可數(shù)字、字母或符號組合 |
time.DATA | 時間 | 24小時制時間格式(支持+年月日),支持填時間段,兩個時間點之間用“~”符號連接 | 例如:15:01,或:2019年10月1日 15:01 |
date.DATA | 日期 | 年月日格式(支持+24小時制時間),支持填時間段,兩個時間點之間用“~”符號連接 | 例如:2019年10月1日,或:2019年10月1日 15:01 |
amount.DATA | 金額 | 1個幣種符號+10位以內(nèi)純數(shù)字,可帶小數(shù),結(jié)尾可帶“元” | 可帶小數(shù) |
phone_number.DATA | 電話 | 17位以內(nèi),數(shù)字、符號 | 電話號碼,例:+86-0766-66888866 |
car_number.DATA | 車牌 | 8位以內(nèi),第一位與最后一位可為漢字,其余為字母或數(shù)字 | 車牌號碼:粵A8Z888掛 |
name.DATA | 姓名 | 10個以內(nèi)純漢字或20個以內(nèi)純字母或符號 | 中文名10個漢字內(nèi);純英文名20個字母內(nèi);中文和字母混合按中文名算,10個字內(nèi) |
phrase.DATA | 漢字 | 5個以內(nèi)漢字 | 5個以內(nèi)純漢字,例如:配送中 |
到了這里,關(guān)于微信小程序-小程序訂閱消息(四)的文章就介紹完了。如果您還想了解更多內(nèi)容,請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章,希望大家以后多多支持TOY模板網(wǎng)!