微信公眾平臺二次開發技術文件
微信公眾平臺二次開發技術文件
本文件基於騰訊公司微信二次開發的相關規範，對微信二次開發的流程、步驟做了相關的說明，方便程式設計和開發人員快速掌握微信公眾平臺開發技術，便於提高程式碼的編寫效率以及減少出現錯誤概率。
登入微信公眾平臺官網後，在公眾平臺後臺管理頁面 - 開發者中心頁，點選“修改配置”按鈕，填寫伺服器地址（URL）、Token和EncodingAESKey，其中URL是開發者用來接收微信訊息和事件的介面URL。Token可由開發者可以任意填寫，用作生成簽名（該Token會和介面URL中包含的Token進行比對，從而驗證安全性）。EncodingAESKey由開發者手動填寫或隨機生成，將用作訊息體加解密金鑰。
開發者提交資訊後，微信伺服器將傳送GET請求到填寫的伺服器地址URL上，GET請求攜帶四個引數：
| 引數 |
描述 |
| signature |
微信加密簽名，signature結合了開發者填寫的token引數和請求中的timestamp引數、nonce引數。 |
| timestamp |
時間戳 |
| nonce |
隨機數 |
| echostr |
隨機字串 |
開發者通過檢驗signature對請求進行校驗（下面有校驗方式）。若確認此次GET請求來自微信伺服器，請原樣返回echostr引數內容，則接入生效，成為開發者成功，否則接入失敗。
加密/校驗流程如下：
1. 將token、timestamp、nonce三個引數進行字典序排序
2. 將三個引數字串拼接成一個字串進行sha1加密
3. 開發者獲得加密後的字串可與signature對比，標識該請求來源於微信
驗證URL有效性成功後即接入生效，成為開發者。如果公眾號型別為服務號（訂閱號只能使用普通訊息介面），可以在公眾平臺網站中申請認證，認證成功的服務號將獲得眾多介面許可權，以滿足開發者需求。
此後使用者每次向公眾號傳送訊息、或者產生自定義選單點選事件時，開發者填寫的伺服器配置URL將得到微信伺服器推送過來的訊息和事件，然後開發者可以依據自身業務邏輯進行響應，例如回覆訊息等。
使用者向公眾號傳送訊息時，公眾號方收到的訊息傳送者是一個OpenID，是使用使用者微訊號加密後的結果，每個使用者對每個公眾號有一個唯一的OpenID。
access_token是公眾號的全域性唯一票據，公眾號呼叫各介面時都需使用access_token。開發者需要進行妥善儲存。access_token的儲存至少要保留512個字元空間。access_token的有效期目前為2個小時，需定時重新整理，重複獲取將導致上次獲取的access_token失效。
公眾平臺的API呼叫所需的access_token的使用及生成方式說明：
1、為了保密appsecrect，第三方需要一個access_token獲取和重新整理的中控伺服器。而其他業務邏輯伺服器所使用的access_token均來自於該中控伺服器，不應該各自去重新整理，否則會造成access_token覆蓋而影響業務；2、目前access_token的有效期通過返回的expire_in來傳達，目前是7200秒之內的值。中控伺服器需要根據這個有效時間提前去重新整理新access_token。在重新整理過程中，中控伺服器對外輸出的依然是老access_token，此時公眾平臺後臺會保證在重新整理短時間內，新老access_token都可用，這保證了第三方業務的平滑過渡；3、access_token的有效時間可能會在未來有調整，所以中控伺服器不僅需要內部定時主動重新整理，還需要提供被動重新整理access_token的介面，這樣便於業務伺服器在API呼叫獲知access_token已超時的情況下，可以觸發access_token的重新整理流程。如果第三方不使用中控伺服器，而是選擇各個業務邏輯點各自去重新整理access_token，那麼就可能會產生衝突，導致服務不穩定。
公眾號可以使用AppID和AppSecret呼叫本介面來獲取access_token。AppID和AppSecret可在微信公眾平臺官網-開發者中心頁中獲得（需要已經成為開發者，且帳號沒有異常狀態）。注意呼叫所有微信介面時均需使用https協議。
介面呼叫請求說明
http請求方式: GEThttps://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET引數說明
| 引數 |
是否必須 |
說明 |
| grant_type |
是 |
獲取access_token填寫client_credential |
| appid |
是 |
第三方使用者唯一憑證 |
| secret |
是 |
第三方使用者唯一憑證金鑰，即appsecret |
返回說明
正常情況下，微信會返回下述JSON資料包給公眾號：
{"access_token":"ACCESS_TOKEN","expires_in":7200}| 引數 |
說明 |
| access_token |
獲取到的憑證 |
| expires_in |
憑證有效時間，單位：秒 |
錯誤時微信會返回錯誤碼等資訊，JSON資料包示例如下（該示例為AppID無效錯誤）:
{"errcode":40013,"errmsg":"invalid appid"}
請注意：
1、自定義選單最多包括3個一級選單，每個一級選單最多包含5個二級選單。
2、一級選單最多4個漢字，二級選單最多7個漢字，多出來的部分將會以“...”代替。
3、建立自定義選單後，選單的重新整理策略是，在使用者進入公眾號會話頁或公眾號profile頁時，如果發現上一次拉取選單的請求在5分鐘以前，就會拉取一下選單，如果選單有更新，就會重新整理客戶端的選單。測試時可以嘗試取消關注公眾賬號後再次關注，則可以看到建立後的效果。
介面呼叫請求說明
http請求方式：POST（請使用https協議） https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN
click和view的請求示例
{ "button":[ { "type":"click", "name":"今日歌曲", "key":"V1001_TODAY_MUSIC" }, { "name":"選單", "sub_button":[ { "type":"view", "name":"搜尋", "url":"http://www.soso.com/" }, { "type":"view", "name":"視訊", "url":"http://v.qq.com/" }, { "type":"click", "name":"贊一下我們", "key":"V1001_GOOD" }] }] }其他新增按鈕型別的請求示例
{ "button": [ { "name": "掃碼", "sub_button": [ { "type": "scancode_waitmsg", "name": "掃碼帶提示", "key": "rselfmenu_0_0", "sub_button": [ ] }, { "type": "scancode_push", "name": "掃碼推事件", "key": "rselfmenu_0_1", "sub_button": [ ] } ] }, { "name": "發圖", "sub_button": [ { "type": "pic_sysphoto", "name": "系統拍照發圖", "key": "rselfmenu_1_0", "sub_button": [ ] }, { "type": "pic_photo_or_album", "name": "拍照或者相簿發圖", "key": "rselfmenu_1_1", "sub_button": [ ] }, { "type": "pic_weixin", "name": "微信相簿發圖", "key": "rselfmenu_1_2", "sub_button": [ ] } ] }, { "name": "傳送位置", "type": "location_select", "key": "rselfmenu_2_0" }, { "type": "media_id", "name": "圖片", "media_id": "MEDIA_ID1" }, { "type": "view_limited", "name": "圖文訊息", "media_id": "MEDIA_ID2" } ]}引數說明
| 引數 |
是否必須 |
說明 |
| button |
是 |
一級選單陣列，個數應為1~3個 |
| sub_button |
否 |
二級選單陣列，個數應為1~5個 |
| type |
是 |
選單的響應動作型別 |
| name |
是 |
選單標題，不超過16個位元組，子選單不超過40個位元組 |
| key |
click等點選型別必須 |
選單KEY值，用於訊息介面推送，不超過128位元組 |
| url |
view型別必須 |
網頁連結，使用者點選選單可開啟連結，不超過1024位元組 |
| media_id |
media_id型別和view_limited型別必須 |
呼叫新增永久素材介面返回的合法media_id |
返回結果
正確時的返回JSON資料包如下：
{"errcode":0,"errmsg":"ok"}錯誤時的返回JSON資料包如下（示例為無效選單名長度）：
{"errcode":40018,"errmsg":"invalid button name size"}
使用介面建立自定義選單後，開發者還可使用介面查詢自定義選單的結構。另外請注意，在設定了個性化選單後，使用本自定義選單查詢介面可以獲取預設選單和全部個性化選單資訊。
請求說明
http請求方式：GEThttps://api.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN返回說明（無個性化選單時）
對應建立介面，正確的Json返回結果:{"menu":{"button":[{"type":"click","name":"今日歌曲","key":"V1001_TODAY_MUSIC","sub_button":[]},{"type":"click","name":"歌手簡介","key":"V1001_TODAY_SINGER","sub_button":[]},{"name":"選單","sub_button":[{"type":"view","name":"搜尋","url":"http://www.soso.com/","sub_button":[]},{"type":"view","name":"視訊","url":"http://v.qq.com/","sub_button":[]},{"type":"click","name":"贊一下我們","key":"V1001_GOOD","sub_button":[]}]}]}}返回說明（有個性化選單時）
{ "menu": { "button": [ { "type": "click", "name": "今日歌曲", "key": "V1001_TODAY_MUSIC", "sub_button": [ ] } ], "menuid": 208396938 }, "conditionalmenu": [ { "button": [ { "type": "click", "name": "今日歌曲", "key": "V1001_TODAY_MUSIC", "sub_button": [ ] }, { "name": "選單", "sub_button": [ { "type": "view", "name": "搜尋", "url": "http://www.soso.com/", "sub_button": [ ] }, { "type": "view", "name": "視訊", "url": "http://v.qq.com/", "sub_button": [ ] }, { "type": "click", "name": "贊一下我們", "key": "V1001_GOOD", "sub_button": [ ] } ] } ], "matchrule": { "group_id": 2, "sex": 1, "country": "中國", "province": "廣東", "city": "廣州", "client_platform_type": 2 }, "menuid": 208396993 } ]}
注：menu為預設選單，conditionalmenu為個性化選單列表。欄位說明請見個性化選單介面頁的說明。
使用介面建立自定義選單後，開發者還可使用介面刪除當前使用的自定義選單。另請注意，在個性化選單時，呼叫此介面會刪除預設選單及全部個性化選單。
請求說明
http請求方式：GEThttps://api.weixin.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN返回說明
對應建立介面，正確的Json返回結果:{"errcode":0,"errmsg":"ok"}當普通微信使用者向公眾賬號發訊息時，微信伺服器將POST訊息的XML資料包到開發者填寫的URL上。
-
-
-
- 文字訊息
-
-
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>1348831860</CreateTime> <MsgType><![CDATA[text]]></MsgType> <Content><![CDATA[this is a test]]></Content> <MsgId>1234567890123456</MsgId> </xml>| 引數 |
描述 |
| ToUserName |
開發者微訊號 |
| FromUserName |
傳送方帳號（一個OpenID） |
| CreateTime |
訊息建立時間 （整型） |
| MsgType |
text |
| Content |
文字訊息內容 |
| MsgId |
訊息id，64位整型 |
-
-
-
- 圖片訊息
-
-
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>1348831860</CreateTime> <MsgType><![CDATA[image]]></MsgType> <PicUrl><![CDATA[this is a url]]></PicUrl> <MediaId><![CDATA[media_id]]></MediaId> <MsgId>1234567890123456</MsgId> </xml>| 引數 |
描述 |
| ToUserName |
開發者微訊號 |
| FromUserName |
傳送方帳號（一個OpenID） |
| CreateTime |
訊息建立時間 （整型） |
| MsgType |
image |
| PicUrl |
圖片連結 |
| MediaId |
圖片訊息媒體id，可以呼叫多媒體檔案下載介面拉取資料。 |
| MsgId |
訊息id，64位整型 |
-
-
-
- 語音訊息
-
-
<xml><ToUserName><![CDATA[toUser]]></ToUserName><FromUserName><![CDATA[fromUser]]></FromUserName><CreateTime>1357290913</CreateTime><MsgType><![CDATA[voice]]></MsgType><MediaId><![CDATA[media_id]]></MediaId><Format><![CDATA[Format]]></Format><MsgId>1234567890123456</MsgId></xml>| 引數 |
描述 |
| ToUserName |
開發者微訊號 |
| FromUserName |
傳送方帳號（一個OpenID） |
| CreateTime |
訊息建立時間 （整型） |
| MsgType |
語音為voice |
| MediaId |
語音訊息媒體id，可以呼叫多媒體檔案下載介面拉取資料。 |
| Format |
語音格式，如amr，speex等 |
| MsgID |
訊息id，64位整型 |
請注意，開通語音識別後，使用者每次傳送語音給公眾號時，微信會在推送的語音訊息XML資料包中，增加一個Recongnition欄位（注：由於客戶端快取，開發者開啟或者關閉語音識別功能，對新關注者立刻生效，對已關注使用者需要24小時生效。開發者可以重新關注此帳號進行測試）。開啟語音識別後的語音XML資料包如下：
<xml><ToUserName><![CDATA[toUser]]></ToUserName><FromUserName><![CDATA[fromUser]]></FromUserName><CreateTime>1357290913</CreateTime><MsgType><![CDATA[voice]]></MsgType><MediaId><![CDATA[media_id]]></MediaId><Format><![CDATA[Format]]></Format><Recognition><![CDATA[騰訊微信團隊]]></Recognition><MsgId>1234567890123456</MsgId></xml>多出的欄位中，Format為語音格式，一般為amr，Recognition為語音識別結果，使用UTF8編碼。
-
-
-
- 視訊訊息
-
-
<xml><ToUserName><![CDATA[toUser]]></ToUserName><FromUserName><![CDATA[fromUser]]></FromUserName><CreateTime>1357290913</CreateTime><MsgType><![CDATA[video]]></MsgType><MediaId><![CDATA[media_id]]></MediaId><ThumbMediaId><![CDATA[thumb_media_id]]></ThumbMediaId><MsgId>1234567890123456</MsgId></xml>| 引數 |
描述 |
| ToUserName |
開發者微訊號 |
| FromUserName |
傳送方帳號（一個OpenID） |
| CreateTime |
訊息建立時間 （整型） |
| MsgType |
視訊為video |
| MediaId |
視訊訊息媒體id，可以呼叫多媒體檔案下載介面拉取資料。 |
| ThumbMediaId |
視訊訊息縮圖的媒體id，可以呼叫多媒體檔案下載介面拉取資料。 |
| MsgId |
訊息id，64位整型 |
-
-
-
- 小視訊訊息
-
-
<xml><ToUserName><![CDATA[toUser]]></ToUserName><FromUserName><![CDATA[fromUser]]></FromUserName><CreateTime>1357290913</CreateTime><MsgType><![CDATA[shortvideo]]></MsgType><MediaId><![CDATA[media_id]]></MediaId><ThumbMediaId><![CDATA[thumb_media_id]]></ThumbMediaId><MsgId>1234567890123456</MsgId></xml>| 引數 |
描述 |
| ToUserName |
開發者微訊號 |
| FromUserName |
傳送方帳號（一個OpenID） |
| CreateTime |
訊息建立時間 （整型） |
| MsgType |
小視訊為shortvideo |
| MediaId |
視訊訊息媒體id，可以呼叫多媒體檔案下載介面拉取資料。 |
| ThumbMediaId |
視訊訊息縮圖的媒體id，可以呼叫多媒體檔案下載介面拉取資料。 |
| MsgId |
訊息id，64位整型 |
-
-
-
- 地理位置訊息
-
-
<xml><ToUserName><![CDATA[toUser]]></ToUserName><FromUserName><![CDATA[fromUser]]></FromUserName><CreateTime>1351776360</CreateTime><MsgType><![CDATA[location]]></MsgType><Location_X>23.134521</Location_X><Location_Y>113.358803</Location_Y><Scale>20</Scale><Label><![CDATA[位置資訊]]></Label><MsgId>1234567890123456</MsgId></xml> | 引數 |
描述 |
| T |