微信小程式API 範本訊息
基於微信的通知管道,我們為開發者提供了可以高效觸達用戶的模板訊息能力,以便實現服務的閉環並提供更佳的體驗。
範本推送位置:服務通知
範本下發條件:使用者本身在微信體系內與頁面有互動行為後觸發,詳見下發條件說明
模板跳轉能力:點選查看詳情只能跳轉下發範本的該帳號的各個頁面
使用說明
- 取得範本id
#登入https://mp.weixin.qq.com取得模板,如果沒有合適的模板,可以申請新增模板,審核通過後可使用,詳見模板審核說明
頁面的
<form/>
元件,屬性report-submit
為true
時,可以宣告為需發送範本訊息,此時點選按鈕提交表單可以取得formId
,用於傳送範本訊息。或當使用者完成支付行為,可以取得prepay_id
用於傳送範本訊息。呼叫介面下發範本訊息(詳見介面說明)
#介面說明
1. 取得access_token
access_token是全域唯一介面呼叫憑證,開發者呼叫各介面時都需使用access_token,請妥善保存。 access_token的儲存至少要保留512個字元空間。 access_token的有效期限目前為2小時,需定時刷新,重複取得將導致上次取得的access_token失效。
公共平台的API呼叫所需的access_token的使用及產生方式說明:
- 為了保密appsecrect,第三方需要一個access_token取得和刷新的中控伺服器。而其他業務邏輯伺服器所使用的access_token都來自於該中控伺服器,不應該各自去刷新,否則會造成access_token覆蓋而影響業務;
- 目前access_token的有效期透過傳回的expire_in來傳達,目前是7200秒之內的值。中控伺服器需要根據這個有效時間提前去刷新新access_token。在刷新過程中,中控伺服器對外輸出的依然是舊access_token,此時公眾平台後台會保證在刷新短時間內,新舊access_token都可用,這保證了第三方業務的平滑過渡;
- #access_token的有效時間可能會在未來有調整,所以中控伺服器不僅需要內部定時主動刷新,還需要提供被動刷新access_token的接口,這樣便於業務伺服器在API調用獲知access_token已超時的情況下,可以觸發access_token的刷新流程。
開發者可以使用AppID和AppSecret呼叫本介面來取得access_token。 AppID和AppSecret可登入微信公眾平台官網-設定-開發設定中取得(需要已經綁定成為開發者,且帳號沒有異常狀態)。 AppSecret產生後請自行儲存,因為在公眾平台每次產生查看都會導致AppSecret被重設。注意呼叫所有微信介面時均需使用https協定。如果第三方不使用中控伺服器,而是選擇各個業務邏輯點各自去刷新access_token,那麼就可能會產生衝突,導致服務不穩定。
介面位址:
https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
HTTP請求方式:
GET
參數說明:
回傳參數說明:
正常情況下,微信會傳回下述JSON封包給開發者:
{"access_token":"ACCESS_TOKEN","expires_in":7200}
錯誤時微信會傳回錯誤碼等信息,JSON封包範例如下(此範例為AppID無效錯誤):
{"errcode":40013,"errmsg":"invalid appid"}
2.傳送範本訊息
介面位址:(ACCESS_TOKEN需換成上文取得的access_token)
https://api.weixin.qq.com/cgi-bin/message/wxopen/template/send?access_token=ACCESS_TOKEN
HTTP要求方式:
POST
POST參數說明:
範例:
{ "touser": "OPENID", "template_id": "TEMPLATE_ID", "page": "index", "form_id": "FORMID", "data": { "keyword1": { "value": "339208499", "color": "#173177" }, "keyword2": { "value": "2015年01月05日 12:30", "color": "#173177" }, "keyword3": { "value": "粤海喜来登酒店", "color": "#173177" } , "keyword4": { "value": "广州市天河区天河路208号", "color": "#173177" } }, "emphasis_keyword": "keyword1.DATA" }
回傳碼說明:
在呼叫範本訊息介面後,會傳回JSON封包。
正常時的回傳JSON封包範例:
{ "errcode":0, "errmsg":"ok", }
錯誤時會傳回錯誤碼訊息,說明如下:
回傳碼 | 說明 |
---|---|
#40037 | template_id不正確 |
41028 | form_id不正確,或過期 |
form_id已被使用 | |
page不正確 |