官方接口 - 消息管理

解析接收到的 XML 消息

调用方法:.parse_data(data, msg_signature=None, timestamp=None, nonce=None)

参数说明:

调用前检查:Token

返回值:None

异常:当解析 XML 失败时抛出 exceptions.ParseError 异常。

说明:如果在实例化 WechatConf 时传入了 encrypt_mode='safe',那么在调用本方法进行解析消息时必须传入 msg_signature / timestamp / nonce 三个参数,否则会无法解密消息。

如果 encrypt_mode='normal'encrypt_mode='compatible',则无需传入后面三个参数。

对应官方文档:接收普通消息 / 接收事件推送

获取解析后的信息

当调用 .parse_data() 方法解析成功后,你可以直接获取解析后的具体信息:

公共信息获取

id = wechat.message.id          # 对应于 XML 中的 MsgId
target = wechat.message.target  # 对应于 XML 中的 ToUserName
source = wechat.message.source  # 对应于 XML 中的 FromUserName
time = wechat.message.time      # 对应于 XML 中的 CreateTime
type = wechat.message.type      # 对应于 XML 中的 MsgType
raw = wechat.message.raw        # 原始 XML 文本,方便进行其他分析

私有信息获取

isinstance(wechat.message, TextMessage) 时,有:

content = wechat.message.content                   # 对应于 XML 中的 Content

isinstance(wechat.message, ImageMessage) 时,有:

picurl = wechat.message.picurl                     # 对应于 XML 中的 PicUrl
media_id = wechat.message.media_id                 # 对应于 XML 中的 MediaId

isinstance(wechat.message, VoiceMessage) 时,有:

media_id = wechat.message.media_id                 # 对应于 XML 中的 MediaId
format = wechat.message.format                     # 对应于 XML 中的 Format
recognition = wechat.message.recognition           # 对应于 XML 中的 Recognition

isintance(wechat.message, VideoMessage)isinstance(wechat.message, ShortVideoMessage) 时,有:

media_id = wechat.message.media_id                 # 对应于 XML 中的 MediaId
thumb_media_id = wechat.message.thumb_media_id     # 对应于 XML 中的 ThumbMediaId

isinstance(wechat.message, LocationMessage) 时,有:

location = wechat.message.location                 # Tuple(X, Y),对应于 XML 中的 (Location_X, Location_Y)
scale = wechat.message.scale                       # 对应于 XML 中的 Scale
label = wechat.message.label                       # 对应于 XML 中的 Label

isinstance(wechat.message, LinkMessage) 时,有:

title = wechat.message.title                       # 对应于 XML 中的 Title
description = wechat.message.description           # 对应于 XML 中的 Description
url = wechat.message.url                           # 对应于 XML 中的 Url

isinstance(wechat.message, EventMessage) 时,有:

if wechat.message.type == 'subscribe':  # 关注事件(包括普通关注事件和扫描二维码造成的关注事件)
    key = wechat.message.key                        # 对应于 XML 中的 EventKey (普通关注事件时此值为 None)
    ticket = wechat.message.ticket                  # 对应于 XML 中的 Ticket (普通关注事件时此值为 None)
elif wechat.message.type == 'unsubscribe':  # 取消关注事件(无可用私有信息)
    pass
elif wechat.message.type == 'scan':  # 用户已关注时的二维码扫描事件
    key = wechat.message.key                        # 对应于 XML 中的 EventKey
    ticket = wechat.message.ticket                  # 对应于 XML 中的 Ticket
elif wechat.message.type == 'location':  # 上报地理位置事件
    latitude = wechat.message.latitude              # 对应于 XML 中的 Latitude
    longitude = wechat.message.longitude            # 对应于 XML 中的 Longitude
    precision = wechat.message.precision            # 对应于 XML 中的 Precision
elif wechat.message.type == 'click':  # 自定义菜单点击事件
    key = wechat.message.key                        # 对应于 XML 中的 EventKey
elif wechat.message.type == 'view':  # 自定义菜单跳转链接事件
    key = wechat.message.key                        # 对应于 XML 中的 EventKey
elif wechat.message.type == 'templatesendjobfinish':  # 模板消息事件
    status = wechat.message.status                  # 对应于 XML 中的 Status
elif wechat.message.type in ['scancode_push', 'scancode_waitmsg', 'pic_sysphoto', 
                             'pic_photo_or_album', 'pic_weixin', 'location_select']:  # 其他事件
    key = wechat.message.key                        # 对应于 XML 中的 EventKey

