When a user sends a message to an Official Account (or an event of a user operation is pushed), a POST request is generated, and the developer can return a specific XML structure in the response packet (GET) to respond to the message in the form of text, image, article, voice, video, or music. Technically, sending a passive response message is not an API, but a reply to the message sent by the Weixin server.

If the Weixin server does not receive any response within 5 seconds after sending the user's message to the developer's server address (configured at the Developer Center) of the Official Account, it will stop the connection and re-initiate a request. A maximum of three retries are made. If you find that the user cannot receive the response message during debugging, you can check whether the message processing timed out. It is recommended to use msgid for de-duplication of messages with msgid and FromUserName + CreateTime for de-duplication of event messages.

If you want to enhance security, you can enable the message encryption in the Developer Center. In this way, the messages sent by the user to the Official Account and the messages with which the Official Account passively replies to the user will continue to be encrypted. For details, see the Message Encryption and Decryption Instructions for passive reply.

If the server cannot process and reply to the message within five seconds, it must respond in any of the following ways so that the Weixin server does not perform any processing or make retry attempts (in this case, the developer can respond to the message asynchronously via the Customer Service Messages API); otherwise, a severe error may occur.

  1. Directly replies "success" (recommended). 2. Directly replies an empty string (an empty string containing 0 bytes, but not an empty content field in the XML structure).

In any of the following cases, Weixin will send a message in the Official Account chat to notify the user that "The Official Account is currently unavailable. Try again later":

  1. The developer did not reply any content within 5s.
  2. The developer replied unusual data, such as JSON data.

Note that before replying with images (GIF not supported) and other multimedia messages, you need to upload temporary assets to the Weixin server via the Media Asset Management API. You can use both temporary assets and permanent assets from Media Asset Management.

Below are the XML data packets required for various message types:

1. Reply with Text Messages

2. Reply with Image Messages

3. Reply with Voice Messages

4. Reply with Video Messages

5. Reply with Music Messages

6. Reply with Articles

# Reply with Text Messages

<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 Recipent's ID (OpenID received)
FromUserName Yes Developer's Weixin ID
CreateTime Yes Creation time of the message (integral)
MsgType Yes Message type. It is "text" for text messages.
Content Yes Reply message content (If line breaks are supported in "content", they are supported in the Weixin app)

# Reply with Image 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>

Parameter Required Description
ToUserName Yes Recipent's ID (OpenID received)
FromUserName Yes Developer's Weixin ID
CreateTime Yes Creation time of the message (integral)
MsgType Yes Message type. It is "image" for image messages.
MediaId Yes ID of the multimedia file uploaded via the Media Asset Management API

# Reply with Voice Messages

<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 Recipent's ID (OpenID received)
FromUserName Yes Developer's Weixin ID
CreateTime Yes Timestamp of the creation time of the message (integral)
MsgType Yes Message type. It is "voice" for voice messages.
MediaId Yes ID of the multimedia file uploaded via the Media Asset Management API

# Reply with Video Messages

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

Parameter Required Description
ToUserName Yes Recipent's ID (OpenID received)
FromUserName Yes Developer's Weixin ID
CreateTime Yes Creation time of the message (integral)
MsgType Yes Message type. It is "video" for video messages.
MediaId Yes ID of the multimedia file uploaded via the Media Asset Management API
Title No The video message's title
Description No The video message description

# Reply with Music Messages

<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 Recipent's ID (OpenID received)
FromUserName Yes Developer's Weixin ID
CreateTime Yes Creation time of the message (integral)
MsgType Yes Message type. It is "music" for music messages.
Title No The music title
Description No The music description
MusicURL No The music's URL
HQMusicUrl No The high-quality music's URL, which is used preferentially in a Wi-Fi environment.
ThumbMediaId Yes The media ID of the thumbnail, which is obtained after a multimedia file is uploaded via the Media Asset Management API.

# Reply with Articles

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>12345678</CreateTime>
  <MsgType><![CDATA[news]]></MsgType>
  <ArticleCount>1</ArticleCount>
  <Articles>
    <item>
      <Title><![CDATA[title1]]></Title>
      <Description><![CDATA[description1]]></Description>
      <PicUrl><![CDATA[picurl]]></PicUrl>
      <Url><![CDATA[url]]></Url>
    </item>
  </Articles>
</xml>

Parameter Required Description
ToUserName Yes Recipent's ID (OpenID received)
FromUserName Yes Developer's Weixin ID
CreateTime Yes Creation time of the message (integral)
MsgType Yes Message type. It is "news" for articles.
ArticleCount Yes The number of articles. The developer can only reply to a user's message (text, image, video, article, or geographic location) with one article, and a maximum of 8 articles can be included in a reply message in other scenarios.
Articles Yes The information of articles. Note that if the number of articles exceeds the limit, only the limited number of articles will be sent.
Title Yes The article title
Description Yes The article description
PicUrl Yes The image URL. The JPG and PNG formats are supported. Preferred resolutions are 360*200 pixels for large images and 200*200 pixels for thumbnails.
Url Yes The URL to be redirected to when an article is tapped