微信开发者文档

2023-11-11 14:28:46

接收事件推送

1 关注/取消关注事件

2 扫描带参数二维码事件

3 上报地理位置事件

4 自定义菜单事件

5 点击菜单拉取消息时的事件推送

6 点击菜单跳转链接时的事件推送

关注/取消关注事件

用户在关注与取消关注公众号时，微信会把这个事件推送到开发者填写的URL。方便开发者给用户下发欢迎消息或者做帐号的解绑。

微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次

关于重试的消息排重，推荐使用FromUserName + CreateTime 排重。

假如服务器无法保证在五秒内处理并回复，可以直接回复空串，微信服务器不会对此作任何处理，并且不会发起重试。

推送XML数据包示例：

<xml>

</xml>

参数说明：

参数描述

ToUserName 开发者微信号

FromUserName 发送方帐号（一个OpenID）

CreateTime 消息创建时间（整型）

MsgType 消息类型，event

Event 事件类型，subscribe(订阅)、unsubscribe(取消订阅)

扫描带参数二维码事件

用户扫描带场景值二维码时，可能推送以下两种事件：

1.如果用户还未关注公众号，则用户可以关注公众号，关注后微信会将带场景值关注事件推送给开发者。

2.如果用户已经关注公众号，则微信会将带场景值扫描事件推送给开发者。

1. 用户未关注时，进行关注后的事件推送

推送XML数据包示例：

</xml>

参数说明：

参数描述

ToUserName 开发者微信号

FromUserName 发送方帐号（一个OpenID）

CreateTime 消息创建时间（整型）

MsgType 消息类型，event

Event 事件类型，subscribe

EventKey 事件KEY值，qrscene_为前缀，后面为二维码的参数值

Ticket 二维码的ticket，可用来换取二维码图片

2. 用户已关注时的事件推送

推送XML数据包示例：

<xml>

</xml>

参数说明：

参数描述

ToUserName 开发者微信号

FromUserName 发送方帐号（一个OpenID）

CreateTime 消息创建时间（整型）

MsgType 消息类型，event

Event 事件类型，SCAN

EventKey 事件KEY值，是一个32位无符号整数，即创建二维码时的二维码scene_id

Ticket 二维码的ticket，可用来换取二维码图片

上报地理位置事件

用户同意上报地理位置后，每次进入公众号会话时，都会在进入时上报地理位置，或在进入会话后每5秒上报一次地理位置，公众号可以在公众平台网站中修改以上设置。上报地理位置时，微信会将上报地理位置事件推送到开发者填写的URL。

推送XML数据包示例：

<xml>

</xml>

参数说明：

参数描述

ToUserName 开发者微信号

FromUserName 发送方帐号（一个OpenID）

CreateTime 消息创建时间（整型）

MsgType 消息类型，event

Event 事件类型，LOCATION

Latitude 地理位置纬度

Longitude 地理位置经度

Precision 地理位置精度

使用网页调试工具调试该接口

自定义菜单事件

用户点击自定义菜单后，微信会把点击事件推送给开发者，请注意，点击菜单弹出子菜单，不会产生上报。

点击菜单拉取消息时的事件推送

推送XML数据包示例：

<xml>

</xml>

参数说明：

参数描述

ToUserName 开发者微信号

FromUserName 发送方帐号（一个OpenID）

CreateTime 消息创建时间（整型）

MsgType 消息类型，event

Event 事件类型，CLICK

EventKey 事件KEY值，与自定义菜单接口中KEY值对应

点击菜单跳转链接时的事件推送

推送XML数据包示例：

<xml>

</xml>

参数说明：

参数描述

ToUserName 开发者微信号

FromUserName 发送方帐号（一个OpenID）

CreateTime 消息创建时间（整型）

MsgType 消息类型，event

Event 事件类型，VIEW

EventKey 事件KEY值，设置的跳转URL

开通语音识别功能

