微信公众号开发:接收通用消息与事件

时间:2025-04-05 22:02:32
当普通微信用户向公众账号发送消息时,微信服务器将POST消息的XML数据包到开发者在微信公众号管理后台中配置的服务器地址URL上。
常见消息类型的推送XML数据包结构如下。

文本消息

<xml>
<ToUserName><![CDATA[开发者微信号]]></ToUserName>
<FromUserName><![CDATA[发送方OpenID]]></FromUserName>
<CreateTime>消息创建时间(整型)</CreateTime>
<MsgType><![CDATA[text]]></MsgType>
<Content><![CDATA[文本消息内容]]></Content>
<MsgId>消息id,64位整型</MsgId>
</xml>

图片消息

<xml>
<ToUserName><![CDATA[开发者微信号]]></ToUserName>
<FromUserName><![CDATA[发送方OpenID]]></FromUserName>
<CreateTime>消息创建时间(整型)</CreateTime>
<MsgType><![CDATA[image]]></MsgType>
<PicUrl><![CDATA[图片链接(由系统生成)]]></PicUrl>
<MediaId><![CDATA[图片消息媒体id,可以调用多媒体文件下载接口拉取数据]]></MediaId>
<MsgId>消息id,64位整型</MsgId>
</xml>

语音消息

对于开通语音识别的公众号,用户每次发送语音给公众号时,微信会在推送的语音消息XML数据包中,增加一个Recongnition字段(注:由于客户端缓存,开发者开启或者关闭语音识别功能,对新关注者立刻生效,对已关注用户需要24小时生效。开发者可以重新关注此帐号进行测试)。
<xml>
<ToUserName><![CDATA[开发者微信号]]></ToUserName>
<FromUserName><![CDATA[发送方OpenID]]></FromUserName>
<CreateTime>消息创建时间(整型)</CreateTime>
<MsgType><![CDATA[voice]]></MsgType>
<MediaId><![CDATA[图片消息媒体id,可以调用多媒体文件下载接口拉取数据]]></MediaId>
<Format><![CDATA[语音格式,如amr,speex等]]></Format>
<Recognition><![CDATA[开通语音识别才有,语音识别结果,UTF8编码]]></Recognition>
<MsgId>消息id,64位整型</MsgId>
</xml>

视频或小视频消息

<xml>
<ToUserName><![CDATA[开发者微信号]]></ToUserName>
<FromUserName><![CDATA[发送方OpenID]]></FromUserName>
<CreateTime>消息创建时间(整型)</CreateTime>
<MsgType><![CDATA[vieo或shortvideo]]></MsgType>
<MediaId><![CDATA[图片消息媒体id,可以调用多媒体文件下载接口拉取数据]]></MediaId>
<ThumbMediaId><![CDATA[视频消息缩略图的媒体id,可调用多媒体文件下载接口拉取数据]]></ThumbMediaId>
<MsgId>消息id,64位整型</MsgId>
</xml>

地理位置消息

<xml>
<ToUserName><![CDATA[开发者微信号]]></ToUserName>
<FromUserName><![CDATA[发送方OpenID]]></FromUserName>
<CreateTime>消息创建时间(整型)</CreateTime>
<MsgType><![CDATA[location]]></MsgType>
<Location_X>地理位置纬度</Location_X>
<Location_Y>地理位置经度</Location_Y>
<Scale>地图缩放大小</Scale>
<Label><![CDATA[地理位置信息]]></Label>
<MsgId>消息id,64位整型</MsgId>
</xml>

链接消息

<xml>
<ToUserName><![CDATA[开发者微信号]]></ToUserName>
<FromUserName><![CDATA[发送方OpenID]]></FromUserName>
<CreateTime>消息创建时间(整型)</CreateTime>
<MsgType><![CDATA[link]]></MsgType>
<Title><![CDATA[消息标题]]></Title>
<Description><![CDATA[消息描述]]></Description>
<Url><![CDATA[消息链接]]></Url>
<MsgId>消息id,64位整型</MsgId>
</xml>
请注意:
1、关于重试的消息排重,推荐使用msgid排重。
2、微信服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。假如服务器无法保证在五秒内处理并回复,可以直接回复空串,微信服务器不会对此作任何处理,并且不会发起重试。详情请见“发送消息-被动回复消息”。
3、如果开发者需要对用户消息在5秒内立即做出回应,即使用“发送消息-被动回复消息”接口向用户被动回复消息时,可以在公众平台官网的开发者中心处设置消息加密。开启加密后,用户发来的消息和开发者回复的消息都会被加密(但开发者通过客服接口等API调用形式向用户发送消息,则不受影响)。