微信開發(fā)者文檔

接收事件推送

目錄

1關(guān)注/取消關(guān)注事件

2掃描帶參數(shù)二維碼事件

3上報(bào)地理位置事件

4自定義菜單事件

5點(diǎn)擊菜單拉取消息時(shí)的事件推送

6點(diǎn)擊菜單跳轉(zhuǎn)鏈接時(shí)的事件推送

關(guān)注/取消關(guān)注事件

用戶在關(guān)注與取消關(guān)注公眾號時(shí)，微信會(huì)把這個(gè)事件推送到開發(fā)者填寫的URL。方便開發(fā)者給用戶下發(fā)歡迎消息或者做帳號的解綁。

微信服務(wù)器在五秒內(nèi)收不到響應(yīng)會(huì)斷掉連接，并且重新發(fā)起請求，總共重試三次

關(guān)于重試的消息排重，推薦使用FromUserName+CreateTime排重。

假如服務(wù)器無法保證在五秒內(nèi)處理并回復(fù)，可以直接回復(fù)空串，微信服務(wù)器不會(huì)對此作任何處理，并且不會(huì)發(fā)起重試。

推送XML數(shù)據(jù)包示例：

<xml>

<ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[FromUser]]></FromUserName>

<CreateTime>123456789</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[subscribe]]></Event>

</xml>

參數(shù)說明：

參數(shù) 描述

ToUserName開發(fā)者微信號

FromUserName 發(fā)送方帳號（一個(gè)OpenID）

CreateTime 消息創(chuàng)建時(shí)間（整型）

MsgType消息類型，event

Event 事件類型，subscribe（訂閱）、unsubscribe（取消訂閱）

掃描帶參數(shù)二維碼事件

用戶掃描帶場景值二維碼時(shí)，可能推送以下兩種事件：

如果用戶還未關(guān)注公眾號，則用戶可以關(guān)注公眾號，關(guān)注后微信會(huì)將帶場景值關(guān)注事件推送給開發(fā)者。

如果用戶已經(jīng)關(guān)注公眾號，則微信會(huì)將帶場景值掃描事件推送給開發(fā)者。

用戶未關(guān)注時(shí)，進(jìn)行關(guān)注后的事件推送

推送XML數(shù)據(jù)包示例：

<xml><ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[FromUser]]></FromUserName>

<CreateTime>123456789</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[subscribe]]></Event>

<EventKey><![CDATA[qrscene_123123]]></EventKey>

<Ticket><![CDATA[TICKET]]></Ticket>

</xml>

參數(shù)說明：參數(shù)

ToUserName

FromUserName

CreateTime

MsgType

Event

EventKey

Ticket

描述

開發(fā)者微信號

發(fā)送方帳號（一個(gè)OpenID）

消息創(chuàng)建時(shí)間（整型）

消息類型，event

事件類型，subscribe

事件KEY值，qrscene—為前綴，后面為二維碼的參數(shù)值二維碼的ticket，可用來換取二維碼圖片

2.用戶已關(guān)注時(shí)的事件推送推送XML數(shù)據(jù)包示例：<xml>

<ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[FromUser]]></FromUserName>

<CreateTime>123456789</CreateTime><MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[SCAN]]></Event>

<EventKey><![CDATA[SCENE_AALUE]]></EventKey>

<Ticket><![CDATA[TICKET]]></Ticket>

</xml>

參數(shù)說明：

描述

開發(fā)者微信號

發(fā)送方帳號（一個(gè)OpenID）

消息創(chuàng)建時(shí)間（整型）

消息類型，event

事件類型，SCAN

事件KEY值，是一個(gè)32位無符號整數(shù)，即創(chuàng)建二維碼時(shí)的二

參數(shù)

ToUserName

FromUserName

CreateTime

MsgType

Event

EventKey

二維碼的ticket，可用來換取二維碼圖片

維碼scene_id

Ticket

上報(bào)地理位置事件

用戶同意上報(bào)地理位置后，每次進(jìn)入公眾號會(huì)話時(shí)，都會(huì)在進(jìn)入時(shí)上報(bào)地理位置，或在進(jìn)入會(huì)話后每5秒上報(bào)一次地理位置，公眾號可以在公眾平臺(tái)網(wǎng)站中修改以上設(shè)置。上報(bào)地理位置時(shí)，微信會(huì)將上報(bào)地理位置事件推送到開發(fā)者填寫的URL。

推送XML數(shù)據(jù)包示例：

<xml><ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[fromUser]]></FromUserName>

<CreateTime>123456789</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[LOCATION]]></Event>

<Latitude>23.137466</Latitude>

<Longitude>113.352425</Longitude>

<Precision>119.385040</Precision>

</xml>

參數(shù)說明：

描述

開發(fā)者微信號

發(fā)送方帳號（一個(gè)OpenID）

消息創(chuàng)建時(shí)間（整型）

消息類型，event

事件類型，LOCATION

地理位置緯度

地理位置經(jīng)度

地理位置精度

參數(shù)

ToUserName

FromUserName

CreateTime

MsgType

Event

Latitude

Longitude

Precision

使用網(wǎng)頁調(diào)試工具調(diào)試該接口

自定義菜單事件

用戶點(diǎn)擊自定義菜單后，微信會(huì)把點(diǎn)擊事件推送給開發(fā)者，請注意，點(diǎn)擊菜單彈出子菜單，不會(huì)產(chǎn)生上報(bào)。

點(diǎn)擊菜單拉取消息時(shí)的事件推送

推送XML數(shù)據(jù)包示例：

<xml>

<ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[FromUser]]></FromUserName>

<CreateTime>123456789</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[CLICK]]></Event>

