When an ordinary WeChat user sends a message to a public account, the WeChat server will POST the XML data packet of the message to the URL filled in by the developer.
1. Regarding the retry message reloading, it is recommended to use msgid reloading.
2. If the WeChat server does not receive a response within five seconds, the connection will be disconnected, and the request will be re-initialized for a total of three retries. If the server cannot guarantee to process and reply within five seconds, it can directly reply with an empty string, and the WeChat server will not do anything to this, and will not initiate a retry.
Messages are divided into common message types and event message types, which are now parsed as follows:
1. Common message type
Common message types are divided into the following 7 message types:
1.1. Text messages
<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> </xml>
1.2. Picture message
<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> </xml>
1.3. Voice messages
<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> </xml>
1.4. Video message
<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> </xml>
1.5. Small video message
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName> <! [CDATA [fromUser]]> </FromUserName> <CreateTime>1357290913</CreateTime> <MsgType><![CDATA[shortvideo]]></MsgType> <MediaId><![CDATA[media_id]]></MediaId> <ThumbMediaId><![CDATA[thumb_media_id]]></ThumbMediaId> <MsgId>1234567890123456</MsgId> </xml>
1.6. Geolocation messages
<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> </xml>
1.7. Link messages
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName> <! [CDATA [fromUser]]> </FromUserName> <CreateTime>1351776360</CreateTime> <MsgType><![CDATA[link]]></MsgType> <Title><![CDATA[Official website link of public platform]]></Title> <Description><![CDATA[Official website link of public platform]]></Description> <Url><![CDATA[url]]></Url> <MsgId>1234567890123456</MsgId> </ xml
2. Event message type
In the process of interaction between WeChat users and the official account, certain operations of the user will cause the WeChat server to notify the server address set by the developer in the developer center through event push, so that the developer can obtain the information. Among them, after some event pushes occur, developers are allowed to reply to users, and some are not allowed.
Event message types are divided into the following 6 types:
2.1. Follow/unfollow events
When users follow and unfollow the official account, WeChat will push the event to the URL filled in by the developer. It is convenient for developers to send welcome messages to users or to unbind accounts.
If the WeChat server fails to receive a response within five seconds, the connection will be disconnected, and the request will be re-initialized for a total of three retries.
Regarding the retry message queue, it is recommended to use FromUserName + CreateTime to queue.
If the server cannot guarantee to process and reply within five seconds, it can directly reply with an empty string, and the WeChat server will not do anything to this, and will not initiate a retry.
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName> <! [CDATA [FromUser]]> </FromUserName> <CreateTime>123456789</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[subscribe]]></Event> </xml>
| ToUserName | Developer WeChat |
| FromUserName | Sender account number (an OpenID) |
| CreateTime | message creation time (integer) |
| MsgType | message type, event |
| Event | Event type, subscribe (subscribe), unsubscribe (unsubscribe) |
2.2. Scanning QR code events with parameters
When a user scans a QR code with a scene value, the following two events may be pushed:
- If the user has not followed the official account, the user can follow the official account, and WeChat will push the following events with scene value to the developer after following the account.
- If the user has followed the official account, WeChat will push the scan event with scene value to the developer.
2.2.1. When the user does not follow, push events after following
<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>
| ToUserName | Developer WeChat |
| FromUserName | Sender account number (an OpenID) |
| CreateTime | message creation time (integer) |
| MsgType | message type, event |
| Event | event type, subscribe |
| EventKey | Event KEY value, qrscene_ is the prefix, followed by the parameter value of the QR code |
| Ticket | A QR code ticket, which can be used to exchange for a QR code image |
2.2.2. Event push when user has followed
<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>
| ToUserName | Developer WeChat |
| FromUserName | Sender account number (an OpenID) |
| CreateTime | message creation time (integer) |
| MsgType | message type, event |
| Event | event type, SCAN |
| EventKey | The event KEY value is a 32-bit unsigned integer, that is, the scene_id of the QR code when the QR code is created |
| Ticket | A QR code ticket, which can be used to exchange for a QR code image |
2.3. Reporting geolocation events
After the user agrees to report the geographic location, each time they enter the official account session, the geographic location will be reported when entering the session, or the geographic location will be reported every 5 seconds after entering the session. The official account can modify the above settings on the official platform website. When reporting geographic location, WeChat will push the reporting geographic location event to the URL filled in by the developer.
<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>
| ToUserName | Developer WeChat |
| FromUserName | Sender account number (an OpenID) |
| CreateTime | message creation time (integer) |
| MsgType | message type, event |
| Event | event type, LOCATION |
| Latitude | Geographical Latitude |
| Longitude | Geographical Longitude |
| Precision | Geolocation accuracy |
2.4. Custom menu events
After the user clicks the custom menu, WeChat will push the click event to the developer. Please note that clicking on the menu will pop up a submenu and no report will be generated.
2.5. Event push when clicking the menu to pull the message
After the user clicks the custom menu, WeChat will push the click event to the developer. Please note that clicking on the menu will pop up a submenu and no report will be generated.
<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>
| ToUserName | Developer WeChat |
| FromUserName | Sender account number (an OpenID) |
| CreateTime | message creation time (integer) |
| MsgType | message type, event |
| Event | event type, CLICK |
| EventKey | Event KEY value, corresponding to the KEY value in the custom menu interface |
2.6. Event push when clicking menu jump link
<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>
| ToUserName | Developer WeChat |
| FromUserName | Sender account number (an OpenID) |
| CreateTime | message creation time (integer) |
| MsgType | message type, event |
| Event | event type, VIEW |
| EventKey | Event KEY value, set jump URL |
3. Passively reply to user messages
When a user sends a message to the official account (or when some specific user operation triggers an event push), a POST request will be generated, and the developer can respond to the message by returning a specific XML structure in the response package (Get). (Now supports replying to text, pictures, graphics, voice, video, and music). Strictly speaking, sending a passive response message is not actually an interface, but a reply to a message sent by the WeChat server.
After the WeChat server sends the user's message to the developer server address of the official account (configured in the developer center), the WeChat server will disconnect the connection if it does not receive a response within five seconds, and re-initiate the request, retried three times in total. If during debugging, it is found that the user cannot receive the response message, you can check whether the message processing times out. Regarding the retrying of messages, it is recommended to use msgid for messages with msgid. It is recommended to use FromUserName + CreateTime to deduplicate event type messages.
If developers want to enhance security, they can enable message encryption in the developer center, so that the messages sent by users to the official account and the passive reply messages from the official account will continue to be encrypted (but). For details, please refer to the description of passive reply message encryption and decryption.
If the server cannot guarantee to process and reply within five seconds, the following reply must be made, so that the WeChat server will not do anything to this and will not initiate a retry (in this case, you can use the customer service message interface to asynchronously reply), otherwise, a serious error message will appear.There are six types of passive replies to user messages:
3.1. Replying to Text Messages
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName> <! [CDATA [fromUser]]> </FromUserName> <CreateTime>12345678</CreateTime> <MsgType><![CDATA[text]]></MsgType> <Content><![CDATA[你好]]></Content> </xml>
| ToUserName | Yes | Receiver account number (OpenID received) |
| FromUserName | Yes | Developer WeChat |
| CreateTime | Yes | message creation time (integer) |
| MsgType | Yes | text |
| Content | Yes | The content of the reply message (line break: line breaks can be used in the content, and the WeChat client supports line break display) |
3.2. Reply to picture messages
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName> <! [CDATA [fromUser]]> </FromUserName> <CreateTime>12345678</CreateTime> <MsgType><![CDATA[image]]></MsgType> <Image> <MediaId><![CDATA[media_id]]></MediaId> </Image> </xml>Whether the parameter must be specified
| ToUserName | Yes | Receiver account number (OpenID received) |
| FromUserName | Yes | Developer WeChat |
| CreateTime | Yes | message creation time (integer) |
| MsgType | Yes | image |
| MediaId | Yes | The id obtained by uploading multimedia files through the material management interface. |
3.3. Reply to a voice message
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName> <! [CDATA [fromUser]]> </FromUserName> <CreateTime>12345678</CreateTime> <MsgType><![CDATA[voice]]></MsgType> <Voice> <MediaId><![CDATA[media_id]]></MediaId> </Voice> </xml>
| ToUserName | Yes | Receiver account number (OpenID received) |
| FromUserName | Yes | Developer WeChat |
| CreateTime | Yes | message creation timestamp (integer) |
| MsgType | Yes | voice |
| MediaId | Yes | Upload multimedia files through the material management interface and get the id |
3.4. Reply to video message
<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>
| ToUserName | 是 | 接收方帐号（收到的OpenID） |
| FromUserName | 是 | 开发者微信号 |
| CreateTime | 是 | 消息创建时间 （整型） |
| MsgType | 是 | video |
| MediaId | 是 | 通过素材管理接口上传多媒体文件，得到的id |
| Title | 否 | 视频消息的标题 |
| Description | 否 | 视频消息的描述 |
3.5.回复音乐消息
<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>
| ToUserName | 是 | 接收方帐号（收到的OpenID） |
| FromUserName | 是 | 开发者微信号 |
| CreateTime | 是 | 消息创建时间 （整型） |
| MsgType | 是 | music |
| Title | 否 | 音乐标题 |
| Description | 否 | 音乐描述 |
| MusicURL | 否 | 音乐链接 |
| HQMusicUrl | 否 | 高质量音乐链接，WIFI环境优先使用该链接播放音乐 |
| ThumbMediaId | 否 | 缩略图的媒体id，通过素材管理接口上传多媒体文件，得到的id |
3.6.回复图文消息
<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>
| ToUserName | 是 | 接收方帐号（收到的OpenID） |
| FromUserName | 是 | 开发者微信号 |
| CreateTime | 是 | 消息创建时间 （整型） |
| MsgType | 是 | news |
| ArticleCount | 是 | 图文消息个数，限制为10条以内 |
| Articles | 是 | 多条图文消息信息，默认第一个item为大图,注意，如果图文数超过10，则将会无响应 |
| Title | 否 | 图文消息标题 |
| Description | 否 | 图文消息描述 |
| PicUrl | 否 | 图片链接，支持JPG、PNG格式，较好的效果为大图360*200，小图200*200 |
| Url | 否 | 点击图文消息跳转链接 |