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