微信企業(yè)號(hào)開發(fā)之如何接收消息
作者：51CTO整理
將應(yīng)用設(shè)置在回調(diào)模式時(shí)，企業(yè)可以通過(guò)回調(diào)URL接收員工回復(fù)的消息，以及員工關(guān)注、點(diǎn)擊菜單、上報(bào)地理位置等事件。在接收到事件后，企業(yè)可以發(fā)送被動(dòng)響應(yīng)消息，實(shí)現(xiàn)員工與企業(yè)的互動(dòng)。
將應(yīng)用設(shè)置在回調(diào)模式時(shí)，企業(yè)可以通過(guò)回調(diào)URL接收員工回復(fù)的消息，以及員工關(guān)注、點(diǎn)擊菜單、上報(bào)地理位置等事件。
在接收到事件后，企業(yè)可以發(fā)送被動(dòng)響應(yīng)消息，實(shí)現(xiàn)員工與企業(yè)的互動(dòng)。
注意，企業(yè)在接收消息，以及發(fā)送被動(dòng)響應(yīng)消息時(shí)，消息體都以AES方式加密，以保證傳輸?shù)陌踩＞唧w可參考'建立連接'中的'回調(diào)模式'一節(jié)。
一、關(guān)注與取消關(guān)注
員工在關(guān)注企業(yè)號(hào)時(shí)，首先要與企業(yè)通訊錄中的帳號(hào)綁定；如果企業(yè)開啟了二次驗(yàn)證，那么在綁定成功后還需要經(jīng)過(guò)企業(yè)的驗(yàn)證，才可以關(guān)注成功。
1、員工與通訊錄中的帳號(hào)綁定
員工關(guān)注企業(yè)號(hào)時(shí)，會(huì)根據(jù)員工的微信號(hào)、微信綁定的手機(jī)或郵箱，與企業(yè)通訊錄的帳號(hào)匹配。如果匹配到，則綁定成功；否則會(huì)提示員工輸入手機(jī)號(hào)或郵箱，驗(yàn)證成功后再與企業(yè)通訊錄中的帳號(hào)匹配。注意，員工的微信版本需要在5.4以上，目前僅支持iOS、Android兩個(gè)平臺(tái)。
2、二次驗(yàn)證
企業(yè)在開啟二次驗(yàn)證時(shí)，必須填寫企業(yè)二次驗(yàn)證頁(yè)面的url。當(dāng)員工綁定通訊錄中的帳號(hào)后，會(huì)收到一條圖文消息，引導(dǎo)員工到企業(yè)的驗(yàn)證頁(yè)面驗(yàn)證身份，企業(yè)在員工驗(yàn)證成功后，調(diào)用如下接口即可讓員工關(guān)注成功。
- 請(qǐng)求說(shuō)明
Http請(qǐng)求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/user/authsucc?access_token=ACCESS_TOKEN&userid=USERID
- 參數(shù)說(shuō)明
| 參數(shù) | 必須 | 說(shuō)明 |
|---|---|---|
| access_token | 是 | 調(diào)用接口憑證 |
| userid | 是 | 員工UserID |
- 權(quán)限說(shuō)明
管理員須擁有userid對(duì)應(yīng)員工的管理權(quán)限。
- 返回結(jié)果
- {
- "errcode": "0",
- "errmsg": "ok"
- }
3、關(guān)注/取消關(guān)注事件的推送
員工關(guān)注、取消關(guān)注企業(yè)號(hào)的事件，會(huì)推送到每個(gè)應(yīng)用在管理端設(shè)置的URL；特別的，默認(rèn)企業(yè)小助手可以用于獲取整個(gè)企業(yè)號(hào)的關(guān)注狀況。（以下假設(shè)該URL為http://api.3dept.com）。
- 請(qǐng)求說(shuō)明
Http請(qǐng)求方式: POST
http://api.3dept.com/?signature=ASDFQWEXZCVAQFASDFASDFSS×tamp=13500001234&nonce=123412323
- 參數(shù)說(shuō)明
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[UserID]]></FromUserName>
- <CreateTime>1348831860</CreateTime>
- <MsgType><![CDATA[event]]></MsgType>
- <Event><![CDATA[subscribe]]></Event>
- <AgentID>1</AgentID>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 企業(yè)號(hào)CorpID |
| FromUserName | 員工UserID |
| CreateTime | 消息創(chuàng)建時(shí)間 （整型） |
| MsgType | 消息類型，此時(shí)固定為：event |
| Event | 事件類型，subscribe(訂閱)、unsubscribe(取消訂閱) |
| AgentID | 企業(yè)應(yīng)用的id，整型。可在應(yīng)用的設(shè)置頁(yè)面獲取；如果id為0，則表示是整個(gè)企業(yè)號(hào)的關(guān)注/取消關(guān)注事件 |
#p#
二、接收普通消息
普通消息是指員工向企業(yè)號(hào)應(yīng)用發(fā)送的消息，包括文本、圖片、語(yǔ)音、視頻、地理位置等類型。
- text消息
- <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>
- <AgentID>1</AgentID>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 企業(yè)號(hào)CorpID |
| FromUserName | 員工UserID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：text |
| Content | 文本消息內(nèi)容 |
| MsgId | 消息id，64位整型 |
| AgentID | 企業(yè)應(yīng)用的id，整型。可在應(yīng)用的設(shè)置頁(yè)面查看 |
- image消息
- <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>
- <AgentID>1</AgentID>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 企業(yè)號(hào)CorpID |
| FromUserName | 員工UserID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：text |
| Content | 文本消息內(nèi)容 |
| MsgId | 消息id，64位整型 |
| AgentID | 企業(yè)應(yīng)用的id，整型。可在應(yīng)用的設(shè)置頁(yè)面查看 |
- image消息
- <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>
- <AgentID>1</AgentID>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 企業(yè)號(hào)CorpID |
| FromUserName | 員工UserID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：image |
| PicUrl | 圖片鏈接 |
| MediaId | 圖片消息媒體id，可以調(diào)用多媒體文件下載接口拉取數(shù)據(jù)。 |
| MsgId | 消息id，64位整型 |
| AgentID | 企業(yè)應(yīng)用的id，整型。可在應(yīng)用的設(shè)置頁(yè)面查看 |
- voice消息
- <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>
- <AgentID>1</AgentID>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 企業(yè)號(hào)CorpID |
| FromUserName | 員工UserID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：voice |
| MediaId | 語(yǔ)音消息媒體id，可以調(diào)用多媒體文件下載接口拉取數(shù)據(jù)。 |
| Format | 語(yǔ)音格式，如amr，speex等 |
| MsgId | 消息id，64位整型 |
| AgentID | 企業(yè)應(yīng)用的id，整型。可在應(yīng)用的設(shè)置頁(yè)面查看 |
- video消息
- <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>
- <AgentID>1</AgentID>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 企業(yè)號(hào)CorpID |
| FromUserName | 員工UserID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：video |
| MediaId | 視頻消息媒體id，可以調(diào)用多媒體文件下載接口拉取數(shù)據(jù)。 |
| ThumbMediaId | 視頻消息縮略圖的媒體id，可以調(diào)用多媒體文件下載接口拉取數(shù)據(jù)。 |
| MsgId | 消息id，64位整型 |
| AgentID | 企業(yè)應(yīng)用的id，整型。可在應(yīng)用的設(shè)置頁(yè)面查看 |
- location消息
- <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>
- <AgentID>1</AgentID>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 企業(yè)號(hào)CorpID |
| FromUserName | 員工UserID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：location |
| Location_X | 地理位置緯度 |
| Location_Y | 地理位置經(jīng)度 |
| Scale | 地圖縮放大小 |
| Label | 地理位置信息 |
| MsgId | 消息id，64位整型 |
| AgentID | 企業(yè)應(yīng)用的id，整型。可在應(yīng)用的設(shè)置頁(yè)面查看 |
#p#
三、接收事件
事件是指員工在企業(yè)號(hào)上的某些操作行為，比如關(guān)注、上報(bào)地理位置、點(diǎn)擊菜單等。（關(guān)注事件請(qǐng)參考’關(guān)注與取消關(guān)注’）
1、菜單事件推送
員工點(diǎn)擊自定義菜單后，微信會(huì)把點(diǎn)擊事件推送給企業(yè)。請(qǐng)注意，點(diǎn)擊菜單彈出子菜單，不會(huì)產(chǎn)生上報(bào)。
- 參數(shù)說(shuō)明
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[FromUser]]></FromUserName>
- <CreateTime>123456789</CreateTime>
- <MsgType><![CDATA[event]]></MsgType>
- <Event><![CDATA[click]]></Event>
- <EventKey><![CDATA[EVENTKEY]]></EventKey>
- <AgentID>001</AgentID>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 企業(yè)號(hào)CorpID |
| FromUserName | 員工UserID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：event |
| Event | 事件類型，可為click或view，對(duì)應(yīng)菜單創(chuàng)建時(shí)的類型 |
| EventKey | 事件KEY值，與菜單接口中KEY值對(duì)應(yīng) |
| AgentID | 企業(yè)應(yīng)用的id，整型。可在應(yīng)用的設(shè)置頁(yè)面查看 |
2、上報(bào)地理位置事件
員工同意上報(bào)地理位置后，每次在進(jìn)入應(yīng)用會(huì)話時(shí)都會(huì)上報(bào)一次地理位置，或在進(jìn)入應(yīng)用會(huì)話后每5秒上報(bào)一次地理位置。企業(yè)可以在管理端修改應(yīng)用的以上 設(shè)置。上報(bào)地理位置時(shí)，微信會(huì)將此事件推送到企業(yè)應(yīng)用在管理端設(shè)置的URL（以下假設(shè)該URL為http://api.3dept.com）。
- 請(qǐng)求說(shuō)明
Http請(qǐng)求方式: POST
http://api.3dept.com/?signature=ASDFQWEXZCVAQFASDFASDFSS×tamp=13500001234&nonce=123412323
- 參數(shù)說(shuō)明
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[FromUser]]></FromUserName>
- <CreateTime>123456789</CreateTime>
- <MsgType><![CDATA[event]]></MsgType>
- <Event><![CDATA[LOCATION]]></Event>
- <Latitude>23.104105</Latitude>
- <Longitude>113.320107</Longitude>
- <Precision>65.000000</Precision>
- <AgentID>001</AgentID>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 企業(yè)號(hào)CorpID |
| FromUserName | 員工UserID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：event |
| Event | 事件類型，此時(shí)固定為：LOCATION |
| Latitude | 地理位置緯度 |
| Longitude | 地理位置經(jīng)度 |
| Precision | 地理位置精度 |
| AgentID | 企業(yè)應(yīng)用的id，整型。可在應(yīng)用的設(shè)置頁(yè)面查看 |
#p#
四、被動(dòng)響應(yīng)消息
企業(yè)響應(yīng)的消息同樣應(yīng)該經(jīng)過(guò)加密，并帶上msg_signature、timestamp、nonce及密文，以下是標(biāo)準(zhǔn)的回包：
- <xml>
- <Encrypt><![CDATA[msg_encrypt]]></Encrypt>
- <MsgSignature><![CDATA[msg_signature]]></MsgSignature>
- <TimeStamp>timestamp</TimeStamp>
- <Nonce><![CDATA[nonce]]></Nonce>
- </xml>
以下是各類型消息的明文XML結(jié)構(gòu)：
- text消息
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[fromUser]]></FromUserName>
- <CreateTime>1348831860</CreateTime>
- <MsgType><![CDATA[text]]></MsgType>
- <Content><![CDATA[this is a test]]></Content>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 員工UserID |
| FromUserName | 企業(yè)號(hào)CorpID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：text |
| Content | 文本消息內(nèi)容 |
- image消息
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[fromUser]]></FromUserName>
- <CreateTime>1348831860</CreateTime>
- <MsgType><![CDATA[image]]></MsgType>
- <Image>
- <MediaId><![CDATA[media_id]]></MediaId>
- </Image>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 員工UserID |
| FromUserName | 企業(yè)號(hào)CorpID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：image |
| MediaId | 圖片消息媒體id，可以調(diào)用多媒體文件下載接口拉取數(shù)據(jù)。 |
- voice消息
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[fromUser]]></FromUserName>
- <CreateTime>1357290913</CreateTime>
- <MsgType><![CDATA[voice]]></MsgType>
- <Voice>
- <MediaId><![CDATA[media_id]]></MediaId>
- </Voice>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 員工UserID |
| FromUserName | 企業(yè)號(hào)CorpID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：voice |
| MediaId | 語(yǔ)音消息媒體id，可以調(diào)用多媒體文件下載接口拉取數(shù)據(jù) |
- video消息
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[fromUser]]></FromUserName>
- <CreateTime>1357290913</CreateTime>
- <MsgType><![CDATA[video]]></MsgType>
- <Video>
- <MediaId><![CDATA[media_id]]></MediaId>
- <Title><![CDATA[title]]></Title>
- <Description><![CDATA[description]]></Description>
- </Video>
- </xml>
| 參數(shù) | 說(shuō)明 |
|---|---|
| ToUserName | 員工UserID |
| FromUserName | 企業(yè)號(hào)CorpID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：video |
| MediaId | 視頻消息媒體id，可以調(diào)用多媒體文件下載接口拉取數(shù)據(jù)。 |
| Title | 視頻消息的標(biāo)題 |
| Description | 視頻消息的描述 |
- news消息
- <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ù) | 說(shuō)明 |
|---|---|
| ToUserName | 員工UserID |
| FromUserName | 企業(yè)號(hào)CorpID |
| CreateTime | 消息創(chuàng)建時(shí)間（整型） |
| MsgType | 消息類型，此時(shí)固定為：news |
| ArticleCount | 多條圖文消息信息，默認(rèn)***個(gè)item為大圖,注意，如果圖文數(shù)超過(guò)10，則將會(huì)無(wú)響應(yīng) |
| Title | 圖文消息標(biāo)題 |
| Description | 圖文消息描述 |
| PicUrl | 圖片鏈接，支持JPG、PNG格式，較好的效果為大圖360*200，小圖200*200 |
| Url | 點(diǎn)擊圖文消息跳轉(zhuǎn)鏈接 |
責(zé)任編輯：閆佳明
來(lái)源：
51CTO