用户每次发送语音给公众号时，微信会在推送的语音消息XML数据包中，增加一个Recongnition字段。

注：由于客户端缓存，开发者开启或者关闭语音识别功能，对新关注者立刻生效，对已关注用户需要24小时生效。开发者可以重新关注此帐号进行测试。

开启语音识别后的语音XML数据包如下：

<xml>

</xml>

参数说明：

参数描述

ToUserName 开发者微信号

FromUserName 发送方帐号（一个OpenID）

CreateTime 消息创建时间（整型）

MsgType 语音为voice

MediaID 语音消息媒体id，可以调用多媒体文件下载接口拉取该媒体

Format 语音格式：amr

Recognition 语音识别结果，UTF8编码

MsgID 消息id，64位整型

发送被动响应消息

对于每一个POST请求，开发者在响应包（Get）中返回特定XML结构，对该消息进行响应（现支持回复文本、图片、图文、语音、视频、音乐）。请注意，回复图片等多媒体消息时需要预先上传多媒体文

件到微信服务器，只支持认证服务号。

微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次，如果在调试中，发现用户无法收到响应的消息，可以检查是否消息处理超时。

关于重试的消息排重，有msgid的消息推荐使用msgid排重。事件类型消息推荐使用FromUserName + CreateTime 排重。

假如服务器无法保证在五秒内处理并回复，必须直接回复空串（是指回复一个空字符串，而不是一个XML结构体中content字段的内容为空，请切勿误解），微信服务器不会对此作任何处理，并且不会发

起重试。。这种情况下，可以使用客服消息接口进行异步回复。

请开发者注意，一旦遇到以下情况，微信都会在公众号会话中，向用户下发系统提示“该公众号暂时无法提供服务，请稍后再试”：

1、开发者在5秒内未回复任何内容

2、开发者回复了异常数据，比如JSON数据等

各消息类型需要的XML数据包结构如下。

目录1 回复文本消息

2 回复图片消息

3 回复语音消息

4 回复视频消息

5 回复音乐消息

6 回复图文消息

回复文本消息

<xml>

</xml>

参数是否必须描述

ToUserName 是接收方帐号（收到的OpenID）

FromUserName 是开发者微信号

CreateTime 是消息创建时间（整型）

MsgType 是 text

Content 是回复的消息内容（换行：在content中能够换行，微信客户端就支持换行显示）

回复图片消息

<xml>

<Image>

</Image>

</xml>

参数是否必须说明

ToUserName 是接收方帐号（收到的OpenID）

FromUserName 是开发者微信号

CreateTime 是消息创建时间（整型）

MsgType 是 image

MediaId 是通过上传多媒体文件，得到的id。

回复语音消息

<xml>

<Voice>

</Voice>

</xml>

参数是否必须说明

ToUserName 是接收方帐号（收到的OpenID）

FromUserName 是开发者微信号

CreateTime 是消息创建时间戳（整型）

MsgType 是语音，voice

MediaId 是通过上传多媒体文件，得到的id

回复视频消息

<xml>

<Video>

</Video>

</xml>

参数是否必须说明

ToUserName 是接收方帐号（收到的OpenID）

FromUserName 是开发者微信号

CreateTime 是消息创建时间（整型）

MsgType 是 video

MediaId 是通过上传多媒体文件，得到的id

Title 否视频消息的标题

Description 否视频消息的描述

回复音乐消息

<xml>

<Music>

</Music>

</xml>

参数是否必须说明

ToUserName 是接收方帐号（收到的OpenID）

FromUserName 是开发者微信号

CreateTime 是消息创建时间（整型）

MsgType 是 music

Title 否音乐标题

Description 否音乐描述

MusicURL 否音乐链接

HQMusicUrl 否高质量音乐链接，WIFI环境优先使用该链接播放音乐

ThumbMediaId 是缩略图的媒体id，通过上传多媒体文件，得到的id

回复图文消息

<xml>

<item>

</item>

<item>

</item>

</Articles>

</xml>