<EventKey><![CDATA[EVENTKEY]]></EventKey>

</xml>

參數(shù)說明：

描述

開發(fā)者微信號

發(fā)送方帳號（一個(gè)OpenlD）

消息創(chuàng)建時(shí)間（整型）

消息類型，event

事件類型，CLICK

事件KEY值，與自定義菜單接口中KEY值對應(yīng)

參數(shù)

ToUserName

FromUserName

CreateTime

MsgType

Event

EventKey

點(diǎn)擊菜單跳轉(zhuǎn)鏈接時(shí)的事件推送推送XML數(shù)據(jù)包示例：<xml>

<ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[FromUser]]></FromUserName>

<CreateTime>123456789</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[VIEW]]></Event>

<EventKey><![CDATA[]]></EventKey>

</xml>

參數(shù)說明：

參數(shù)

ToUserName

FromUserName

CreateTime

MsgType

Event

EventKey

描述

開發(fā)者微信號

發(fā)送方帳號（一個(gè)OpenID）

消息創(chuàng)建時(shí)間（整型）

消息類型，event

事件類型，VIEW

事件KEY值，設(shè)置的跳轉(zhuǎn)URL

開通語音識(shí)別功能

用戶每次發(fā)送語音給公眾號時(shí)，微信會(huì)在推送的語音消息 XML數(shù)據(jù)包中，增加一個(gè)

Recongnition字段。

注：由于客戶端緩存，開發(fā)者開啟或者關(guān)閉語音識(shí)別功能，對新關(guān)注者立刻生效，對已關(guān)注用戶需要24小時(shí)生效。開發(fā)者可以重新關(guān)注此帳號進(jìn)行測試。

開啟語音識(shí)別后的語音XML數(shù)據(jù)包如下：

<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騰訊微信團(tuán)隊(duì)]]></Recognition>

<MsgId>1234567890123456</MsgId>

</xml>

參數(shù)說明：參數(shù)

ToUserName

FromUserName

CreateTime

MsgType

MediaID

Format

Recognition

MsgID

描述

開發(fā)者微信號

發(fā)送方帳號（一個(gè)OpenID）

消息創(chuàng)建時(shí)間（整型）

語音為voice

語音消息媒體id，可以調(diào)用多媒體文件下載接口拉取該媒體

語音格式：amr

語音識(shí)別結(jié)果，UTF8編碼

消息id，64位整型發(fā)送被動(dòng)響應(yīng)消息

對于每一個(gè)POST請求，開發(fā)者在響應(yīng)包（Get）中返回特定XML結(jié)構(gòu)，對該消息進(jìn)行響應(yīng)（現(xiàn)支持回復(fù)文本、圖片、圖文、語音、視頻、音樂）。請注意，回復(fù)圖片等多媒體消息時(shí)需要預(yù)先上傳多媒體文件到微信服務(wù)器，只支持認(rèn)證服務(wù)號。

微信服務(wù)器在五秒內(nèi)收不到響應(yīng)會(huì)斷掉連接，并且重新發(fā)起請求，總共重試三次，如果在調(diào)試中，發(fā)現(xiàn)用戶無法收到響應(yīng)的消息，可以檢查是否消息處理超時(shí)。

關(guān)于重試的消息排重，有msgid的消息推薦使用msgid排重。事件類型消息推薦使用FromUserName+CreateTime排重。

假如服務(wù)器無法保證在五秒內(nèi)處理并回復(fù)，必須直接回復(fù)空串（是指回復(fù)一個(gè)空字符串，而不是一個(gè)XML結(jié)構(gòu)體中content字段的內(nèi)容為空，請切勿誤解），微信服務(wù)器不會(huì)對此作任何處理，并且不會(huì)發(fā)

起重試。。這種情況下，可以使用客服消息接口進(jìn)行異步回復(fù)。

請開發(fā)者注意，一旦遇到以下情況，微信都會(huì)在公眾號會(huì)話中，向用戶下發(fā)系統(tǒng)提示“該公眾號暫時(shí)無法提供服務(wù)，請稍后再試”：

1、 開發(fā)者在5秒內(nèi)未回復(fù)任何內(nèi)容

2、 開發(fā)者回復(fù)了異常數(shù)據(jù)，比如JSON數(shù)據(jù)等

各消息類型需要的XML數(shù)據(jù)包結(jié)構(gòu)如下。

目錄1回復(fù)文本消息

2回復(fù)圖片消息

3回復(fù)語音消息

4回復(fù)視頻消息

5回復(fù)音樂消息

6回復(fù)圖文消息

回復(fù)文本消息

<xml>

<ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[fromUser]]></FromUserName>

<CreateTime>12345678</CreateTime>

<MsgType><![CDATA[text]]></MsgType>

<Content><![CDATA你好]]></Content>

</xml>

描述

接收方帳號（收到的OpenID）

開發(fā)者微信號

消息創(chuàng)建時(shí)間（整型）

text

回復(fù)的消息內(nèi)容（換行：在content中能夠換行，微信

參數(shù)是否必須

ToUserName是

FromUserName是

CreateTime

MsgType

Content

是

是

是客戶端就支持換行顯示）回復(fù)圖片消息

<xml>

<ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[fromUser]]></FromUserName>

<CreateTime>12345678</CreateTime>

<MsgType><![CDATA[image]]></MsgType>

<Image>

<MediaId><![CDATA[media_id]]></MediaId>

</Image>

</xml>

參數(shù)

是否必須

說明

ToUserName

是

接收方帳號（收到的OpenID）

FromUserName是

開發(fā)者微信號

CreateTime

是

消息創(chuàng)建時(shí)間（整型）

MsgType

是

image