被动回复消息 - 文本消息

将文字信息组装为符合微信服务器要求的响应数据

调用方法:.response_text(content, escape=False)

参数说明:

调用前检查:必须已经成功调用过 .parse_data() 方法。

返回值:组装好的 XML 字符串,可直接回复微信服务器。

说明:该方法会根据 WechatConf 实例化时的 encrypt_mode 参数自动组装普通消息或加密消息,无需干预。

对应官方文档:回复文本消息

被动回复消息 - 图片消息

将 media_id 所代表的图片组装为符合微信服务器要求的响应数据

调用方法:.response_image(media_id)

参数说明:

调用前检查:必须已经成功调用过 .parse_data() 方法。

返回值:组装好的 XML 字符串,可直接回复微信服务器。

说明:该方法会根据 WechatConf 实例化时的 encrypt_mode 参数自动组装普通消息或加密消息,无需干预。

对应官方文档:回复图片消息

被动回复消息 - 语音消息

将 media_id 所代表的语音组装为符合微信服务器要求的响应数据

调用方法:.response_voice(media_id)

参数说明:

调用前检查:必须已经成功调用过 .parse_data() 方法。

返回值:组装好的 XML 字符串,可直接回复微信服务器。

说明:该方法会根据 WechatConf 实例化时的 encrypt_mode 参数自动组装普通消息或加密消息,无需干预。

对应官方文档:回复语音消息

被动回复消息 - 视频消息

将 media_id 所代表的视频组装为符合微信服务器要求的响应数据

调用方法:.response_video(media_id, title=None, description=None)

参数说明:

调用前检查:必须已经成功调用过 .parse_data() 方法。

返回值:组装好的 XML 字符串,可直接回复微信服务器。

说明:该方法会根据 WechatConf 实例化时的 encrypt_mode 参数自动组装普通消息或加密消息,无需干预。

对应官方文档:回复视频消息

被动回复消息 - 音乐消息

将音乐信息组装为符合微信服务器要求的响应数据

调用方法:.response_music(music_url, title=None, description=None, hq_music_url=None, thumb_media_id=None)

参数说明:

调用前检查:必须已经成功调用过 .parse_data() 方法。

返回值:组装好的 XML 字符串,可直接回复微信服务器。

说明:该方法会根据 WechatConf 实例化时的 encrypt_mode 参数自动组装普通消息或加密消息,无需干预。

对应官方文档:回复音乐消息

被动回复消息 - 图文消息

将图文信息组装为符合微信服务器要求的响应数据

调用方法:.response_news(articles)

参数说明:

调用前检查:必须已经成功调用过 .parse_data() 方法。

返回值:组装好的 XML 字符串,可直接回复微信服务器。

说明:该方法会根据 WechatConf 实例化时的 encrypt_mode 参数自动组装普通消息或加密消息,无需干预。

对应官方文档:回复图文消息

被动回复消息 - 空消息

假如服务器无法保证在五秒内处理并回复,必须调用该接口,这样微信服务器才不会对此作任何处理,并且不会发起重试(这种情况下,可以使用客服消息接口进行异步回复),否则,将出现严重的错误提示。

调用方法:.response_none()

调用前检查:必须已经成功调用过 .parse_data() 方法。

返回值:组装好的 XML 字符串,可直接回复微信服务器。

对应官方文档:回复空消息

客服消息

发送文本消息

调用方法:.send_text_message(user_id, content)

参数说明:

调用前检查:App ID / App Secret

返回值:正常返回官方接口的 JSON 数据:{"errcode": 0, "errmsg": "ok"},一般无需理会该返回值,发送失败会抛出异常,捕获异常即可。

异常:当发生失败时抛出 exceptions.OfficialAPIError 异常,该异常包含了错误的代号与原因信息。

对应官方文档:客服接口

发送图片消息

调用方法:.send_image_message(user_id, media_id)

参数说明:

调用前检查:App ID / App Secret

返回值:正常返回官方接口的 JSON 数据:{"errcode": 0, "errmsg": "ok"},一般无需理会该返回值,发送失败会抛出异常,捕获异常即可。

异常:当发生失败时抛出 exceptions.OfficialAPIError 异常,该异常包含了错误的代号与原因信息。

对应官方文档:客服接口

