When the app is set in callback mode, the enterprise can receive employee reply messages, as well as employee attention, menu clicks, geographic location reporting and other events through the callback URL. After receiving an event, the enterprise can send a passive response message to enable interaction between employees and the enterprise. Note that when an enterprise receives a message or sends a passive response message, the message body is encrypted using AES to ensure transmission security. For details, please refer to the section 'Callback Mode' in 'Establish Connection'. 1. Follow and Unfollow When employees follow a corporate account, they must first bind it to the account in the corporate address book; if the company has enabled two-factor verification, then after the binding is successful, they must also be verified by the company before they can successfully follow. 1. Bind employees to accounts in the address book When an employee follows a corporate account, the employee's WeChat ID, the mobile phone or email address bound to WeChat, will be matched with the account in the corporate address book. If a match is found, the binding is successful; otherwise, the employee will be prompted to enter the mobile phone number or email address, and after successful verification, it will be matched with the account in the corporate address book. Note that the employee's WeChat version must be above 5.4, and currently only supports iOS and Android platforms. 2. Secondary verification When an enterprise enables two-step verification, it must fill in the URL of the enterprise two-step verification page. When an employee binds an account in the address book, he or she will receive a graphic message to guide the employee to the enterprise's verification page to verify his or her identity. After the employee successfully verifies, the enterprise can call the following interface to let the employee follow the success. Http request method: GET https://qyapi.weixin.qq.com/cgi-bin/user/authsucc?access_token=ACCESS_TOKEN&userid=USERID parameter | must | illustrate |
---|
access_token | yes | Call interface credentials | userid | yes | Employee UserID |
The administrator must have the management authority of the employee corresponding to the userid. - {
- "errcode" : "0" ,
- "errmsg" : "ok"
- }
3. Push notifications for follow/unfollow events Events of employees following or unfollowing an enterprise account will be pushed to the URL set by each application on the management side; in particular, the default enterprise assistant can be used to obtain the following status of the entire enterprise account. (The following assumes that the URL is http://api.3dept.com). Http request method: POST http://api.3dept.com/?signature=ASDFQWEXZCVAQFASDFASDFSS×tamp=13500001234&nonce=123412323 - < xml >
- < ToUserName > <![CDATA[toUser]]> </ ToUserName >
- < FromUserName > <![CDATA[UserID]]> </ FromUserName >
- <CreateTime> 1348831860 </CreateTime>
- < MsgType > <![CDATA[event]]> </ MsgType >
- < Event > <![CDATA[subscribe]]> </ Event >
- <AgentID> 1 </AgentID>
- </ xml >
parameter | illustrate |
---|
ToUserName | Corporate ID | FromUserName | Employee UserID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: event | Event | Event type, subscribe (subscription), unsubscribe (unsubscription) | AgentID | The id of the enterprise application, integer. It can be obtained from the application settings page; if the id is 0, it means the follow/unfollow event of the entire enterprise account |
#p# 2. Receiving ordinary messages Ordinary messages refer to messages sent by employees to enterprise applications, including text, pictures, voice, video, geographic location, and other types. - < 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 >
parameter | illustrate |
---|
ToUserName | Corporate ID | FromUserName | Employee UserID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: text | Content | Text message content | MsgId | Message id, 64-bit integer | AgentID | The id of the enterprise application, integer. You can view it on the application settings page. |
- < 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 >
parameter | illustrate |
---|
ToUserName | Corporate ID | FromUserName | Employee UserID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: text | Content | Text message content | MsgId | Message id, 64-bit integer | AgentID | The id of the enterprise application, integer. You can view it on the application settings page. |
- < 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 >
parameter | illustrate |
---|
ToUserName | Corporate ID | FromUserName | Employee UserID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: image | PicUrl | Image Link | MediaId | The media id of the picture message can be used to call the multimedia file download interface to pull data. | MsgId | Message id, 64-bit integer | AgentID | The id of the enterprise application, integer. You can view it on the application settings page. |
- < 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 >
parameter | illustrate |
---|
ToUserName | Corporate ID | FromUserName | Employee UserID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: voice | MediaId | Voice message media id, you can call the multimedia file download interface to pull data. | Format | Voice format, such as amr, speex, etc. | MsgId | Message id, 64-bit integer | AgentID | The id of the enterprise application, integer. You can view it on the application settings page. |
- < 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 >
parameter | illustrate |
---|
ToUserName | Corporate ID | FromUserName | Employee UserID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: video | MediaId | Video message media id, you can call the multimedia file download interface to pull data. | ThumbMediaId | The media ID of the video message thumbnail. You can call the multimedia file download interface to pull data. | MsgId | Message id, 64-bit integer | AgentID | The id of the enterprise application, integer. You can view it on the application settings page. |
- < 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[Location Information]]> </ Label >
- < MsgId > 1234567890123456 </ MsgId >
- <AgentID> 1 </AgentID>
- </ xml >
parameter | illustrate |
---|
ToUserName | Corporate ID | FromUserName | Employee UserID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: location | Location_X | Geographical location latitude | Location_Y | Geographic location longitude | Scale | Map zoom size | Label | Geographical location information | MsgId | Message id, 64-bit integer | AgentID | The id of the enterprise application, integer. You can view it on the application settings page. |
#p# 3. Receiving events Events refer to certain operations performed by employees on the enterprise account, such as following, reporting geographic location, clicking on menus, etc. (For events to follow, please refer to 'Follow and Unfollow') 1. Menu event push When an employee clicks on a custom menu, WeChat will push the click event to the enterprise. Please note that clicking on a menu to pop up a submenu will not generate a report. - < 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 >
parameter | illustrate |
---|
ToUserName | Corporate ID | FromUserName | Employee UserID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: event | Event | Event type, which can be click or view, corresponding to the type when the menu is created | EventKey | Event KEY value, corresponding to the KEY value in the menu interface | AgentID | The id of the enterprise application, integer. You can view it on the application settings page. |
2. Reporting Geolocation Events After employees agree to report their location, they will report their location every time they enter an application session, or every 5 seconds after entering an application session. Enterprises can modify the above settings of the application on the management side. When reporting the location, WeChat will push this event to the URL set by the enterprise application on the management side (assuming that the URL is http://api.3dept.com below). Http request method: POST http://api.3dept.com/?signature=ASDFQWEXZCVAQFASDFASDFSS×tamp=13500001234&nonce=123412323 - < 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 >
parameter | illustrate |
---|
ToUserName | Corporate ID | FromUserName | Employee UserID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: event | Event | Event type, fixed at this time: LOCATION | Latitude | Geographical location latitude | Longitude | Geographic location longitude | Precision | Geolocation accuracy | AgentID | The id of the enterprise application, integer. You can view it on the application settings page. |
#p# 4. Passive response message The enterprise response message should also be encrypted and carry msg_signature, timestamp, nonce and ciphertext . The following is a standard response packet: - < xml >
- < Encrypt > <![CDATA[msg_encrypt]]> </ Encrypt >
- < MsgSignature > <![CDATA[msg_signature]]> </ MsgSignature >
- <TimeStamp> timestamp </TimeStamp>
- < Nonce > <![CDATA[nonce]]> </ Nonce >
- </ xml >
The following is the plain text XML structure of each type of message: - < xml >
- < ToUserName > <![CDATA[toUser]]> </ ToUserName >
- < FromUserName > <![CDATA[fromUser]]> </ FromUserName >
- <CreateTime> 1348831860 </CreateTime>
- < MsgType > <![CDATA[text]]> </ MsgType >
- < Content > <![CDATA[this is a test]]> </ Content >
- </ xml >
parameter | illustrate |
---|
ToUserName | Employee UserID | FromUserName | Corporate ID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: text | Content | Text message content |
- < xml >
- < ToUserName > <![CDATA[toUser]]> </ ToUserName >
- < FromUserName > <![CDATA[fromUser]]> </ FromUserName >
- <CreateTime> 1348831860 </CreateTime>
- < MsgType > <![CDATA[image]]> </ MsgType >
- < Image >
- < MediaId > <![CDATA[media_id]]> </ MediaId >
- </ Image >
- </ xml >
parameter | illustrate |
---|
ToUserName | Employee UserID | FromUserName | Corporate ID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: image | MediaId | The media id of the picture message can be used to call the multimedia file download interface to pull data. |
- < xml >
- < ToUserName > <![CDATA[toUser]]> </ ToUserName >
- < FromUserName > <![CDATA[fromUser]]> </ FromUserName >
- <CreateTime> 1357290913 </CreateTime>
- < MsgType > <![CDATA[voice]]> </ MsgType >
- < Voice >
- < MediaId > <![CDATA[media_id]]> </ MediaId >
- </ Voice >
- </ xml >
parameter | illustrate |
---|
ToUserName | Employee UserID | FromUserName | Corporate ID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: voice | MediaId | Voice message media id, you can call the multimedia file download interface to pull data |
- < 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 >
parameter | illustrate |
---|
ToUserName | Employee UserID | FromUserName | Corporate ID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: video | MediaId | Video message media id, you can call the multimedia file download interface to pull data. | Title | Title of the video message | Description | Description of video message |
- < 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 >
parameter | illustrate |
---|
ToUserName | Employee UserID | FromUserName | Corporate ID | CreateTime | Message creation time (integer) | MsgType | Message type, fixed at this time: news | ArticleCount | For multiple text and picture messages, the first item is a large picture by default. Please note that if the number of pictures and texts exceeds 10, there will be no response. | Title | Title of picture and text message | Description | Description of the picture and text message | PicUrl | Image link, supports JPG and PNG formats, the best effect is 360*200 for large images and 200*200 for small images | Url | Click on the link to jump to the text message | |