Callback Messages
Back

From WeChat Official Account Admin Platform
Jump to: navigation, search

The developer returns a specific XML structure in the response packet (GET) for each POST request.The platform currently supports text, image, rich media, audio, video and music messages. Users can upload multimedia files to the WeChat server before replying to a multimedia message, for example, one that contains an image. Only authorized service accounts are supported.

If a response from the developer's backend system is not received within five seconds, the WeChat Official Account System will close the connection and initiate a new request up to three times. If the user cannot receive the response packet during debugging, check whether the message has timed out.

To avoid duplicate retry messages, it is recommended to use msgid. As to event-based messages, it is recommended to use FromUserName + CreateTime.

Sending a callback message is not an API, but a reply to the message sent from the WeChat Official Account System. If the developer’s backend system cannot guarantee a reply back to the WeChat Official Account System within five seconds, a reply with an empty string should be returned to the WeChat Official Account System instead (please note that an empty string does not mean an XML-formatted reply where the content field is null). In this case, the WeChat Official Account System will not attempt to resend the message. A reply can be also be made asynchronously via the customer service API.

When one of the scenarios listed below is encountered, WeChat Official Account System will deliver the system message "The official account cannot provide service currently, please try again later" to the user in the official account chat view:

1. The developer’s backend system does not reply within five seconds of receiving the message. 
2. The developer replies abnormally-formatted data, e.g. JSON data. 

The following describes XML-based formats of different message types.

Contents

Text Message

 <xml>
 <ToUserName><![CDATA[toUser]]></ToUserName>
 <FromUserName><![CDATA[fromUser]]></FromUserName>
 <CreateTime>12345678</CreateTime>
 <MsgType><![CDATA[text]]></MsgType>
 <Content><![CDATA[Hello]]></Content>
 </xml>
Parameter Required Description
ToUserName Yes Receiver's WeChat ID (the received OpenID)
FromUserName Yes Developer's WeChat ID
CreateTime Yes Message creation time (Integer)
MsgType Yes Text
Content Yes Reply message content (Wrap: can show as a new line in WeChat client if you can wrap in content here.)


Image Message

 <xml>
 <ToUserName><![CDATA[toUser]]></ToUserName>
 <FromUserName><![CDATA[fromUser]]></FromUserName>
 <CreateTime>12345678</CreateTime>
 <MsgType><![CDATA[image]]></MsgType>
 <Image>
 <MediaId><![CDATA[media_id]]></MediaId>
 </Image>
 </xml>
Parameter Required Description
ToUserName Yes Receiver's WeChat ID (the received OpenID)
FromUserName Yes Developer's WeChat ID
CreateTime Yes Message creation time (Integer)
MsgType Yes Image
MediaId Yes The ID obtained by uploading a multimedia file


Audio 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>
Parameter Required Description
ToUserName Yes Receiver's WeChat ID (the received OpenID)
FromUserName Yes Developer's WeChat ID
CreateTime Yes Message creation time (Integer)
MsgType Yes Voice
MediaId Yes The ID obtained by uploading a multimedia file


Video Message

 <xml>
 <ToUserName><![CDATA[toUser]]></ToUserName>
 <FromUserName><![CDATA[fromUser]]></FromUserName>
 <CreateTime>12345678</CreateTime>
 <MsgType><![CDATA[video]]></MsgType>
 <Video>
 <MediaId><![CDATA[media_id]]></MediaId>
 <ThumbMediaId><![CDATA[thumb_media_id]]></ThumbMediaId>
 </Video> 
 </xml>
Parameter Required Description
ToUserName Yes Receiver's WeChat ID (the received OpenID)
FromUserName Yes Developer's WeChat ID
CreateTime Yes Message creation time (Integer)
MsgType Yes Voice
MediaId Yes Obtain this ID by uploading a multimedia file
ThumbMediaId Yes The thumb multimedia ID that is obtained by uploading a multimedia file


Music Message

 <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>
Parameter Required Description
ToUserName Yes Receiver's WeChat ID (the received OpenID)
FromUserName Yes Developer's WeChat ID
CreateTime Yes Message creation time (Integer)
MsgType Yes Music
Title No Music title
Description No Music Description
MusicURL No URL for music
HQMusicUrl No URL that WeChat accesses on Wi-Fi
ThumbMediaId Yes The thumb multimedia ID that is obtained by uploading a multimedia file


Rich Media 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 Required Description
ToUserName Yes Receiver's WeChat ID (the received OpenID)
FromUserName Yes Developer's WeChat ID
CreateTime Yes Message creation time (Integer)
MsgType Yes News
ArticleCount Yes Quantity of rich media messages (up to 10)
Articles Yes The content of rich media messages. The first item is displayed as a large image by default. No response is given if more than 10 messages exist.
Title No Title of the rich media message
Description No Description of the rich media message
PicUrl No URL of images in rich media messages. Recommended image size: 360*200 (large image); 200*200 (small image) Image format supported: JPG and PNG
Url No Redirection link of the rich media message
Developer Guide
Custom-defined Menu
WeChat JS-SDK