MediaId

是

通過上傳多媒體文件，得到的id。

回復(fù)語音消息

<xml>

<ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[fromUser]]></FromUserName>

<CreateTime>12345678</CreateTime>

<MsgType><![CDATA[voice]]></MsgType>

<Voice>

<MediaId><![CDATA[media_id]]></MediaId>

</Voice>

</xml>

參數(shù)

是否必須

說明

ToUserName

是

接收方帳號（收到的OpenID）

FromUserName

是

開發(fā)者微信號

CreateTime

是

消息創(chuàng)建時(shí)間戳（整型）

MsgType

是

語音）voice

MediaId

是

通過上傳多媒體文件，得到的id

回復(fù)視頻消息

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

參數(shù)

是否必須

說明

ToUserName

是

接收方帳號（收到的OpenID）

FromUserName

是

開發(fā)者微信號

CreateTime

是

消息創(chuàng)建時(shí)間（整型）

MsgType

是

video

MediaId

是

通過上傳多媒體文件，得到的id

Title

否

視頻消息的標(biāo)題

Description否 視頻消息的描述

回復(fù)音樂消息

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

參數(shù) 是否必須

說明

ToUserName 是

接收方帳號（收到的OpenID）

FromUserName是

開發(fā)者微信號

CreateTime 是

消息創(chuàng)建時(shí)間（整型）

MsgType 是

music

Title 否

音樂標(biāo)題

Description 否

音樂描述

MusicURL 否

音樂鏈接

HQMusicUrl 否

高質(zhì)量音樂鏈接，WIFI環(huán)境優(yōu)先使用該鏈接播放音樂

ThumbMediaId是

縮略圖的媒體id，通過上傳多媒體文件，得到的id

回復(fù)圖文消息

<xml>

<ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[fromUser]]></FromUserName>

<CreateTime>12345678</CreateTime>

<MsgType><![CDATA[news]]></MsgType>

<ArticleCount>2</ArticleCount>

<Articles>

<item>

<Title><![CDATA[title1]]></Title>

<Description><![CDATA[description1]]></Description>

<PicUrl><![CDATA[picurl]]></PicUrl>

<Url><![CDATA[url]]></Url>

</item>

<item>

<Title><![CDATA[title]]></Title>

<Description><![CDATA[description]]></Description>

<PicUrl><![CDATA[picurl]]></PicUrl>

<Url><![CDATA[url]]></Url>

</item>

</Articles>

</xml>

參數(shù)

是否必須

說明

ToUserName

是

接收方帳號（收到的OpenID）

FromUserName

是

開發(fā)者微信號

CreateTime

是

消息創(chuàng)建時(shí)間（整型）

MsgType

是

news

ArticleCount

是

圖文消息個(gè)數(shù)，限制為10條以內(nèi)

Articles

是

多條圖文消息信息，默認(rèn)第一個(gè)item為大圖，注意

如果圖文數(shù)超過10,則將會(huì)無響應(yīng)

Title

否

圖文消息標(biāo)題

Description

否

圖文消息描述

PicUrl

否

圖片鏈接，支持JPG、PNG格式，較好的效果為大

圖360*200，

小圖200*200

Url

否

點(diǎn)擊圖文消息跳轉(zhuǎn)鏈接

發(fā)送客服消息

出自微信公眾平臺(tái)開發(fā)者文檔

當(dāng)用戶主動(dòng)發(fā)消息給公眾號的時(shí)候（包括發(fā)送信息、點(diǎn)擊自定義菜單、訂閱事件、掃描二維碼事件、支付成功事件、用戶維權(quán)），微信將會(huì)把消息數(shù)據(jù)推送給開發(fā)者，開發(fā)者在一段時(shí)間內(nèi)（目前修改為48小時(shí)）可以調(diào)用客服消息接口，通過POST一個(gè)JSON數(shù)據(jù)包來發(fā)送消息給普通用戶，在48小時(shí)內(nèi)不限制發(fā)送次數(shù)。此接口主要用于客服等有人工消息處理環(huán)節(jié)的功能，方便開發(fā)者為用戶提供更加優(yōu)質(zhì)的服務(wù)。

接口調(diào)用請求說明

http請求方式：POST

/cgi-bin/message/custom/sendfaccess_token二ACCESS_TOKEN

各消息類型所需的JSON數(shù)據(jù)包如下。

發(fā)送文本消息

（

〃touser〃：〃OPENID〃，

〃 工 〃-〃工_工〃

msgtype:text,

"text":

（

"content":"HelloWorld"

}

}

參數(shù)

是否必須

說明

access_token

是

調(diào)用接口憑證

touser

是

普通用戶openid

msgtype

是

消息類型，text

content

是

文本消息內(nèi)容

發(fā)送圖片消息

(

〃touser〃：〃OPENID〃，

〃 一」〃一〃?……〃

msgtype:image,

〃?〃一image:

(

〃media_id〃：〃MEDIA_ID〃

}

}

參數(shù)

是否必須

說明

access_token

是

調(diào)用接口憑證

touser

是

普通用戶openid

msgtype

是

消息類型，image

media_id

是

發(fā)送的圖片的媒體ID

發(fā)送語音消息

(

〃touser〃：〃OPENID〃,

〃 一」一〃一〃_

msgtype:voice,

〃?〃一voice:

(

〃media_id〃：〃MEDIA_ID〃

}

}

參數(shù)

是否必須

說明

access_token

是

調(diào)用接口憑證

touser

是

普通用戶openid

msgtype

是

消息類型，voice

media_id

是

發(fā)送的語音的媒體ID

發(fā)送視頻消息

