When a WeChat user sends a message to the Official Account, the WeChat server will POST an XML data packet of the message to the URL entered by the developer.

Notes:

  1. It is recommended to use msgid for de-duplication of requests.

  2. If the WeChat 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. If the server cannot process and reply to the message within five seconds,

it can return an empty string. When receiving the string, the WeChat server will not take any action or make a retry. For details, see "Sending Messages - Passive Reply Messages".

  1. If the developer needs to respond immediately to the user message within 5 seconds by using the "Sending Messages - Passive Reply Messages" API to passively reply to the user message,

the developer can set message encryption in the Developer Center on the Official Accounts Platform. After message encryption is enabled, the messages sent by users and the reply messages from the developer will both be encrypted (not including the messages

sent by the developer by calling the Customer Service API). For details on the message encryption/decryption, see "Sending Messages - Passive Reply Message Encryption/Decryption Instructions".

The XML data packets for various message types are structured as follows:

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>

Parameter Description
ToUserName Developer's WeChat ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type. It is "text" for text messages.
Content Text message content
MsgId Message ID (64-bit integer)

Debug this API using webpage debugging tool

Image Messages

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

Parameter Description
ToUserName Developer's WeChat ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type. It is "image" for image messages.
PicUrl Image link (generated by the system)
MediaId Media ID of the image message. Data can be fetched by calling the "Get Temporary Assets" API.
MsgId Message ID (64-bit integer)

Debug this API using webpage debugging tool

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>

Parameter Description
ToUserName Developer's WeChat ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type. It is "voice" for voice messages.
MediaId Media ID of the voice message. Data can be fetched by calling the "Get Temporary Assets" API.
Format Voice format, such as amr and speex.
MsgID Message ID (64-bit integer)

Debug this API using webpage debugging tool

Note that after voice recognition is enabled, each time a user sends a voice message to the Official Account, WeChat adds a Recognition field in the pushed voice message XML data packet (Note: Due to client caching, the developer's operation of enabling or disabling the voice recognition feature takes effect immediately for new followers, and after 24 hours for existing users. The developer can re-follow this account for testing). The voice XML data packet after voice recognition is enabled is as follows:

<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>
  <Recognition>< ![CDATA[Tencent WeChat Team] ]></Recognition>
  <MsgId>1234567890123456</MsgId>
</xml>

Parameters:

Parameter Description
ToUserName Developer's WeChat ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type. It is "voice" for voice messages.
MediaID Media ID of the voice message. The asset can be fetched by calling the "Get Temporary Assets" API.
Format Voice format (amr)
Recognition UTF8-encoded voice recognition result
MsgID Message ID (64-bit integer)

Video Messages

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

Parameter Description
ToUserName Developer's WeChat ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type. It is "video" for video messages.
MediaId Media ID of the video message. Data can be fetched by calling the "Get Temporary Assets" API.
ThumbMediaId Media ID of the video message thumbnail. Data can be fetched by calling the "Download Multimedia Files" API.
MsgId Message ID (64-bit integer)

Debug this API using webpage debugging tool

Short Video Messages

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

Parameter Description
ToUserName Developer's WeChat ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type. It is "shortvideo" for short video messages.
MediaId Media ID of the video message. Data can be fetched by calling the "Get Temporary Assets" API.
ThumbMediaId Media ID of the video message thumbnail. Data can be fetched by calling the "Get Temporary Assets" API.
MsgId Message ID (64-bit integer)

Debug this API using webpage debugging tool

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

Parameter Description
ToUserName Developer's WeChat ID
FromUserName Sender's account (an OpenID)
CreateTime Message creation time (integer)
MsgType Message type. It is "location" for geographic location messages.
Location_X Latitude of the location
Location_Y Longitude of the location
Scale Map scale
Label Geographic location information
MsgId Message ID (64-bit integer)

Debug this API using webpage debugging tool

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>1351776360</CreateTime>
  <MsgType><![CDATA[link]]></MsgType>
  <Title><![CDATA[Link to the Official Accounts Platform]]></Title>
  <Description><![CDATA[Link to the Official Accounts Platform]]></Description>
  <Url><![CDATA[url]]></Url>
  <MsgId>1234567890123456</MsgId>
</xml>

Parameter Description
ToUserName WeChat ID of the recipient
FromUserName WeChat ID of the sender. For ordinary users, it is an OpenID.
CreateTime Message creation time
MsgType Message type. It is "link" for link messages.
Title Message title
Description Message description
Url Message link
MsgId Message ID (64-bit integer)

Debug this API using webpage debugging tool