1.客服消息
当用户和公众号产生特定动作的交互时(具体动作列表请见下方说明),微信将会把消息数据推送给开发者,开发者可以在一段时间内(目前修改为48小时)调用客服接口,通过POST一个JSON数据包来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能,方便开发者为用户提供更加优质的服务。
目前允许的动作列表如下(公众平台会根据运营情况更新该列表,不同动作触发后,允许的客服接口下发消息条数不同,下发条数达到上限后,会遇到错误返回码,具体请见返回码说明页):
1、用户发送信息 2、点击自定义菜单(仅有点击推事件、扫码推事件、扫码推事件且弹出“消息接收中”提示框这3种菜单类型是会触发客服接口的) 3、关注公众号 4、扫描二维码 5、支付成功 6、用户维权
为了帮助公众号使用不同的客服身份服务不同的用户群体,客服接口进行了升级,开发者可以管理客服账号,并设置客服账号的头像和昵称。该能力针对所有拥有客服接口权限的公众号开放。
另外,请开发者注意,本接口中所有使用到media_id的地方,现在都可以使用素材管理中的永久素材media_id了。
1.1.客服账号管理
开发者在根据开发文档的要求完成开发后,使用6.0.2版及以上版本的微信用户在与公众号进行客服沟通,公众号使用不同的客服账号进行回复后,用户可以看到对应的客服头像和昵称。
请注意,必须先在公众平台官网为公众号设置微信号后才能使用该能力。
1.1.1.添加客服账号
1.1.1.1.接口说明
开发者可以通过本接口为公众号添加客服账号,每个公众号最多添加10个客服账号。
1.1.1.2.调用接口(post方法)
https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN
1.1.1.3.调用实例
{
"kf_account" : "test1@test",
"nickname" : "客服1",
"password" : "pswmd5",
}
1.1.1.4.返回说明
{
"errcode" : 0,
"errmsg" : "ok",
}
1.1.2.修改客服账号
1.1.2.1.接口说明
开发者可以通过本接口为公众号修改客服账号。
1.1.2.2.调用接口(post方法)
https://api.weixin.qq.com/customservice/kfaccount/update?access_token=ACCESS_TOKEN
1.1.2.3.调用实例
{
"kf_account" : "test1@test",
"nickname" : "客服1",
"password" : "pswmd5",
}
1.1.2.4.返回说明
{
"errcode" : 0,
"errmsg" : "ok",
}
1.1.3.删除客服账号
1.1.3.1.接口说明
开发者可以通过该接口为公众号删除客服帐号。
1.1.3.2.调用接口(get方法)
https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN
1.1.3.3.调用实例
{
"kf_account" : "test1@test",
"nickname" : "客服1",
"password" : "pswmd5",
}
1.1.3.4.返回说明
{
"errcode" : 0,
"errmsg" : "ok",
}
1.1.4.设置客服账号的头像
1.1.4.1.接口说明
开发者可调用本接口来上传图片作为客服人员的头像,头像图片文件必须是jpg格式,推荐使用640*640大小的图片以达到最佳效果。
1.1.4.2.调用接口(post/form)
1.1.4.3.调用实例
使用curl命令,用FORM表单方式上传一个多媒体文件,curl命令的具体用法请自行了解
1.1.4.4.返回说明
{
"errcode" : 0,
"errmsg" : "ok",
}
1.1.5.获取所有客服账号
1.1.5.1.接口说明
开发者通过本接口,获取公众号中所设置的客服基本信息,包括客服工号、客服昵称、客服登录账号。
1.1.5.2.调用接口(get方法)
https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN
1.1.5.3.返回说明
{ "kf_list": [ { "kf_account": "test1@test", "kf_nick": "ntest1", "kf_id": "1001" "kf_headimgurl": " http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0" }, { "kf_account": "test2@test", "kf_nick": "ntest2", "kf_id": "1002" "kf_headimgurl": " http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw /0" }, { "kf_account": "test3@test", "kf_nick": "ntest3", "kf_id": "1003" "kf_headimgurl": " http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw /0" } ] }
1.1.6.接口的统一参数说明
access_token:调用接口凭证,必须
kf_account: 完整客服账号,格式为:账号前缀@公众号微信号,必须
kf_nick: 客服昵称,必须
kf_id:客服工号,必须
nickname:客服昵称,最长6个汉字或12个英文字符,必须
password:客服账号登录密码,格式为密码明文的32位加密MD5值。该密码仅用于在公众平台官网的多客服功能中使用,若不使用多客服功能,则不必设置密码,必须
media:该参数仅在设置客服头像时出现,是form-data中媒体文件标识,有filename、filelength、content-type等信息,必须
1.2.客服接口-发消息
1.2.1.调用接口(post方法)
https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN
1.2.2.调用实例
发送文本消息
{ "touser":"OPENID", "msgtype":"text", "text": { "content":"Hello World" } }
发送图片消息
{ "touser":"OPENID", "msgtype":"image", "image": { "media_id":"MEDIA_ID" } }
发送语音消息
{ "touser":"OPENID", "msgtype":"voice", "voice": { "media_id":"MEDIA_ID" } }
发送视频消息
{ "touser":"OPENID", "msgtype":"video", "video": { "media_id":"MEDIA_ID", "thumb_media_id":"MEDIA_ID", "title":"TITLE", "description":"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" } }
发送图文消息(点击跳转到外链) 图文消息条数限制在8条以内,注意,如果图文数超过8,则将会无响应。
{ "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" } ] } }
发送图文消息(点击跳转到图文消息页面) 图文消息条数限制在8条以内,注意,如果图文数超过8,则将会无响应。
{ "touser":"OPENID", "msgtype":"mpnews", "mpnews": { "media_id":"MEDIA_ID" } }
发送卡券
{ "touser":"OPENID", "msgtype":"wxcard", "wxcard":{ "card_id":"123dsdajkasd231jhksad", "card_ext": "{\"code\":\"\",\"openid\":\"\",\"timestamp\":\"1402057159\",\"signature\":\"017bb17407c8e0058a66d72dcc61632b70f511ad\"}" }, }
请注意,如果需要以某个客服帐号来发消息(在微信6.0.2及以上版本中显示自定义头像),则需在JSON数据包的后半部分加入customservice参数,例如发送文本消息则改为:
{ "touser":"OPENID", "msgtype":"text", "text": { "content":"Hello World" }, "customservice": { "kf_account": "test1@kftest" } }
1.2.3.参数说明
access_token: 调用接口凭证,必须
touser: 普通用户openid,必须
msgtype:消息类型,文本为text,图片为image,语音为voice,视频消息为video,音乐消息为music,图文消息(点击跳转到外链)为news,图文消息(点击跳转到图文消息页面)为mpnews,卡券为wxcard,必须
content: 文本消息内容,必须
media_id: 发送的图片/语音/视频/图文消息(点击跳转到图文消息页)的媒体ID,必须
thumb_media_id:缩略图的媒体ID,必须
title: 图文消息/视频消息/音乐消息的标题,必须
description: 图文消息/视频消息/音乐消息的描述,必须
musicurl:音乐链接,必须
hqmusicurl:高品质音乐链接,wifi环境优先使用该链接播放音乐,必须
url:图文消息被点击后跳转的链接,必须
picurl: 图文消息的图片链接,支持JPG、PNG格式,较好的效果为大图640*320,小图80*80,必须
2.高级群发接口
在公众平台网站上,为订阅号提供了每天一条的群发权限,为服务号提供每月(自然月)4条的群发权限。而对于某些具备开发能力的公众号运营者,可以通过高级群发接口,实现更灵活的群发能力。
请注意:
1、对于认证订阅号,群发接口每天可成功调用1次,此次群发可选择发送给全部用户或某个分组;
2、对于认证服务号虽然开发者使用高级群发接口的每日调用限制为100次,但是用户每月只能接收4条,无论在公众平台网站上,还是使用接口群发,用户每月只能接收4条群发消息,多于4条的群发将对该用户发送失败;
3、具备微信支付权限的公众号,在使用群发接口上传、群发图文消息类型时,可使用<a>标签加入外链;
4、开发者可以使用预览接口校对消息样式和排版,通过预览接口可发送编辑好的消息给指定用户校验效果。
群发图文消息的过程如下:
1、首先,预先将图文消息中需要用到的图片,使用上传图文消息内图片接口,上传成功并获得图片URL
2、上传图文消息素材,需要用到图片时,请使用上一步获取的图片URL
3、使用对用户分组的群发,或对OpenID列表的群发,将图文消息群发出去
4、在上述过程中,如果需要,还可以预览图文消息、查询群发状态,或删除已群发的消息等
群发图片、文本等其他消息类型的过程如下:
1、如果是群发文本消息,则直接根据下面的接口说明进行群发即可
2、如果是群发图片、视频等消息,则需要预先通过素材管理接口准备好mediaID
关于群发时使用is_to_all为true使其进入公众号在微信客户端的历史消息列表:
1、使用is_to_all为true且成功群发,会使得此次群发进入历史消息列表。
2、为防止异常,认证订阅号在一天内,只能使用is_to_all为true进行群发一次,或者在公众平台官网群发(不管本次群发是对全体还是对某个分组)一次。以避免一天内有2条群发进入历史消息列表。
3、类似地,服务号在一个月内,使用is_to_all为true群发的次数,加上公众平台官网群发(不管本次群发是对全体还是对某个分组)的次数,最多只能是4次。
4、设置is_to_all为false时是可以多次群发的,但每个用户只会收到最多4条,且这些群发不会进入历史消息列表。
另外,请开发者注意,本接口中所有使用到media_id的地方,现在都可以使用素材管理中的永久素材media_id了。请但注意,使用同一个素材群发出去的链接是一样的,这意味着,删除某一次群发,会导致整个链接失效。
2.1.上传图文消息内的图片获取url[订阅号与服务号认证后均可用]
2.1.1.接口说明
请注意,本接口所上传的图片不占用公众号的素材库中图片数量的5000个的限制。图片仅支持jpg/png格式,大小必须在1MB以下。
2.1.2.调用接口(post方法)
https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN
2.1.3.调用实例
curl -F [email protected] "https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN"
2.1.4.参数说明
access_token: 调用接口凭证,必须
media: form-data中媒体文件标识,有filename、filelength、content-type等信息,必须
2.1.5.返回说明
{
"url": "http://mmbiz.qpic.cn/mmbiz/gLO17UPS6FS2xsypf378iaNhWacZ1G1UplZYWEYfwvuU6Ont96b1roYs CNFwaRrSaKTPCUdBK9DgEHicsKwWCBRQ/0"
}
2.2.上传图文消息素材[订阅号与服务号认证后均可用]
2.2.1.调用接口
https://api.weixin.qq.com/cgi-bin/media/uploadnews?access_token=ACCESS_TOKEN
2.2.2.调用实例
{ "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 } ] }
2.2.3.参数说明
Articles:图文消息,一个图文消息支持1到8条图文,必须
thumb_media_id: 图文消息缩略图的media_id,可以在基础支持-上传多媒体文件接口中获得,必须
author:图文消息的作者,非必须
title: 图文消息的标题,必须
content_source_url:在图文消息页面点击“阅读原文”后的页面,非必须
content: 图文消息页面的内容,支持HTML标签。具备微信支付权限的公众号,可以使用a标签,其他公众号不能使用,必须
digest: 图文消息的描述,非必须
show_cover_pic:是否显示封面,1为显示,0为不显示,非必须
2.2.4.返回说明
{ "type":"news", "media_id":"CsEf3ldqkAYJAU6EJeIkStVDSvffUJ54vqbThMgplD-VJXXof6ctX5fI6-aYyUiQ", "created_at":1391857799 }
2.2.5.参数说明
type: 媒体文件类型,分别有图片(image)、语音(voice)、视频(video)和缩略图(thumb),次数为news,即图文消息
media_id: 媒体文件/图文消息上传后获取的唯一标识
created_at:媒体文件上传时间
2.3.根据分组进行群发[订阅号与服务号认证后均可用]
2.3.1.调用接口(post方法)
https://api.weixin.qq.com/cgi-bin/message/mass/sendall?access_token=ACCESS_TOKEN
2.3.2.调用实例
图文消息(注意图文消息的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" }
卡券消息(注意图文消息的media_id需要通过上述方法来得到):
{ "filter":{ "is_to_all":false, "group_id":"2" }, "wxcard":{ "card_id":"123dsdajkasd231jhksad" }, "msgtype":"wxcard" }
2.3.3.参数说明
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,卡券为wxcard,必须
title: 消息的标题,非必须
description: 消息的描述,非必须
thumb_media_id:视频缩略图的媒体ID,必须
2.3.4.返回说明
{ "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 }
2.3.5.返回参数说明
type:媒体文件类型,分别有图片(image)、语音(voice)、视频(video)和缩略图(thumb),图文消息为news
errcode: 错误码
errmsg: 错误信息
msg_id: 消息发送任务的ID
msg_data_id:消息的数据ID,该字段只有在群发图文消息时,才会出现。可以用于在图文分析数据接口中,获取到对应的图文消息的数据,是图文分析数据接口中的msgid字段中的前半部分,详见图文分析数据接口中的msgid字段的介绍。
2.3.6.返回注意事项
在返回成功时,意味着群发任务提交成功,并不意味着此时群发已经结束,所以,仍有可能在后续的发送过程中出现异常情况导致用户未收到消息,如消息有时会进行审核、服务器不稳定等。此外,群发任务一般需要较长的时间才能全部发送完毕,请耐心等待。
2.4.根据OPENID列表群发[订阅号不可用,服务号认证后可用]
2.4.1.调用接口(post方法)
https://api.weixin.qq.com/cgi-bin/message/mass/send?access_token=ACCESS_TOKEN
2.4.2.调用实例
图文消息(注意图文消息的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://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":[ "OPENID1", "OPENID2" ], "wxcard": {"card_id":"123dsdajkasd231jhksad"} "msgtype":"wxcard" }
2.4.3.参数说明
touser: 填写图文消息的接收者,一串OpenID列表,OpenID最少2个,最多10000个,必须
mpnews: 用于设定即将发送的图文消息,必须
media_id:用于群发的图文消息的media_id,必须
msgtype:群发的消息类型,图文消息为mpnews,文本消息为text,语音为voice,音乐为music,图片为image,视频为video,卡券为wxcard,必须
title: 消息的标题,非必须
description:消息的描述,非必须
thumb_media_id: 视频缩略图的媒体ID
2.4.4.返回说明
{ "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 }
2.4.5.返回参数说明
type:媒体文件类型,分别有图片(image)、语音(voice)、视频(video)和缩略图(thumb),次数为news,即图文消息
errcode: 错误码
errmsg: 错误信息
msg_id: 消息发送任务的ID
msg_data_id:消息的数据ID,,该字段只有在群发图文消息时,才会出现。可以用于在图文分析数据接口中,获取到对应的图文消息的数据,是图文分析数据接口中的msgid字段中的前半部分,详见图文分析数据接口中的msgid字段的介绍。
2.4.6.返回注意事项
在返回成功时,意味着群发任务提交成功,并不意味着此时群发已经结束,所以,仍有可能在后续的发送过程中出现异常情况导致用户未收到消息,如消息有时会进行审核、服务器不稳定等。此外,群发任务一般需要较长的时间才能全部发送完毕,请耐心等待。
2.5.删除群发[订阅号与服务号认证后均可用]
2.5.1.接口说明
由于技术限制,群发只有在刚发出的半小时内可以删除,发出半小时之后将无法被删除。
请注意:
1、只有已经发送成功的消息才能删除
2、删除消息是将消息的图文详情页失效,已经收到的用户,还是能在其本地看到消息卡片。
3、删除群发消息只能删除图文消息和视频消息,其他类型的消息一经发送,无法删除。
4、如果多次群发发送的是一个图文消息,那么删除其中一次群发,就会删除掉这个图文消息也,导致所有群发都失效
2.5.2.调用接口(post方法)
https://api.weixin.qq.com/cgi-bin/message/mass/delete?access_token=ACCESS_TOKEN
2.5.3.调用实例
{ "msg_id":30124 }
2.5.4.参数说明
msg_id: 发送出去的消息ID,必须
2.5.5.返回说明
{ "errcode":0, "errmsg":"ok" }
2.5.6.返回参数说明
errcode: 错误码
errmsg: 错误信息
2.6.预览接口[订阅号与服务号认证后均可用]
2.6.1.接口说明
开发者可通过该接口发送消息给指定用户,在手机端查看消息的样式和排版。为了满足第三方平台开发者的需求,在保留对openID预览能力的同时,增加了对指定微信号发送预览的能力,但该能力每日调用次数有限制(100次),请勿滥用。
2.6.2.调用接口(post方法)
https://api.weixin.qq.com/cgi-bin/message/mass/preview?access_token=ACCESS_TOKEN
2.6.3.调用实例
图文消息(其中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", "wxcard":{ "card_id":"123dsdajkasd231jhksad", "card_ext": "{\"code\":\"\",\"openid\":\"\",\"timestamp\":\"1402057159\",\"signature\":\"017bb17407c8e0058a66d72dcc61632b70f511ad\"}" }, "msgtype":"wxcard" }
请注意,上述JSON数据中的touser字段都可以改为towxname,这样就可以针对微信号进行预览(而非openID),towxname和touser同时赋值时,以towxname优先。修改后JSON数据如下(以图文消息为例): 图文消息:
{ "towxname":"示例的微信号", "mpnews":{ "media_id":"123dsdajkasd231jhksad" }, "msgtype":"mpnews" }
2.6.4.参数说明
touser: 接收消息用户对应该公众号的openid,该字段也可以改为towxname,以实现对微信号的预览
msgtype: 群发的消息类型,图文消息为mpnews,文本消息为text,语音为voice,音乐为music,图片为image,视频为video,卡券为wxcard
media_id:用于群发的消息的media_id
content:发送文本消息时文本的内容
2.6.5.返回说明
{ "errcode":0, "errmsg":"preview success", "msg_id":34182 }
2.6.6.返回参数说明
errcode: 错误码
errmsg: 错误信息
msg_id: 消息ID
2.7.查询群发消息发送状态[订阅号与服务号认证后均可用]
2.7.1.调用接口(post方法)
https://api.weixin.qq.com/cgi-bin/message/mass/get?access_token=ACCESS_TOKEN
2.7.2.调用实例
{
"msg_id": "201053012"
}
2.7.3.参数说明
msg_id: 群发消息后返回的消息id
2.7.4.返回说明
{ "msg_id":201053012, "msg_status":"SEND_SUCCESS" }
2.7.5.返回参数说明
msg_id:群发消息后返回的消息id
msg_status:消息发送后的状态,SEND_SUCCESS表示发送成功
2.8.事件推送群发结果
2.8.1.推送说明
由于群发任务提交后,群发任务可能在一定时间后才完成,因此,群发接口调用时,仅会给出群发任务是否提交成功的提示,若群发任务提交成功,则在群发任务结束时,会向开发者在公众平台填写的开发者URL(callback URL)推送事件。
需要注意,由于群发任务彻底完成需要较长时间,将会在群发任务即将完成的时候,就推送群发结果,此时的推送人数数据将会与实际情形存在一定误差
2.8.2.推送url
<xml> <ToUserName><![CDATA[gh_3e8adccde292]]></ToUserName> <FromUserName><![CDATA[oR5Gjjl_eiZoUpGozMo7dbBJ362A]]></FromUserName> <CreateTime>1394524295</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[MASSSENDJOBFINISH]]></Event> <MsgID>1988</MsgID> <Status><![CDATA[sendsuccess]]></Status> <TotalCount>100</TotalCount> <FilterCount>80</FilterCount> <SentCount>75</SentCount> <ErrorCount>5</ErrorCount> </xml>
2.8.3.参数说明
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: 发送失败的粉丝数
3.模板消息接口
模板消息仅用于公众号向用户发送重要的服务通知,只能用于符合其要求的服务场景中,如信用卡刷卡通知,商品购买成功通知等。不支持广告等营销类消息以及其它所有可能对用户造成骚扰的消息。
关于使用规则,请注意:
1、所有服务号都可以在功能->添加功能插件处看到申请模板消息功能的入口,但只有认证后的服务号才可以申请模板消息的使用权限并获得该权限; 2、需要选择公众账号服务所处的2个行业,每月可更改1次所选行业; 3、在所选择行业的模板库中选用已有的模板进行调用; 4、每个账号可以同时使用25个模板。 5、当前每个账号的模板消息的日调用上限为10万次,单个模板没有特殊限制。【2014年11月18日将接口调用频率从默认的日1万次提升为日10万次,可在MP登录后的开发者中心查看】。当账号粉丝数超过10W/100W/1000W时,模板消息的日调用上限会相应提升,以公众号MP后台开发者中心页面中标明的数字为准。
关于接口文档,请注意:
1、模板消息调用时主要需要模板ID和模板中各参数的赋值内容; 2、模板中参数内容必须以".DATA"结尾,否则视为保留字; 3、模板保留符号"{{ }}"。
3.1.设置所属的行业
3.1.1.接口说明
设置行业可在MP中完成,每月可修改行业1次,账号仅可使用所属行业中相关的模板,为方便第三方开发者,提供通过接口调用的方式来修改账号所属行业。
3.1.2.调用接口(post方法)
https://api.weixin.qq.com/cgi-bin/template/api_set_industry?access_token=ACCESS_TOKEN
3.1.3.调用实例
{
"industry_id1":"1",
"industry_id2":"4"
}
3.1.4.参数说明
industry_id1:公众号模板消息所属行业编号,必须
industry_id2: 公众号模板消息所属行业编号,必须
3.1.5.行业代码查询
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 |
3.2.获取设置的行业信息
3.2.1.接口说明
获取帐号设置的行业信息,可在MP中查看行业信息,为方便第三方开发者,提供通过接口调用的方式来获取帐号所设置的行业信息。
3.2.2.调用接口(get方法)
https://api.weixin.qq.com/cgi-bin/template/get_industry?access_token=ACCESS_TOKEN
3.2.3.参数说明
access_token: 接口调用凭证,必须
3.2.4.返回说明
{
"primary_industry":{"first_class":"运输与仓储","second_class":"快递"},
"secondary_industry":{"first_class":"IT科技","second_class":"互联网|电子商务"}
}
3.2.5.返回参数说明
primary_industry:帐号设置的主营行业
secondary_industry:帐号设置的副营行业
3.3.获取模板ID
3.3.1.接口说明
从行业模板库选择模板到帐号后台,获得模板ID的过程可在MP中完成。为方便第三方开发者,提供通过接口调用的方式来获取模板ID。
3.3.2.调用接口(post方法)
https://api.weixin.qq.com/cgi-bin/template/api_add_template?access_token=ACCESS_TOKEN
3.3.3.调用实例
{
"template_id_short":"TM00015"
}
3.3.4.参数说明
template_id_short:模板库中模板的编号,有“TM**”和“OPENTMTM**”等形式,必须
3.3.5.返回说明
{
"errcode":0,
"errmsg":"ok",
"template_id":"Doclyl5uP7Aciu-qZ7mJNPtWkbkYnWBWVja26EGbNyk"
}
3.4.获取模板列表
3.4.1.接口说明
获取已添加至帐号下所有模板列表,可在MP中查看模板列表信息,为方便第三方开发者,提供通过接口调用的方式来获取帐号下所有模板信息。
3.4.2.调用接口(get方法)
https://api.weixin.qq.com/cgi-bin/template/get_all_private_template?access_token=ACCESS_TOKEN
3.4.3.参数说明
access_token: 接口调用凭证,必须
3.4.4.返回说明
{ "template_list": [{ "template_id": "iPk5sOIt5X_flOVKn5GrTFpncEYTojx6ddbt8WYoV5s", "title": "领取奖金提醒", "primary_industry": "IT科技", "deputy_industry": "互联网|电子商务", "content": "{ {result.DATA} }\n\n领奖金额:{ {withdrawMoney.DATA} }\n领奖 时间:{ {withdrawTime.DATA} }\n银行信息:{ {cardInfo.DATA} }\n到账时间: { {arrivedTime.DATA} }\n{ {remark.DATA} }", "example": "您已提交领奖申请\n\n领奖金额:xxxx元\n领奖时间:2013-10-10 12:22:22\n银行信息:xx银行(尾号xxxx)\n到账时间:预计xxxxxxx\n\n预计将于xxxx到达您的银行卡" }] }
3.4.5.返回参数说明
template_id: 模板ID
title: 模板标题
primary_industry: 模板所属行业的一级行业
deputy_industry: 模板所属行业的二级行业
content:模板内容
example:模板示例
3.5.删除模板
3.5.1.接口说明
删除模板可在MP中完成,为方便第三方开发者,提供通过接口调用的方式来删除某帐号下的模板。
3.5.2.调用接口(post方法)
https://api,weixin.qq.com/cgi-bin/template/del_private_template?access_token=ACCESS_TOKEN
3.5.3.调用实例
{
“template_id”=”Dyvp3-Ff0cnail_CDSzk1fIc6-9lOkxsQE7exTJbwUE”
}
3.5.4.参数说明
template_id: 公众帐号下模板消息ID,必须
3.5.5.返回说明
{
"errcode":0,"errmsg":"ok"
}
3.6.发送模板消息
3.6.1.调用接口
https://api.weixin.qq.com/cgi-bin/message/template/send?access_token=ACCESS_TOKEN
3.6.2.调用实例
{ "touser":"OPENID", "template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY", "url":"http://weixin.qq.com/download", "data":{ "first": { "value":"恭喜你购买成功!", "color":"#173177" }, "keynote1":{ "value":"巧克力", "color":"#173177" }, "keynote2": { "value":"39.8元", "color":"#173177" }, "keynote3": { "value":"2014年9月22日", "color":"#173177" }, "remark":{ "value":"欢迎再次购买!", "color":"#173177" } } }
3.6.3.返回码说明
{ "errcode":0, "errmsg":"ok", "msgid":200228332 }
3.7.事件推送
3.7.1.推送说明
在模版消息发送任务完成后,微信服务器会将是否送达成功作为通知,发送到开发者中心中填写的服务器配置地址中。
3.7.2.推送成功xml
<xml> <ToUserName><![CDATA[gh_7f083739789a]]></ToUserName> <FromUserName><![CDATA[oia2TjuEGTNoeX76QEjQNrcURxG8]]></FromUserName> <CreateTime>1395658920</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[TEMPLATESENDJOBFINISH]]></Event> <MsgID>200163836</MsgID> <Status><![CDATA[success]]></Status> </xml>
3.7.3.参数说明
ToUserName:公众号微信号
FromUserName:接收模板消息的用户的openid
CreateTime:创建时间
MsgType:消息类型是事件
Event: 事件为模板消息发送结束
MsgID: 消息id
Status: 发送状态为成功
3.7.4.用户拒收推送失败XML(用户设置拒绝接收公众号消息):
<xml> <ToUserName><![CDATA[gh_7f083739789a]]></ToUserName> <FromUserName><![CDATA[oia2TjuEGTNoeX76QEjQNrcURxG8]]></FromUserName> <CreateTime>1395658984</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[TEMPLATESENDJOBFINISH]]></Event> <MsgID>200163840</MsgID> <Status><![CDATA[failed:user block]]></Status> </xml>
3.7.5.参数说明
ToUserName: 公众号微信号
FromUserName:接收模板消息的用户的openid
CreateTime:创建时间
MsgType:消息类型是事件
Event:事件为模板消息发送结束
MsgID: 消息id
Status: 发送状态为用户拒绝接收
3.7.6.其他原因推送失败XML:
<xml> <ToUserName><![CDATA[gh_7f083739789a]]></ToUserName> <FromUserName><![CDATA[oia2TjuEGTNoeX76QEjQNrcURxG8]]></FromUserName> <CreateTime>1395658984</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[TEMPLATESENDJOBFINISH]]></Event> <MsgID>200163840</MsgID> <Status><![CDATA[failed: system failed]]></Status> </xml>
3.7.7.参数说明
ToUserName:公众号微信号
FromUserName:接收模板消息的用户的openid
CreateTime:创建时间
MsgType: 消息类型是事件
Event: 事件为模板消息发送结束
MsgID:消息id
Status: 发送状态为发送失败(非用户拒绝)