(

〃touser〃：〃OPENID〃,

〃 工 〃-〃 —一〃

msgtype:video,

〃 ?一1…〃一

video:

(

〃media_id〃：〃MEDIA_ID〃，

〃thumb_media_id〃：〃MEDIA_ID〃,

"title〃：〃TITLE”,

〃description〃：〃DESCRIPTION〃

}

}

參數(shù)

是否必須

說明

access_token

是

調(diào)用接口憑證

touser

是

普通用戶openid

msgtype

是

消息類型，video

media_id

是

發(fā)送的視頻的媒體ID

thumb_media_id

是

縮略圖的媒體ID

title

否

視頻消息的標(biāo)題

description

否

視頻消息的描述

發(fā)送音樂消息

(

"touser”:"OPENID”,

〃 一」〃一〃 ?一〃

msgtype:music,

〃?〃一

music：

(

"title":"MUSIC_TITLE",

"description”:"MUSIC_DESCRIPTION”,

"musicurl":"MUSIC_URL",

〃hqmusicurl〃：〃HQ_MUSIC_URL〃，

"thumb_media_id":"THUMB_MEDIA_ID"

}

}

參數(shù)

是否必須

說明

access_token

是

調(diào)用接口憑證

touser

是

普通用戶openid

msgtype

是

消息類型，music

title

否

音樂標(biāo)題

description

否

音樂描述

musicurl

是

音樂鏈接

hqmusicurl

是

高品質(zhì)音樂鏈接，wifi環(huán)境優(yōu)先使用該鏈接播放音樂

thumb_media_id

是

縮略圖的媒體ID

發(fā)送圖文消息

圖文消息條數(shù)限制在10條以內(nèi)，注意，如果圖文數(shù)超過10,則將會(huì)無響應(yīng)。

(

〃touser〃：〃OPENID〃，

〃 一」一〃一〃一_一〃

msgtype:news,

〃〃一「news:{

"articles":[

(

"title":"HappyDay",

"description":"IsReallyAHappyDay",

"url":"URL",

"picurl":"PIC_URL"

},

(

"title":"HappyDay",

"description":"IsReallyAHappyDay",

"url":"URL",

"picurl":"PIC_URL"

}

]

}

}

參數(shù)

是否必須

說明

access_token

是

調(diào)用接口憑證

touser

是

普通用戶openid

msgtype

是

消息類型，news

title

否

標(biāo)題

description

否

描述

url

否

點(diǎn)擊后跳轉(zhuǎn)的鏈接

picurl

否

圖文消息的圖片鏈接，支持JPG、PNG格式，較好的效果為大圖640*320，小圖80*80

高級群發(fā)接口在公眾平臺(tái)網(wǎng)站上，為訂閱號提供了每天一條的群發(fā)權(quán)限，為服務(wù)號提供每月(自然月)4條的群發(fā)權(quán)限。而對于某些具備開發(fā)能力的公眾號運(yùn)營者，可以通過高級群發(fā)接口，實(shí)現(xiàn)更靈活的群發(fā)能力。

請注意：

1、 對于認(rèn)證訂閱號，群發(fā)接口每天可成功調(diào)用1次，此次群發(fā)可選擇發(fā)送給全部用戶或某個(gè)分組；

2、 對于認(rèn)證服務(wù)號雖然開發(fā)者使用高級群發(fā)接口的每日調(diào)用限制為100次，但是用戶每月只能接收4條，無論在公眾平臺(tái)網(wǎng)站上，還是使用接口群發(fā)，用戶每月只能接收4條群發(fā)消息，多于4條的群發(fā)將對該用戶發(fā)送失??；

3、 具備微信支付權(quán)限的公眾號，在使用群發(fā)接口上傳、群發(fā)圖文消息類型時(shí)，可使用＜a＞標(biāo)簽加入外鏈；

4、 開發(fā)者可以使用預(yù)覽接口校對消息樣式和排版，通過預(yù)覽接口可發(fā)送編輯好的消息給指定用戶校驗(yàn)效果。

上傳圖文消息素材【訂閱號與服務(wù)號認(rèn)證后均可用】

接口調(diào)用請求說明

http請求方式：POST

POST數(shù)據(jù)說明

POST數(shù)據(jù)示例如下：

(

"articles":[

(

"thumb_media_id":"qI6_Ze_6PtV7svjolgs-rN6stStuHIjs9_DidOHaj0Q-mwvBelO

XCFZiq2OsIU-p",

author:xxx,

"title":"HappyDay",

content_source_url:,"content":"content","digest":"digest",

〃—l一_-一一n_〃一〃r〃

show_cover_pic:1

},

(

"thumb_media_id":"qI6_Ze_6PtV7svjolgs-rN6stStuHIjs9_DidOHaj0Q-mwvBelO

XCFZiq2OsIU-p",

author:xxx,

"title":"HappyDay",

content_source_url:,

"content":"content",

"digest":"digest",

〃 1 ? 〃 〃c〃

show_cover_pic:0

]

}

參數(shù)

是否必須

說明

Articles

是

圖文消息，一個(gè)圖文消息支持1到10條圖文

thumb_media_id

是

圖文消息縮略圖的media_id，可以在基礎(chǔ)支持-上傳多媒體文件接口中獲得

author

否

圖文消息的作者

title

是

圖文消息的標(biāo)題

content_source_url

否

在圖文消息頁面點(diǎn)擊“閱讀原文”后的頁面

content

是

圖文消息頁面的內(nèi)容，支持HTML標(biāo)簽

digest

否

圖文消息的描述

show_cover_pic

否

是否顯示封面，1為顯示，0為不顯示

返回說明

返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）：

（

〃」一〃一〃一_一〃

type:news,

〃media_id〃：〃CsEf3ldqkAYJAU6EJeIkStVDSvffUJ54vqbThMgplD-VJXXof6ctX5fI6

-aYyUiQ”,

〃created_at〃：1391857799

}

