當用戶發送消息給公眾號時(或某些特定的用戶操作引發的事件推送時),會產生一個POST請求,開發者可以在響應包(Get)中返回特定XML結構,來對該消息進行響應(現支持回復文本、圖片、圖文、語音、視頻、音樂)。嚴格來說,發送被動響應消息其實并不是一種接口,而是對微信服務器發過來消息的一次回復。
微信服務器在將用戶的消息發給公眾號的開發者服務器地址(開發者中心處配置)后,微信服務器在五秒內收不到響應會斷掉連接,并且重新發起請求,總共重試三次,如果在調試中,發現用戶無法收到響應的消息,可以檢查是否消息處理超時。關于重試的消息排重,有msgid的消息推薦使用msgid排重。事件類型消息推薦使用FromUserName + CreateTime 排重。
如果開發者希望增強安全性,可以在開發者中心處開啟消息加密,這樣,用戶發給公眾號的消息以及公眾號被動回復用戶消息都會繼續加密,詳見被動回復消息加解密說明。
假如服務器無法保證在五秒內處理并回復,必須做出下述回復,這樣微信服務器才不會對此作任何處理,并且不會發起重試(這種情況下,可以使用客服消息接口進行異步回復),否則,將出現嚴重的錯誤提示。詳見下面說明:
1、直接回復success(推薦方式) 2、直接回復空串(指字節長度為0的空字符串,而不是XML結構體中content字段的內容為空)
一旦遇到以下情況,微信都會在公眾號會話中,向用戶下發系統提示“該公眾號暫時無法提供服務,請稍后再試”:
1、開發者在5秒內未回復任何內容 2、開發者回復了異常數據,比如JSON數據等
另外,請注意,回復圖片(不支持gif動圖)等多媒體消息時需要預先通過素材管理接口上傳臨時素材到微信服務器,可以使用素材管理中的臨時素材,也可以使用永久素材。
各消息類型需要的XML數據包結構如下:
目錄
1 回復文本消息
2 回復圖片消息
3 回復語音消息
4 回復視頻消息
5 回復音樂消息
6 回復圖文消息
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>12345678</CreateTime> <MsgType><![CDATA[text]]></MsgType> <Content><![CDATA[你好]]></Content> </xml>
參數 | 是否必須 | 描述 |
---|---|---|
ToUserName | 是 | 接收方帳號(收到的OpenID) |
FromUserName | 是 | 開發者微信號 |
CreateTime | 是 | 消息創建時間 (整型) |
MsgType | 是 | 消息類型,文本為text |
Content | 是 | 回復的消息內容(換行:在content中能夠換行,微信客戶端就支持換行顯示) |
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>12345678</CreateTime> <MsgType><![CDATA[image]]></MsgType> <Image> <MediaId><![CDATA[media_id]]></MediaId> </Image> </xml>
參數 | 是否必須 | 說明 |
---|---|---|
ToUserName | 是 | 接收方帳號(收到的OpenID) |
FromUserName | 是 | 開發者微信號 |
CreateTime | 是 | 消息創建時間 (整型) |
MsgType | 是 | 消息類型,圖片為image |
MediaId | 是 | 通過素材管理中的接口上傳多媒體文件,得到的id。 |
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>12345678</CreateTime> <MsgType><![CDATA[voice]]></MsgType> <Voice> <MediaId><![CDATA[media_id]]></MediaId> </Voice> </xml>
參數 | 是否必須 | 說明 |
---|---|---|
ToUserName | 是 | 接收方帳號(收到的OpenID) |
FromUserName | 是 | 開發者微信號 |
CreateTime | 是 | 消息創建時間戳 (整型) |
MsgType | 是 | 消息類型,語音為voice |
MediaId | 是 | 通過素材管理中的接口上傳多媒體文件,得到的id |
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>12345678</CreateTime> <MsgType><![CDATA[video]]></MsgType> <Video> <MediaId><![CDATA[media_id]]></MediaId> <Title><![CDATA[title]]></Title> <Description><![CDATA[description]]></Description> </Video> </xml>
參數 | 是否必須 | 說明 |
---|---|---|
ToUserName | 是 | 接收方帳號(收到的OpenID) |
FromUserName | 是 | 開發者微信號 |
CreateTime | 是 | 消息創建時間 (整型) |
MsgType | 是 | 消息類型,視頻為video |
MediaId | 是 | 通過素材管理中的接口上傳多媒體文件,得到的id |
Title | 否 | 視頻消息的標題 |
Description | 否 | 視頻消息的描述 |
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>12345678</CreateTime> <MsgType><![CDATA[music]]></MsgType> <Music> <Title><![CDATA[TITLE]]></Title> <Description><![CDATA[DESCRIPTION]]></Description> <MusicUrl><![CDATA[MUSIC_Url]]></MusicUrl> <HQMusicUrl><![CDATA[HQ_MUSIC_Url]]></HQMusicUrl> <ThumbMediaId><![CDATA[media_id]]></ThumbMediaId> </Music> </xml>
參數 | 是否必須 | 說明 |
---|---|---|
ToUserName | 是 | 接收方帳號(收到的OpenID) |
FromUserName | 是 | 開發者微信號 |
CreateTime | 是 | 消息創建時間 (整型) |
MsgType | 是 | 消息類型,音樂為music |
Title | 否 | 音樂標題 |
Description | 否 | 音樂描述 |
MusicURL | 否 | 音樂鏈接 |
HQMusicUrl | 否 | 高質量音樂鏈接,WIFI環境優先使用該鏈接播放音樂 |
ThumbMediaId | 是 | 縮略圖的媒體id,通過素材管理中的接口上傳多媒體文件,得到的id |
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>12345678</CreateTime> <MsgType><![CDATA[news]]></MsgType> <ArticleCount>1</ArticleCount> <Articles> <item> <Title><![CDATA[title1]]></Title> <Description><![CDATA[description1]]></Description> <PicUrl><![CDATA[picurl]]></PicUrl> <Url><![CDATA[url]]></Url> </item> </Articles> </xml>
參數 | 是否必須 | 說明 |
---|---|---|
ToUserName | 是 | 接收方帳號(收到的OpenID) |
FromUserName | 是 | 開發者微信號 |
CreateTime | 是 | 消息創建時間 (整型) |
MsgType | 是 | 消息類型,圖文為news |
ArticleCount | 是 | 圖文消息個數;當用戶發送文本、圖片、視頻、圖文、地理位置這五種消息時,開發者只能回復1條圖文消息;其余場景多可回復8條圖文消息 |
Articles | 是 | 圖文消息信息,注意,如果圖文數超過限制,則將只發限制內的條數 |
Title | 是 | 圖文消息標題 |
Description | 是 | 圖文消息描述 |
PicUrl | 是 | 圖片鏈接,支持JPG、PNG格式,較好的效果為大圖360*200,小圖200*200 |
Url | 是 | 點擊圖文消息跳轉鏈接 |