During the interaction between a Weixin user and an Official Account, some operations of the user will cause the Weixin server to push event messages to the server address set by the developer in the Developer Center, so that the developer can be notified of such operations. Some of the event pushes allow the developer to reply to the user, and some don't. The details are as follows:

Contents

1 Following/Unfollowing Event

2 Event of Scanning QR Code with Parameters

3 Event of Reporting Geographic Location

4 Custom Menu Event

5 Event of Tapping Menu to Pull Message

6 Event of Tapping Menu to Redirect to URL

# Following/Unfollowing Event

When a user follows or unfollows an Official Account, Weixin will push the event to the URL entered by the developer so that the developer can send a welcome message to the user or unlink the account. If the user who unfollows the account, in order to protect the user's data privacy, the developer must delete all the information of the user upon receipt of the event.

If the Weixin server does not receive the response within five seconds, the connection is broken and the request is initiated again. A maximum of three retries are made.

It is recommended to use FromUserName + CreateTime for de-duplication of requests.

If the merchant's server cannot ensure the request is processed and responded within five seconds, it can return an empty string. When receiving the string, the Weixin server will not take any action or make a retry.

Example of XML packet:

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[FromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[subscribe]]></Event>
</xml>

Parameters:

Parameter Description
ToUserName Developer's Weixin ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type: event
Event Event type (subscribe or unsubscribe)

Debug this API using webpage debugging tool

# Event of Scanning QR Code with Parameters

When a user scans a QR code with a scene value, the following two events may be pushed:

  1. If the user has not followed the Official Account, they can follow it, and then Weixin will push the Official Account following event with the scene value to the developer.
  2. If the user has followed the Official Account, Weixin will push the event of code scan with the scene value to the developer.

1. Event of a user following the Official Account

Example of XML packet:

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

Parameters:

Parameter Description
ToUserName Developer's Weixin ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type: event
Event Event type (subscribe)
EventKey Event key. "qrscene_" is the prefix, followed by the parameter value of the QR code.
Ticket The ticket of the QR code, which can be used to exchange for the QR code image.

2. Event of a user scanning the QR code

Example of XML packet:

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[FromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[SCAN]]></Event>
  <EventKey><![CDATA[SCENE_VALUE]]></EventKey>
  <Ticket><![CDATA[TICKET]]></Ticket>
</xml> 

Parameters:

Parameter Description
ToUserName Developer's Weixin ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type: event
Event Event type (SCAN)
EventKey Event key, a 32-bit unsigned integer. It is the scene_id of the QR code created.
Ticket The ticket of the QR code, which can be used to exchange for the QR code image.

Debug this API using webpage debugging tool

# Event of Reporting Geographic Location

After a user agrees on reporting their location, their location is reported each time the user enters the Official Account, or every 5 seconds after the user enters the Official Account. The Official Account can modify the setting on the Official Accounts Platform. When a geographic location is reported Weixin will send a geographic location report event to the URL entered by the developer.

Example of XML packet:

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

Parameters:

Parameter Description
ToUserName Developer's Weixin ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type: event
Event Event type: LOCATION
Latitude Latitude of the location
Longitude Longitude of the location
Precision Accuracy of the location

Debug this API using webpage debugging tool

# Custom Menu Event

After a user taps the custom menu, Weixin will push the tapping event to the developer. Note that the event of tapping the menu to open the sub-menu will not be reported.

Event of tapping menu to pull message

Example of XML packet:

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

Parameters:

Parameter Description
ToUserName Developer's Weixin ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type: event
Event Event type (CLICK)
EventKey Event key, which corresponds to the key in the custom menu API

Event of tapping menu to redirect to URL

Example of XML packet:

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[FromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[VIEW]]></Event>
  <EventKey><![CDATA[www.qq.com]]></EventKey>
</xml>

Parameters:

Parameter Description
ToUserName Developer's Weixin ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type: event
Event Event type (VIEW)
EventKey Event key, which is the URL to be redirected to

Debug this API using webpage debugging tool