參數(shù)

說明

type

媒體文件類型，分別有圖片（image）、語音（voice）、視頻（video）和縮略圖（thumb），次數(shù)為news，即圖文消息

Media_id

媒體文件/圖文消息上傳后獲取的唯一標(biāo)識(shí)

created_at

媒體文件上傳時(shí)間

錯(cuò)誤時(shí)微信會(huì)返回錯(cuò)誤碼等信息，請根據(jù)錯(cuò)誤碼查詢錯(cuò)誤信息：全局返回碼說明

根據(jù)分組進(jìn)行群發(fā)【訂閱號與服務(wù)號認(rèn)證后均可用】

接口調(diào)用請求說明

http請求方式：POST

POST數(shù)據(jù)說明

POST數(shù)據(jù)示例如下：

圖文消息(注意圖文消息的media_id需要通過上述方法來得到)：

(

"filter":(

"is_to_all":false

〃一一 」〃一〃C〃

group_id:2

},

〃〃一「

mpnews:{

〃media_id〃：〃123dsdajkasd231jhksad〃

},

〃」〃一〃〃

msgtype:mpnews

}

文本：

(

"filter":(

"is_to_all":false

〃一一 〃一〃c〃

group_id:2

},

"text":(

〃content〃：〃CONTENT〃

},

〃 —— 一一〃-〃土一土〃

msgtype:text

}

語音(注意此處media_id需通過基礎(chǔ)支持中的上傳下載多媒體文件來得到)：

(

"filter":(

"is_to_all":false

〃一一 」〃一〃C〃

group_id:2

},

〃?〃一「

voice:{

"media_id":"123dsdajkasd231jhksad"

},

〃」〃一〃?〃

msgtype:voice

}

圖片(注意此處media_id需通過基礎(chǔ)支持中的上傳下載多媒體文件來得到)：

(

"filter":(

〃is_to_all〃：false

〃 ?一1〃、〃C〃

group_id:2

},

〃?〃一「

image:{

〃media_id〃：〃123dsdajkasd231jhksad〃

},

〃 一」〃一〃?……〃

msgtype：image

}

視頻

請注意，此處視頻的media_id需通過POST請求到下述接口特別地得到：

/cgi-bin/media/uploadvideofaccess_token

二accesstokEN

POST數(shù)據(jù)如下(此處media_id需通過基礎(chǔ)支持中的上傳下載多媒體文件來得

到)：

(

〃 1. ?1〃一

media_id:

〃rF4UdIMfYK3efUfyoddYRMU50zMiRmmt_l0kszupYh_SzrcW5Gaheq05p_lHu0TQ〃，

"title〃：〃TITLE”,

"description":"Description"

}

返回將為

(

type:video,

"media_id”:"IhdaAQXuvJtGzwwc0abfXnzeezf00NgPK6AQYShD8RQYMTtfzbLdBIQkQ

ziv2XJc",

"created_at":1398848981

}

然后，POST下述數(shù)據(jù)(將media_id改為上一步中得到的media_id)，即可進(jìn)行

發(fā)送

(

"filter":(

"is_to_all":false

〃 ?

group_id:2

},

"mpvideo":(

"media_id”:"IhdaAQXuvJtGzwwc0abfXnzeezf00NgPK6AQYShD8RQYMTtfzbLdBIQkQ

ziv2XJc”,

},

msgtype:mpvideo

參數(shù)

是否必須

說明

Filter

是

用于設(shè)定圖文消息的接收者

is_to_all

否

用于設(shè)定是否向全部用戶發(fā)送，值為true或false，選擇true該消息群發(fā)給所有用戶，選擇false可根據(jù)group_id發(fā)送給指定群組的用戶

Group_id

否

群發(fā)到的分組的group_id，參加用戶管理中用戶分組接口，若is_to_all值為true，可不填寫group_id

Mpnews

是

用于設(shè)定即將發(fā)送的圖文消息

Media_id

是

用于群發(fā)的消息的media_id

msgtype

是

群發(fā)的消息類型，圖文消息為mpnews，文本消息為text，語音為voice，音樂為music，圖片為image，視頻為video

Title

否

消息的標(biāo)題

description

否

消息的描述

Thumb_media_id

是

視頻縮略圖的媒體ID

返回說明

返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）：

（

"errcode〃：0,

"errmsg〃：〃sendjobsubmissionsuccess",

〃msg_id〃：34182

}

參數(shù)

說明

type

媒體文件類型，分別有圖片（image）、語音（voice）、視頻（video）和縮略圖（thumb），圖文消息為news

errcode

錯(cuò)誤碼

errmsg

錯(cuò)誤信息

msg_id

消息ID

請注意：在返回成功時(shí)，意味著群發(fā)任務(wù)提交成功，并不意味著此時(shí)群發(fā)已經(jīng)結(jié)束，所以，仍有可能在后續(xù)的發(fā)送過程中出現(xiàn)異常情況導(dǎo)致用戶未收到消息，如消息有時(shí)會(huì)進(jìn)行審核、服務(wù)器不穩(wěn)定等。此外，群發(fā)任務(wù)一般需要較長的時(shí)間才能全部發(fā)送完畢，請耐心等待。

錯(cuò)誤時(shí)微信會(huì)返回錯(cuò)誤碼等信息，請根據(jù)錯(cuò)誤碼查詢錯(cuò)誤信息：全局返回碼說明