参数是否必须说明

ToUserName 是接收方帐号（收到的OpenID）

FromUserName 是开发者微信号

CreateTime 是消息创建时间（整型）

MsgType 是 news

ArticleCount 是图文消息个数，限制为10条以内

Articles 是多条图文消息信息，默认第一个item为大图,注意，如果图文数超过10，则将会无响应

Title 否图文消息标题

Description 否图文消息描述

PicUrl 否图片链接，支持JPG、PNG格式，较好的效果为大图360*200，小图200*200

Url 否点击图文消息跳转链接

发送客服消息

出自微信公众平台开发者文档

当用户主动发消息给公众号的时候（包括发送信息、点击自定义菜单、订阅事件、扫描二维码事件、支付成功事件、用户维权），微信将会把消息数据推送给开发者，开发者在一段时间内（目前修改为48小时）可以调用客服消息接口，通过POST一个JSON数据包来发送消息给普通用户，在48小时内不限制发送次数。此接口主要用于客服等有人工消息处理环节的功能，方便开发者为用户提供更加优质的服务。

接口调用请求说明

http请求方式: POST

https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

各消息类型所需的JSON数据包如下。

发送文本消息

{

"touser":"OPENID",

"msgtype":"text",

"text":

{

"content":"Hello World"

}

参数	是否必须	说明
access_token	是	调用接口凭证
touser	是	普通用户openid
msgtype	是	消息类型，text
content	是	文本消息内容

发送图片消息

{

"touser":"OPENID",

"msgtype":"image",

"image":

{

"media_id":"MEDIA_ID"

}

参数	是否必须	说明
access_token	是	调用接口凭证
touser	是	普通用户openid
msgtype	是	消息类型，image
media_id	是	发送的图片的媒体ID

发送语音消息

{

"touser":"OPENID",

"msgtype":"voice",

"voice":

{

"media_id":"MEDIA_ID"

}

参数	是否必须	说明
access_token	是	调用接口凭证
touser	是	普通用户openid
msgtype	是	消息类型，voice
media_id	是	发送的语音的媒体ID

发送视频消息

{

"touser":"OPENID",

"msgtype":"video",

"video":

{

"media_id":"MEDIA_ID",

"thumb_media_id":"MEDIA_ID",

"title":"TITLE",

"description":"DESCRIPTION"

}

参数	是否必须	说明
access_token	是	调用接口凭证
touser	是	普通用户openid
msgtype	是	消息类型，video
media_id	是	发送的视频的媒体ID
thumb_media_id	是	缩略图的媒体ID
title	否	视频消息的标题
description	否	视频消息的描述

发送音乐消息

{

"touser":"OPENID",

"msgtype":"music",

"music":

{

"title":"MUSIC_TITLE",

"description":"MUSIC_DESCRIPTION",

"musicurl":"MUSIC_URL",

"hqmusicurl":"HQ_MUSIC_URL",

"thumb_media_id":"THUMB_MEDIA_ID"

}

参数	是否必须	说明
access_token	是	调用接口凭证
touser	是	普通用户openid
msgtype	是	消息类型，music
title	否	音乐标题
description	否	音乐描述
musicurl	是	音乐链接
hqmusicurl	是	高品质音乐链接，wifi环境优先使用该链接播放音乐
thumb_media_id	是	缩略图的媒体ID

发送图文消息

图文消息条数限制在10条以内，注意，如果图文数超过10，则将会无响应。

{

"touser":"OPENID",

"msgtype":"news",

"news":{

"articles": [

{

"title":"Happy Day",

"description":"Is Really A Happy Day",

"url":"URL",

"picurl":"PIC_URL"

{

"title":"Happy Day",

"description":"Is Really A Happy Day",

"url":"URL",

"picurl":"PIC_URL"

}

]

}

参数	是否必须	说明
access_token	是	调用接口凭证
touser	是	普通用户openid
msgtype	是	消息类型，news
title	否	标题
description	否	描述
url	否	点击后跳转的链接
picurl	否	图文消息的图片链接，支持JPG、PNG格式，较好的效果为大图640320，小图8080

高级群发接口

在公众平台网站上，为订阅号提供了每天一条的群发权限，为服务号提供每月（自然月）4条的群发权限。而对于某些具备开发能力的公众号运营者，可以通过高级群发接口，实现更灵活的群发能力。

请注意：

1、对于认证订阅号，群发接口每天可成功调用1次，此次群发可选择发送给全部用户或某个分组；

2、对于认证服务号虽然开发者使用高级群发接口的每日调用限制为100次，但是用户每月只能接收4条，无论在公众平台网站上，还是使用接口群发，用户每月只能接收4条群发消息，多于4条的群发将对该用户发送失败；

3、具备微信支付权限的公众号，在使用群发接口上传、群发图文消息类型时，可使用<a>标签加入外链；

4、开发者可以使用预览接口校对消息样式和排版，通过预览接口可发送编辑好的消息给指定用户校验效果。

上传图文消息素材【订阅号与服务号认证后均可用】

接口调用请求说明

http请求方式: POST

POST数据说明

POST数据示例如下：

{

"articles": [

{

"thumb_media_id":"qI6_Ze_6PtV7svjolgs-rN6stStuHIjs9_DidOHaj0Q-mwvBelOXCFZiq2OsIU-p",

"author":"xxx",

"title":"Happy Day",

"content_source_url":"www.qq.com",

"content":"content",

"digest":"digest",

"show_cover_pic":"1"

{

"thumb_media_id":"qI6_Ze_6PtV7svjolgs-rN6stStuHIjs9_DidOHaj0Q-mwvBelOXCFZiq2OsIU-p",

"author":"xxx",

"title":"Happy Day",

"content_source_url":"www.qq.com",

"content":"content",

"digest":"digest",

"show_cover_pic":"0"

}

]

}

参数	是否必须	说明
Articles	是	图文消息，一个图文消息支持1到10条图文
thumb_media_id	是	图文消息缩略图的media_id，可以在基础支持-上传多媒体文件接口中获得
author	否	图文消息的作者
title	是	图文消息的标题
content_source_url	否	在图文消息页面点击“阅读原文”后的页面
content	是	图文消息页面的内容，支持HTML标签
digest	否	图文消息的描述
show_cover_pic	否	是否显示封面，1为显示，0为不显示

返回说明

返回数据示例（正确时的JSON返回结果）：

{

"type":"news",

"media_id":"CsEf3ldqkAYJAU6EJeIkStVDSvffUJ54vqbThMgplD-VJXXof6ctX5fI6-aYyUiQ",

"created_at":1391857799

}

参数	说明
type	媒体文件类型，分别有图片（image）、语音（voice）、视频（video）和缩略图（thumb），次数为news，即图文消息
Media_id	媒体文件/图文消息上传后获取的唯一标识
created_at	媒体文件上传时间

错误时微信会返回错误码等信息，请根据错误码查询错误信息: 全局返回码说明 根据分组进行群发【订阅号与服务号认证后均可用】

接口调用请求说明

http请求方式: POST

POST数据说明

POST数据示例如下：

图文消息（注意图文消息的media_id需要通过上述方法来得到）：

{

"filter":{

"is_to_all":false

"group_id":"2"

"mpnews":{

"media_id":"123dsdajkasd231jhksad"

"msgtype":"mpnews"

}

文本：

{

"filter":{

"is_to_all":false

"group_id":"2"

"text":{

"content":"CONTENT"

"msgtype":"text"

}

语音（注意此处media_id需通过基础支持中的上传下载多媒体文件来得到）：

{

"filter":{

"is_to_all":false

"group_id":"2"

"voice":{

"media_id":"123dsdajkasd231jhksad"

"msgtype":"voice"

}

图片（注意此处media_id需通过基础支持中的上传下载多媒体文件来得到）：

{

"filter":{

"is_to_all":false

"group_id":"2"

"image":{

"media_id":"123dsdajkasd231jhksad"

"msgtype":"image"

}

视频

请注意，此处视频的media_id需通过POST请求到下述接口特别地得到： https://file.api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKEN

POST数据如下（此处media_id需通过基础支持中的上传下载多媒体文件来得到）：

{

"media_id": "rF4UdIMfYK3efUfyoddYRMU50zMiRmmt_l0kszupYh_SzrcW5Gaheq05p_lHuOTQ",

"title": "TITLE",

"description": "Description"

}

返回将为

{

"type":"video",

"media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",

"created_at":1398848981

}

然后，POST下述数据（将media_id改为上一步中得到的media_id），即可进行发送

{

"filter":{

"is_to_all":false

"group_id":"2"

"mpvideo":{

"media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",

"msgtype":"mpvideo"

}

参数	是否必须	说明
Filter	是	用于设定图文消息的接收者
is_to_all	否	用于设定是否向全部用户发送，值为true或false，选择true该消息群发给所有用户，选择false可根据group_id发送给指定群组的用户
Group_id	否	群发到的分组的group_id，参加用户管理中用户分组接口，若is_to_all值为true，可不填写group_id
Mpnews	是	用于设定即将发送的图文消息
Media_id	是	用于群发的消息的media_id
msgtype	是	群发的消息类型，图文消息为mpnews，文本消息为text，语音为voice，音乐为music，图片为image，视频为video
Title	否	消息的标题
description	否	消息的描述
Thumb_media_id	是	视频缩略图的媒体ID

返回说明

返回数据示例（正确时的JSON返回结果）：

{

"errcode":0,

"errmsg":"send job submission success",

"msg_id":34182

}

参数	说明
type	媒体文件类型，分别有图片（image）、语音（voice）、视频（video）和缩略图（thumb），图文消息为news
errcode	错误码
errmsg	错误信息
msg_id	消息ID

请注意：在返回成功时，意味着群发任务提交成功，并不意味着此时群发已经结束，所以，仍有可能在后续的发送过程中出现异常情况导致用户未收到消息，如消息有时会进行审核、服务器不稳定等。此外，群发任务一般需要较长的时间才能全部发送完毕，请耐心等待。

错误时微信会返回错误码等信息，请根据错误码查询错误信息: 全局返回码说明

根据OpenID列表群发【订阅号不可用，服务号认证后可用】

接口调用请求说明

http请求方式: POST

POST数据说明

POST数据示例如下：

图文消息（注意图文消息的media_id需要通过上述方法来得到）： {

"touser":[

"OPENID1",

"OPENID2"

"mpnews":{

"media_id":"123dsdajkasd231jhksad"

"msgtype":"mpnews"

}

文本：

{

"touser":[

"OPENID1",

"OPENID2"

"msgtype": "text",

"text": { "content": "hello from boxer."}

}

语音：

{

"touser":[

"OPENID1",

"OPENID2"

"voice":{

"media_id":"mLxl6paC7z2Tl-NJT64yzJve8T9c8u9K2x-Ai6Ujd4lIH9IBuF6-2r66mamn_gIT"

"msgtype":"voice"

}

图片：

{

"touser":[

"OPENID1",

"OPENID2"

"image":{

"media_id":"BTgN0opcW3Y5zV_ZebbsD3NFKRWf6cb7OPswPi9Q83fOJHK2P67dzxn11Cp7THat"

"msgtype":"image"

}

视频：

请注意，此处视频的media_id需通过POST请求到下述接口特别地得到： https://file.api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKEN

POST数据如下（此处media_id需通过基础支持中的上传下载多媒体文件来得到）：

{

"media_id": "rF4UdIMfYK3efUfyoddYRMU50zMiRmmt_l0kszupYh_SzrcW5Gaheq05p_lHuOTQ",

"title": "TITLE",

"description": "Description"

}

返回将为

{

"type":"video",

"media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",

"created_at":1398848981

}

然后，POST下述数据（将media_id改为上一步中得到的media_id），即可进行发送

{

"touser":[

"OPENID1",

"OPENID2"

"video":{

"media_id":"123dsdajkasd231jhksad",

"title":"TITLE",

"description":"DESCRIPTION"

"msgtype":"video"

}

参数	是否必须	说明
touser	是	填写图文消息的接收者，一串OpenID列表，OpenID最少个，最多10000个
mpnews	是	用于设定即将发送的图文消息
media_id	是	用于群发的图文消息的media_id
msgtype	是	群发的消息类型，图文消息为mpnews，文本消息为text，语音为voice，音乐为music，图片为image，视频为video
title	否	消息的标题
description	否	消息的描述
thumb_media_id	是	视频缩略图的媒体ID

返回说明

返回数据示例（正确时的JSON返回结果）：

{

"errcode":0,

"errmsg":"send job submission success",

"msg_id":34182

}

参数	说明
type	媒体文件类型，分别有图片（image）、语音（voice）、视频（video）和缩略图（thumb），次数为news，即图文消息
errcode	错误码
errmsg	错误信息
msg_id	消息ID

错误时微信会返回错误码等信息，请根据错误码查询错误信息: 全局返回码说明

删除群发【订阅号与服务号认证后均可用】

接口调用请求说明

http请求方式: POST

POST数据说明

POST数据示例如下：

{

"msg_id":30124

}

参数	是否必须	说明
msg_id	是	发送出去的消息ID

请注意，只有已经发送成功的消息才能删除删除消息只是将消息的图文详情页失效，已经收到的用户，还是能在其本地看到消息卡片。 另外，删除群发消息只能删除图文消息和视频消息，其他类型的消息一经发送，无法删除。

返回说明

返回数据示例（正确时的JSON返回结果）：

{

"errcode":0,

"errmsg":"ok"

}

参数	说明
errcode	错误码
errmsg	错误信息

错误时微信会返回错误码等信息，请根据错误码查询错误信息: 全局返回码说明

预览接口【订阅号与服务号认证后均可用】

开发者可通过该接口发送消息给指定用户，在手机端查看消息的样式和排版。

接口调用请求说明

http请求方式: POST

POST数据说明

POST数据示例如下：

图文消息（其中media_id与根据分组群发中的media_id相同）：

{

"touser":"OPENID",

"mpnews":{

"media_id":"123dsdajkasd231jhksad"

"msgtype":"mpnews"

}

文本：

{

"touser":"OPENID",

"text":{

"content":"CONTENT"

"msgtype":"text"

}

语音（其中media_id与根据分组群发中的media_id相同）：

{

"touser":"OPENID",

"voice":{

"media_id":"123dsdajkasd231jhksad"

"msgtype":"voice"

}

图片（其中media_id与根据分组群发中的media_id相同）：

{

"touser":"OPENID",

"image":{

"media_id":"123dsdajkasd231jhksad"

"msgtype":"image"

}

视频（其中media_id与根据分组群发中的media_id相同）：

{

"touser":"OPENID",

"mpvideo":{ "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",

"msgtype":"mpvideo"

}

参数	说明
touser	接收消息用户对应该公众号的openid
msgtype	群发的消息类型，图文消息为mpnews，文本消息为text，语音为voice，音乐为music，图片为image，视频为video
Media_id	用于群发的消息的media_id
content	发送文本消息时文本的内容

返回说明

返回数据示例（正确时的JSON返回结果）：

{

"errcode":0,

"errmsg":"send job submission success",

"msg_id":34182

}

参数	说明
errcode	错误码
errmsg	错误信息
msg_id	消息ID

查询群发消息发送状态【订阅号与服务号认证后均可用】

接口调用请求说明

http请求方式: POST

https://api.weixin.qq.com/cgi-bin/message/mass/get?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

{

"msg_id": "201053012"

}

参数	说明
msg_id	群发消息后返回的消息id

返回说明

返回数据示例（正确时的JSON返回结果）：

{

"msg_id":201053012,

"msg_status":"SEND_SUCCESS"

}

参数	说明
msg_id	群发消息后返回的消息id
msg_status	消息发送后的状态，SEND_SUCCESS表示发送成功

事件推送群发结果

由于群发任务提交后，群发任务可能在一定时间后才完成，因此，群发接口调用时，仅会给出群发任务是否提交成功的提示，若群发任务提交成功，则在群发任务结束时，会向开发者在公众平台填写的开发者URL（callback URL）推送事件。

推送的XML结构如下（发送成功时）：

<xml>

</xml>

参数	说明
ToUserName	公众号的微信号
FromUserName	公众号群发助手的微信号，为mphelper
CreateTime	创建时间的时间戳
MsgType	消息类型，此处为event
Event	事件信息，此处为MASSSENDJOBFINISH
MsgID	群发的消息ID
Status	群发的结构，为“send success”或“send fail”或“err(num)”。但send success时，也有可能因用户拒收公众号的消息、系统错误等原因造成少量用户接收失败。err(num)是审核失败的具体原因，可能的情况如下： err(10001), //涉嫌广告 err(20001), //涉嫌政治 err(20004), //涉嫌社会 err(20002), //涉嫌色情 err(20006), //涉嫌违法犯罪 err(20008), //涉嫌欺诈 err(20013), //涉嫌版权 err(22000), //涉嫌互推(互相宣传) err(21000), //涉嫌其他
TotalCount	group_id下粉丝数；或者openid_list中的粉丝数
FilterCount	过滤（过滤是指特定地区、性别的过滤、用户设置拒收的过滤，用户接收已超4条的过滤）后，准备发送的粉丝数，原则上，FilterCount = SentCount + ErrorCount
SentCount	发送成功的粉丝数
ErrorCount	发送失败的粉丝数

模板消息接口

模板消息仅用于公众号向用户发送重要的服务通知，只能用于符合其要求的服务场景中，如信用卡刷卡通知，商品购买成功通知等。不支持广告等营销类消息以及其它所有可能对用户造成骚扰的消息。

关于使用规则，请注意：

1、所有服务号都可以在功能->添加功能插件处看到申请模板消息功能的入口，但只有认证后的服务号才可以申请模板消息的使用权限并获得该权限；

2、需要选择公众账号服务所处的2个行业，每月可更改1次所选行业；

3、在所选择行业的模板库中选用已有的模板进行调用；

4、每个账号可以同时使用15个模板。

5、当前每个模板的日调用上限为100000次【2014年11月18日将接口调用频率从默认的日10000次提升为日100000次，可在MP登录后的开发者中心查看】。

关于接口文档，请注意：

1、模板消息调用时主要需要模板ID和模板中各参数的赋值内容；

2、模板中参数内容必须以".DATA"结尾，否则视为保留字；

3、模板保留符号"{{ }}"。

1 设置所属行业

2 获得模板ID

3 发送模板消息

4 事件推送

设置所属行业

设置行业可在MP中完成，每月可修改行业1次，账号仅可使用所属行业中相关的模板，为方便第三方开发者，提供通过接口调用的方式来修改账号所属行业，具体如下：

接口调用请求说明

http请求方式: POST

https://api.weixin.qq.com/cgi-bin/template/api_set_industry?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

{

"industry_id1":"1",

"industry_id2":"4"

}

参数说明

参数	是否必须	说明
industry_id1	是	公众号模板消息所属行业编号
industry_id2	是	公众号模板消息所属行业编号

行业代码查询

主行业	副行业	代码
IT科技	互联网/电子商务	1
IT科技	IT软件与服务	2
IT科技	IT硬件与设备	3
IT科技	电子技术	4
IT科技	通信与运营商	5
IT科技	网络游戏	6
金融业	银行	7
金融业	基金\|理财\|信托	8
金融业	保险	9
餐饮	餐饮	10
酒店旅游	酒店	11
酒店旅游	旅游	12
运输与仓储	快递	13
运输与仓储	物流	14
运输与仓储	仓储	15
教育	培训	16
教育	院校	17
*与公共事业	学术科研	18
*与公共事业	交警	19
*与公共事业	博物馆	20
*与公共事业	公共事业\|非盈利机构	21
医药护理	医药医疗	22
医药护理	护理美容	23
医药护理	保健与卫生	24
交通工具	汽车相关	25
交通工具	摩托车相关	26
交通工具	火车相关	27
交通工具	飞机相关	28
房地产	建筑	29
房地产	物业	30
消费品	消费品	31
商业服务	法律	32
商业服务	会展	33
商业服务	中介服务	34
商业服务	认证	35
商业服务	审计	36
文体娱乐	传媒	37
文体娱乐	体育	38
文体娱乐	娱乐休闲	39
印刷	印刷	40
其它	其它	41

获得模板ID

从行业模板库选择模板到账号后台，获得模板ID的过程可在MP中完成。为方便第

三方开发者，提供通过接口调用的方式来修改账号所属行业，具体如下：

接口调用请求说明

http请求方式: POST

https://api.weixin.qq.com/cgi-bin/template/api_add_template?

access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

{

"template_id_short":"TM00015"

}

参数说明

参数	是否必须	说明
template_id_short	是	模板库中模板的编号，有“TM”和“OPENTMTM”等形式

返回码说明

在调用模板消息接口后，会返回JSON数据包。正常时的返回JSON数据包示例：

{

"errcode":0,

"errmsg":"ok",

"template_id":"Doclyl5uP7Aciu-qZ7mJNPtWkbkYnWBWVja26EGbNyk"

}

发送模板消息

接口调用请求说明

http请求方式: POST

https://api.weixin.qq.com/cgi-bin/message/template/send?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

{

"touser":"OPENID",

"template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",

"url":"http://weixin.qq.com/download",

"topcolor":"#FF0000",

"data":{

"first": {

"value":"恭喜你购买成功！",

"color":"#173177"

"keynote1":{

"value":"巧克力",

"color":"#173177"

"keynote2": {

"value":"39.8元",

"color":"#173177"

"keynote3": {

"value":"2014年9月16日",

"color":"#173177"

"remark":{

"value":"欢迎再次购买！",

"color":"#173177"

}

返回码说明

在调用模板消息接口后，会返回JSON数据包。正常时的返回JSON数据包示例：

{

"errcode":0,

"errmsg":"ok",

"msgid":200228332

}

事件推送

在模版消息发送任务完成后，微信服务器会将是否送达成功作为通知，发送到开发者中心中填写的服务器配置地址中。

1、送达成功时，推送的XML如下：

<xml>

</xml>

参数说明

参数	说明
ToUserName	公众号微信号
FromUserName	接收模板消息的用户的openid
CreateTime	创建时间
MsgType	消息类型是事件
Event	事件为模板消息发送结束
MsgID	消息id
Status	发送状态为成功

2、送达由于用户拒收（用户设置拒绝接收公众号消息）而失败时，推送的XML如下：

<xml>

</xml>

参数说明

参数	说明
ToUserName	公众号微信号
FromUserName	接收模板消息的用户的openid
CreateTime	创建时间
MsgType	消息类型是事件
Event	事件为模板消息发送结束
MsgID	消息id
Status	发送状态为用户拒绝接收

3、送达由于其他原因失败时，推送的XML如下：

<xml>

</xml>

参数说明

参数	说明
ToUserName	公众号微信号
FromUserName	接收模板消息的用户的openid
CreateTime	创建时间
MsgType	消息类型是事件
Event	事件为模板消息发送结束
MsgID	消息id
Status	发送状态为发送失败（非用户拒绝）

微信开发者文档

码农公寓

相关文章