发送语音消息

调用方法:.send_voice_message(user_id, media_id)

参数说明:

调用前检查:App ID / App Secret

返回值:正常返回官方接口的 JSON 数据:{"errcode": 0, "errmsg": "ok"},一般无需理会该返回值,发送失败会抛出异常,捕获异常即可。

异常:当发生失败时抛出 exceptions.OfficialAPIError 异常,该异常包含了错误的代号与原因信息。

对应官方文档:客服接口

发送视频消息

调用方法:.send_video_message(user_id, media_id, title=None, description=None)

参数说明:

调用前检查:App ID / App Secret

返回值:正常返回官方接口的 JSON 数据:{"errcode": 0, "errmsg": "ok"},一般无需理会该返回值,发送失败会抛出异常,捕获异常即可。

异常:当发生失败时抛出 exceptions.OfficialAPIError 异常,该异常包含了错误的代号与原因信息。

对应官方文档:客服接口

发送音乐消息

调用方法:.send_music_message(user_id, url, hq_url, thumb_media_id, title=None, description=None)

参数说明:

调用前检查:App ID / App Secret

返回值:正常返回官方接口的 JSON 数据:{"errcode": 0, "errmsg": "ok"},一般无需理会该返回值,发送失败会抛出异常,捕获异常即可。

异常:当发生失败时抛出 exceptions.OfficialAPIError 异常,该异常包含了错误的代号与原因信息。

对应官方文档:客服接口

发送图文消息

调用方法:.send_article_message(self, user_id, articles=None, media_id=None)

参数说明:

注意 articlesmedia_id 参数只能传递任意一个。同时传递两个将优先使用 articles 进行发送。

调用前检查:App ID / App Secret

返回值:正常返回官方接口的 JSON 数据:{"errcode": 0, "errmsg": "ok"},一般无需理会该返回值,发送失败会抛出异常,捕获异常即可。

异常:当发生失败时抛出 exceptions.OfficialAPIError 异常,该异常包含了错误的代号与原因信息。

对应官方文档:客服接口

发送卡券

待开发

群发接口

待开发

模板消息

设置所属行业

调用方法:.set_template_industry(industry_id1, industry_id2)

参数说明:

调用前检查:App ID / App Secret

返回值:正常返回官方接口的 JSON 数据:{"errcode": 0, "errmsg": "ok"},一般无需理会该返回值,设置失败会抛出异常,捕获异常即可。

异常:当发生失败时抛出 exceptions.OfficialAPIError 异常,该异常包含了错误的代号与原因信息。

对应官方文档:设置所属行业

获取设置的行业信息

待开发

获得模板 ID

调用方法:.get_template_id(template_id_short)

参数说明:

调用前检查:App ID / App Secret

返回值:正常返回官方接口的 JSON 数据,示例:

{
    "errcode": 0,
    "errmsg": "ok",
    "template_id": "Doclyl5uP7Aciu-qZ7mJNPtWkbkYnWBWVja26EGbNyk"
}

异常:当发生失败时抛出 exceptions.OfficialAPIError 异常,该异常包含了错误的代号与原因信息。

对应官方文档:获得模板ID

获取模板列表

待开发

删除模板

待开发

发送模板消息

调用方法:.send_template_message(user_id, template_id, data, url='', topcolor='#FF0000')

参数说明:

调用前检查:App ID / App Secret

返回值:正常返回官方接口的 JSON 数据,示例:

{
    "errcode": 0,
    "errmsg": "ok",
    "msgid": 200228332
}

异常:当发生失败时抛出 exceptions.OfficialAPIError 异常,该异常包含了错误的代号与原因信息。

对应官方文档:发送模板消息

模板消息事件推送

当模板消息事件推送 XML 到达并经过 .parse_data() 解析后,你可以通过下面的方式获取状态信息。

首先要确定该消息是模板消息的事件推送:

from wechat_sdk.messages import EventMessage
if isinstance(wechat.message, EventMessage) and wechat.message.type == 'templatesendjobfinish':

然后就可以根据 wechat.message.status 的情况进行判断了:

  1. 当送达成功时,wechat.message.status == 'success'
  2. 当送达失败,原因为用户拒收(用户设置拒绝接收公众号消息)时,wechat.message.status == 'failed:user block'
  3. 当送达失败,其他原因时,wechat.message.status == 'failed:system failed'

公众号自动回复配置

待开发