根據(jù)OpenlD列表群發(fā)【訂閱號不可用，服務(wù)號認(rèn)證后可用】

接口調(diào)用請求說明

http請求方式：POST

POST數(shù)據(jù)說明

POST數(shù)據(jù)示例如下：

圖文消息(注意圖文消息的media_id需要通過上述方法來得到)：(

"touser":[

"OPENID1",

"OPENID2"

],

〃〃一「

mpnews:{

〃media_id〃：〃123dsdajkasd231jhksad〃

},

〃」〃一〃〃

msgtype:mpnews

}

文本：

(

"touser":[

"OPENID1",

"OPENID2"

],

"msgtype”:"text”,

"text":("content":"hellofromboxer."}

}

語曰：

(

"touser":[

"OPENID1",

"OPENID2"

],

〃?〃一「

voice:{

"media_id”:"mLxl6paC7z2Tl-NJT64yzJve8T9c8u9K2x-Ai6Ujd4lIH9IBuF6-2r66mamn_gIT"

},

〃」〃一〃?〃

msgtype:voice

}

圖片：

(

"touser〃：["OPENID1","OPENID2"

],

〃?〃一「image：!

"media_id":"BTgN0opcW3Y5zV_ZebbsD3NFKRWf6cb7OPswPi9Q83fOJHK2P67dzxn11

Cp7THat"

},

〃 一」〃一〃?……〃

msgtype:image

}

視頻：

請注意，此處視頻的media_id需通過POST請求到下述接口特別地得到：

/cgi-bin/media/uploadvideoPaccesstoken

二ACCESSTOKEN

POST數(shù)據(jù)如下(此處media_id需通過基礎(chǔ)支持中的上傳下載多媒體文件來得到)：

(

〃 1. ?1〃一

media_id:

"rF4UdIMfYK3efUfyoddYRMU50zMiRmmt_l0kszupYh_SzrcW5Gaheq05p_lHuOTQ",

"title":"TITLE",

"description":"Description"

}

返回將為

(

type:video,

"media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",

"created_at":1398848981

}

然后，POST下述數(shù)據(jù)(將media_id改為上一步中得到的media_id)，即可進(jìn)行發(fā)送

(

"touser":[

"OPENID1",

"OPENID2"

],

"video":(

"media_id":"123dsdajkasd231jhksad",

"title":"TITLE",

"description〃：〃DESCRIPTION”

},

〃 工 〃-〃 —一〃

msgtype:video

}

參數(shù)

是否必須

說明

touser

是

填寫圖文消息的接收者，一串OpenlD列表，OpenlD最少個(gè)，最多10000個(gè)

mpnews

是

用于設(shè)定即將發(fā)送的圖文消息

media_id

是

用于群發(fā)的圖文消息的media_id

msgtype

是

群發(fā)的消息類型，圖文消息為mpnews，文本消息為text，語音為voice，音樂為music，圖片為image，視頻為video

title

否

消息的標(biāo)題

description

否

消息的描述

thumb_media_id

是

視頻縮略圖的媒體ID

返回說明

返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）：

(

"errcode":0,

"errmsg":"sendjobsubmissionsuccess",

"msg_id":34182

}

參數(shù)

說明

type

媒體文件類型，分別有圖片（image）、語音（voice）、視頻（video）和縮略圖（thumb），次數(shù)為news，即圖文消息

errcode

錯(cuò)誤碼

errmsg

錯(cuò)誤信息

msg_id

消息ID

請注意：在返回成功時(shí)，意味著群發(fā)任務(wù)提交成功，并不意味著此時(shí)群發(fā)已經(jīng)結(jié)束，所以，仍有可能在后續(xù)的發(fā)送過程中出現(xiàn)異常情況導(dǎo)致用戶未收到消息，

如消息有時(shí)會(huì)進(jìn)行審核、服務(wù)器不穩(wěn)定等。此外，群發(fā)任務(wù)一般需要較長的時(shí)間才能全部發(fā)送完畢，請耐心等待。

錯(cuò)誤時(shí)微信會(huì)返回錯(cuò)誤碼等信息，請根據(jù)錯(cuò)誤碼查詢錯(cuò)誤信息：全局返回碼說明

刪除群發(fā)【訂閱號與服務(wù)號認(rèn)證后均可用】

接口調(diào)用請求說明

http請求方式：POST

POST數(shù)據(jù)說明

POST數(shù)據(jù)示例如下：

(

〃msg_id〃：30124

}

參數(shù)

是否必須

說明

msg_id

是

發(fā)送出去的消息ID

請注意，只有已經(jīng)發(fā)送成功的消息才能刪除刪除消息只是將消息的圖文詳情頁失效，已經(jīng)收到的用戶，還是能在其本地看到消息卡片。另外，刪除群發(fā)消息只能刪除圖文消息和視頻消息，其他類型的消息一經(jīng)發(fā)送，無法刪除。

返回說明

返回?cái)?shù)據(jù)示例(正確時(shí)的JSON返回結(jié)果)：

(

"errcode〃：0,

errmsg:ok

}

參數(shù)

說明

errcode

錯(cuò)誤碼

errmsg

錯(cuò)誤信息

錯(cuò)誤時(shí)微信會(huì)返回錯(cuò)誤碼等信息，請根據(jù)錯(cuò)誤碼查詢錯(cuò)誤信息：全局返回碼說明

預(yù)覽接口【訂閱號與服務(wù)號認(rèn)證后均可用】

開發(fā)者可通過該接口發(fā)送消息給指定用戶，在手機(jī)端查看消息的樣式和排版。

接口調(diào)用請求說明

http請求方式：POST

POST數(shù)據(jù)說明

POST數(shù)據(jù)示例如下：

