一、说明
当用户和公众号产生特定动作的交互时(具体动作列表请见下方说明),微信将会把消息数据推送给开发者,开发者可以在一段时间内(目前修改为48小时)调用客服接口,通过POST一个JSON数据包来发送消息给普通用户。
二、动作列表
动作列表如下(公众平台会根据运营情况更新该列表,不同动作触发后,允许的客服接口下发消息条数不同,下发条数达到上限后,会遇到错误返回码):
- 用户发送信息
- 点击自定义菜单(仅有点击推事件、扫码推事件、扫码推事件且弹出“消息接收中”提示框这3种菜单类型是会触发客服接口的)
- 关注公众号
- 扫描二维码
- 支付成功
- 用户维权
三、具体接口-客服账号管理
客服消息依托于客服账号,而客服账号可以通过接口管理。
3.1 添加客服帐号
每个公众号最多添加10个客服账号,地址为:
post-https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN
相关字段为:
字段 | 描述 |
---|---|
kf_account | 客服账号 |
nickname | 昵称 |
password | 密码 |
3.2 修改客服账号
地址为:
post-https://api.weixin.qq.com/customservice/kfaccount/update?access_token=ACCESS_TOKEN
相关字段为:
字段 | 描述 |
---|---|
kf_account | 客服账号 |
nickname | 昵称 |
password | 密码 |
3.3 删除客服账号
地址为:
get-https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN
相关字段为:
字段 | 描述 |
---|---|
kf_account | 客服账号 |
nickname | 昵称 |
password | 密码 |
3.4 设置客服账号头像
可调用本接口来上传图片作为客服人员的头像,头像图片文件必须是jpg格式,推荐使用640*640大小的图片以达到最佳效果。
地址为:
POST/FORM-http://api.weixin.qq.com/customservice/kfaccount/uploadheadimg?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT
调用示例:使用curl命令,用FORM表单方式上传一个多媒体文件,curl命令的具体用法请自行了解
3.5 获取所有客服账号
获取公众号中所设置的客服基本信息,包括客服工号、客服昵称、客服登录账号、客服头像。
地址为:
get-https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN
四、具体接口–发消息
地址为:
post-https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN
4.1 文本消息
{
"touser":"OPENID",
"msgtype":"text",
"text":
{
"content":"Hello World"
}
}
content支持插入跳小程序的文字链,如
文本内容<a href="http://www.qq.com" data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>
注意:data-miniprogram-appid对应的小程序必须与公众号有绑定关系
4.2图片消息
{
"touser":"OPENID",
"msgtype":"image",
"image":
{
"media_id":"MEDIA_ID"
}
}
4.3语音消息
{
"touser":"OPENID",
"msgtype":"voice",
"voice":
{
"media_id":"MEDIA_ID"
}
}
4.4视频消息
{
"touser":"OPENID",
"msgtype":"video",
"video":
{
"media_id":"MEDIA_ID",
"thumb_media_id":"MEDIA_ID",
"title":"TITLE",
"description":"DESCRIPTION"
}
}
4.5音乐消息
{
"touser":"OPENID",
"msgtype":"music",
"music":
{
"title":"MUSIC_TITLE",
"description":"MUSIC_DESCRIPTION",
"musicurl":"MUSIC_URL",
"hqmusicurl":"HQ_MUSIC_URL",
"thumb_media_id":"THUMB_MEDIA_ID"
}
}
4.5图文消息-点击后转到url(图文消息条数限制在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"
}
]
}
}
4.7 图文消息-点击跳转到图文消息页面
{
"touser":"OPENID",
"msgtype":"mpnews",
"mpnews":
{
"media_id":"MEDIA_ID"
}
}
4.8 卡券
{
"touser":"OPENID",
"msgtype":"wxcard",
"wxcard":{
"card_id":"123dsdajkasd231jhksad"
},
}
4.9 小程序卡片(要求小程序与公众号已关联)
{
"touser":"OPENID",
"msgtype":"miniprogrampage",
"miniprogrampage":
{
"title":"title",
"appid":"appid",
"pagepath":"pagepath",
"thumb_media_id":"thumb_media_id"
}
}
注意:如果需要以某个客服帐号来发消息(在微信6.0.2及以上版本中显示自定义头像),则需在JSON数据包的后半部分加入customservice参数
五、客服输入状态
开发者可通过调用“客服输入状态”接口,返回客服当前输入状态给用户(即在对话框显示“对方正在输入……”)
地址为:
post-https://api.weixin.qq.com/cgi-bin/message/custom/typing?access_token=ACCESS_TOKEN
限制:
- 如果不满足发送客服消息的触发条件,则无法下发输入状态。
- 下发输入状态,需要客服之前30秒内跟用户有过消息交互。
- 在输入状态中(持续15s),不可重复下发输入态。
- 在输入状态中,如果向用户下发消息,会同时取消输入状态。