圖文消息（其中media_id與根據(jù)分組群發(fā)中的media_id相同）：

（

〃touser〃：〃OPENID〃，

〃〃一「

mpnews:{

〃media_id〃：〃123dsdajkasd231jhksad〃

},

〃」〃一〃〃

msgtype:mpnews

}

文本：

（

〃touser〃：〃OPENID〃，

"text":（

〃content〃：〃CONTENT〃

},

〃 —— 一一〃-〃土一土〃

msgtype:text

}

語音（其中media_id與根據(jù)分組群發(fā)中的media_id相同）：

（

"touser〃：〃OPENID”,

〃?〃一「

voice:{

"media_id":"123dsdajkasd231jhksad"

},

〃」〃一〃?〃msgtype:voice

}

圖片（其中media_id與根據(jù)分組群發(fā)中的media_id相同）：

（

"touser":"OPENID",

〃?〃一「image:{

"media_id":"123dsdajkasd231jhksad"

},

〃」〃一〃?〃msgtype：image

}

視頻（其中media_id與根據(jù)分組群發(fā)中的media_id相同）：

"touser〃：〃OPENID”,

"mpvideo〃：{"media_id":"IhdaAQXuvJtGzwwc0abfXnzeezf00NgPK6AQYShD8RQY

MTtfzbLdBIQkQziv2XJc”,

},

msgtype:mpvideo

}

參數(shù)

說明

touser

接收消息用戶對應(yīng)該公眾號的openid

msgtype

群發(fā)的消息類型，圖文消息為mpnews，文本消息為text，語音為voice，音樂為music，圖片為image，視頻為video

Media_id

用于群發(fā)的消息的media_id

content

發(fā)送文本消息時(shí)文本的內(nèi)容

返回說明

返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）：

（

"errcode":0,

"errmsg":"sendjobsubmissionsuccess",

"msg_id":34182

參數(shù)

說明

errcode

錯(cuò)誤碼

errmsg

錯(cuò)誤信息

msg_id

消息ID

查詢?nèi)喊l(fā)消息發(fā)送狀態(tài)【訂閱號與服務(wù)號認(rèn)證后均可用】

接口調(diào)用請求說明

http請求方式：POST

/cgi-bin/message/mass/get?accesstoken=ACCES

STOKEN

POST數(shù)據(jù)說明

POST數(shù)據(jù)示例如下：

(

〃msg_id〃：〃201053012〃

}

參數(shù)

說明

msg_id

群發(fā)消息后返回的消息id

返回說明

返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）：

（

〃msg_id〃：201053012,

〃msg_status〃：〃SEND_SUCCESS〃

}

參數(shù)

說明

msg_id

群發(fā)消息后返回的消息id

msg_status

消息發(fā)送后的狀態(tài)，SEND_SUCCESS表示發(fā)送成功

事件推送群發(fā)結(jié)果

由于群發(fā)任務(wù)提交后，群發(fā)任務(wù)可能在一定時(shí)間后才完成，因此，群發(fā)接口調(diào)用時(shí)，僅會(huì)給出群發(fā)任務(wù)是否提交成功的提示，若群發(fā)任務(wù)提交成功，則在群發(fā)任務(wù)結(jié)束時(shí)，會(huì)向開發(fā)者在公眾平臺(tái)填寫的開發(fā)者URL(callbackURL)推送事件。

推送的XML結(jié)構(gòu)如下(發(fā)送成功時(shí))：

<xml>

<ToUserName><![CDATA[gh_3e8adccde292]]></ToUserName>

<FromUserName><![CDATA[oR5Gjjl_eiZoUpGozMo7dbBJ362A]]></FromUserName>

<CreateTime>1394524295</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[MASSSENDJOBFINISH]]></Event>

<MsgID>1988</MsgID>

<Status><![CDATA[sendsuccess]]></Status>

<TotalCount>100</TotalCount>

<FilterCount>80</FilterCount>

<SentCount>75</SentCount>

<ErrorCount>5</ErrorCount>

</xml>

ToUserName

公眾號的微信號

FromUserName

公眾號群發(fā)助手的微信號，為mphelper

CreateTime

創(chuàng)建時(shí)間的時(shí)間戳

MsgType

消息類型，此處為event

Event

事件信息，此處為MASSSENDJOBFINISH

MsgID

群發(fā)的消息ID

Status

群發(fā)的結(jié)構(gòu)，為“sendsuccess”或“sendfail”或“err(num)”。但sendsuccess時(shí)，也有可能因用戶拒收公眾號的消息、系統(tǒng)錯(cuò)誤等原因造成少量用戶接收失敗。err(num)是審核失敗的具體原因，可能的情況如下：

err(10001),//涉嫌廣告err(20001),//涉嫌政治err(20004),〃涉嫌社會(huì)err(20002),〃涉嫌色情err(20006),//涉嫌違法犯罪

err(20008),//涉嫌欺詐err(20013),//涉嫌版權(quán)err(22000),〃涉嫌互推(互相宣傳)err(21000),〃涉嫌其他

TotalCount

group_id下粉絲數(shù)；或者openid_list中的粉絲數(shù)

FilterCount

過濾(過濾是指特定地區(qū)、性別的過濾、用戶設(shè)置拒收的過濾，用戶接收已超4條的過濾)后，準(zhǔn)備發(fā)送的粉絲數(shù)，原則上，F(xiàn)ilterCount=SentCount+ErrorCount

SentCount

發(fā)送成功的粉絲數(shù)

ErrorCount

發(fā)送失敗的粉絲數(shù)

模板消息接口

模板消息僅用于公眾號向用戶發(fā)送重要的服務(wù)通知，只能用于符合其要求的服務(wù)場景中，如信用卡刷卡通知，商品購買成功通知等。不支持廣告等營銷類消息以及其它所有可能對用戶造成騷擾的消息。

關(guān)于使用規(guī)則，請注意：

1、 所有服務(wù)號都可以在功能->添加功能插件處看到申請模板消息功能的入口，但只有認(rèn)證后的服務(wù)號才可以申請模板消息的使用權(quán)限并獲得該權(quán)限；

2、 需要選擇公眾賬號服務(wù)所處的2個(gè)行業(yè)，每月可更改1次所選行業(yè)；

3、 在所選擇行業(yè)的模板庫中選用已有的模板進(jìn)行調(diào)用；

4、 每個(gè)賬號可以同時(shí)使用15個(gè)模板。

5、 當(dāng)前每個(gè)模板的日調(diào)用上限為100000次【2014年11月18日將接口調(diào)用頻率從默認(rèn)的日10000次提升為日100000次，可在MP登錄后的開發(fā)者中心查看】。關(guān)于接口文檔，請注意：

1、 模板消息調(diào)用時(shí)主要需要模板ID和模板中各參數(shù)的賦值內(nèi)容；

2、 模板中參數(shù)內(nèi)容必須以".DATA〃結(jié)尾，否則視為保留字；

3、模板保留符號〃{{}}〃。

目錄

1設(shè)置所屬行業(yè)

2獲得模板ID

3發(fā)送模板消息

4事件推送

設(shè)置所屬行業(yè)

設(shè)置行業(yè)可在MP中完成，每月可修改行業(yè)1次，賬號僅可使用所屬行業(yè)中相關(guān)的模板，為方便第三方開發(fā)者，提供通過接口調(diào)用的方式來修改賬號所屬行業(yè)，具體如下：接口調(diào)用請求說明

http請求方式：POST

/cgi-bin/template/api_set_industry?access_token=ACCESS

_TOKEN

POST數(shù)據(jù)說明

POST數(shù)據(jù)示例如下：

(

〃industry_id1〃:〃1〃，

〃industry_id2〃:〃4〃

}

參數(shù)說明

參數(shù)

是否必須

說明

industry_id1

是

公眾號模板消息所屬行業(yè)編號

industry_id2

是

公眾號模板消息所屬行業(yè)編號

行業(yè)代碼查詢

主行業(yè)

副行業(yè)

代碼

IT科技

互聯(lián)網(wǎng)/電子商務(wù)

1

IT科技

IT軟件與服務(wù)

2

IT科技

IT硬件與設(shè)備

3

IT科技

電子技術(shù)

4

IT科技

通信與運(yùn)營商

5

IT科技

網(wǎng)絡(luò)游戲

6

金融業(yè)

銀行

7

金融業(yè)

基金|理財(cái)|信托

8

金融業(yè)

保險(xiǎn)

9

餐飲

餐飲

10

酒店旅游

酒店

11

酒店旅游

旅游

12

運(yùn)輸與倉儲(chǔ)

快遞

13

運(yùn)輸與倉儲(chǔ)

物流

14

運(yùn)輸與倉儲(chǔ)

倉儲(chǔ)

15

教育

培訓(xùn)

16

教育

院校

17

政府與公共事業(yè)

學(xué)術(shù)科研

18

政府與公共事業(yè)

交警

19

政府與公共事業(yè)

博物館

20

政府與公共事業(yè)

公共事業(yè)|非盈利機(jī)構(gòu)

21

醫(yī)藥護(hù)理

醫(yī)藥醫(yī)療

22

醫(yī)藥護(hù)理

護(hù)理美容

23

醫(yī)藥護(hù)理

保健與衛(wèi)生

24

交通工具

汽車相關(guān)

25

交通工具

摩托車相關(guān)

26

交通工具

火車相關(guān)

27

交通工具

飛機(jī)相關(guān)

28

房地產(chǎn)

建筑

29

房地產(chǎn)

物業(yè)

30

消費(fèi)品

消費(fèi)品

31

商業(yè)服務(wù)

法律

32

商業(yè)服務(wù)

會(huì)展

33

商業(yè)服務(wù)

中介服務(wù)

34

商業(yè)服務(wù)

認(rèn)證

35

商業(yè)服務(wù)

審計(jì)

36

文體娛樂

傳媒

37

文體娛樂

體育

38

文體娛樂

娛樂休閑

39

印刷

印刷

40

其它

其它

41

獲得模板ID

從行業(yè)模板庫選擇模板到賬號后臺(tái)，獲得模板ID的過程可在MP中完成。為方便

第

三方開發(fā)者，提供通過接口調(diào)用的方式來修改賬號所屬行業(yè)，具體如下：

接口調(diào)用請求說明

http請求方式：POST

/cgi-bin/template/api_add_template

?

access_token=ACCESS_TOKEN

POST數(shù)據(jù)說明

POST數(shù)據(jù)示例如下：

(

〃template_id_short〃：〃TM00015"

}

參數(shù)說明

參數(shù)

是否必須

說明

template_id_short

是

模板庫中模板的編號，有“TM**”和“OPENTMTM**”等形式

返回碼說明

在調(diào)用模板消息接口后，會(huì)返回JSON數(shù)據(jù)包。正常時(shí)的返回JSON數(shù)據(jù)包示例：

(

"errcode〃：0,

errmsg:ok,

"template_id":"Doclyl5uP7Aciu-qZ7mJNPtWkbkYnWBWVja26EGbNyk"

}

發(fā)送模板消息

接口調(diào)用請求說明

http請求方式：POST

HYPERLINK"/cgi-bin/message/template/sendfacc