客服账号管理 | 微信开放文档

当用户和公众号产生特定动作的交互时（具体动作列表请见下方说明），微信将会把消息数据推送给开发者，开发者可以在一段时间内（目前为48小时，2023年6月12日后启用新规则，查看公告）调用客服接口，通过POST一个JSON数据包来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能，方便开发者为用户提供更加优质的服务。

目前允许的动作列表如下（公众平台会根据运营情况更新该列表，不同动作触发后，允许的客服接口

用户发送信息
点击自定义菜单（仅有点击推事件、扫码推事件、扫码推事件且弹出“消息接收中”提示框这3种菜单类型是会触发客服接口的）
关注公众号
扫描二维码

2023年6月之后各场景的客服消息下发规则：

场景	下发额度	额度有效期
用户发送消息	5条	48小时
点击自定义菜单	3条	1分钟
关注公众号	3条	1分钟
扫描二维码	3条	1分钟

特别说明：在用户点击菜单消息时，触发的是点击菜单事件，对应场景2点击自定义菜单的消息规则，不会产生用户发送消息场景的客服消息下发额度。

为了帮助公众号使用不同的客服身份服务不同的用户群体，客服接口进行了升级，开发者可以管理客服账号，并设置客服账号的头像和昵称。该能力针对所有拥有客服接口权限的公众号开放。

另外，请开发者注意，本接口中所有使用到media_id的地方，现在都可以使用素材管理中的永久素材media_id了。

# 客服账号管理

开发者在根据开发文档的要求完成开发后，使用6.0.2版及以上版本的微信用户在与公众号进行客服沟通，公众号使用不同的客服账号进行回复后，用户可以看到对应的客服头像和昵称。

请注意，必须先在公众平台官网为公众号设置微信号后才能使用该能力。

# 添加客服账号

开发者可以通过本接口为公众号添加客服账号，每个公众号最多添加100个客服账号。该接口调用请求如下：

http请求方式: POST https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN

POST数据示例如下：

{
     "kf_account" : "test1@test",
     "nickname" : "客服1",
     "password" : "pswmd5"
}

返回说明（正确时的JSON返回结果）：

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

错误时微信会返回错误码等信息，请根据错误码查询错误信息

# 修改客服账号

开发者可以通过本接口为公众号修改客服账号。该接口调用请求如下：

http请求方式: POST https://api.weixin.qq.com/customservice/kfaccount/update?access_token=ACCESS_TOKEN

POST数据示例如下：

{
     "kf_account" : "test1@test",
     "nickname" : "客服1",
     "password" : "pswmd5"
}

返回说明（正确时的JSON返回结果）：

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

错误时微信会返回错误码等信息，请根据错误码查询错误信息

# 删除客服账号

开发者可以通过该接口为公众号删除客服账号。该接口调用请求如下：

http请求方式: POST https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN

POST数据示例如下：

{
     "kf_account" : "test1@test"
}

返回说明（正确时的JSON返回结果）：

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

错误时微信会返回错误码等信息，请根据错误码查询错误信息

# 设置客服账号的头像

开发者可调用本接口来上传图片作为客服人员的头像，头像图片文件必须是jpg格式，推荐使用640*640大小的图片以达到最佳效果。该接口调用请求如下：

http请求方式: POST / FORM https://api.weixin.qq.com/customservice/kfaccount/uploadheadimg?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT 调用示例：使用curl命令，用FORM表单方式上传一个多媒体文件，curl命令的具体用法请自行了解

返回说明（正确时的JSON返回结果）：

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

错误时微信会返回错误码等信息，请根据错误码查询错误信息

# 获取所有客服账号

开发者通过本接口，获取公众号中所设置的客服基本信息，包括客服工号、客服昵称、客服登录账号。

http请求方式: GET https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN

返回说明（正确时的JSON返回结果）：

{
    "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"
        }
    ]
}

错误时微信会返回错误码等信息，请根据错误码查询错误信息

# 接口的统一参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
kf_account	是	完整客服账号，格式为：账号前缀@公众号微信号
kf_nick	是	客服昵称
kf_id	是	客服工号
nickname	是	客服昵称，最长6个汉字或12个英文字符
password	否	客服账号登录密码，格式为密码明文的32位加密MD5值。该密码仅用于在公众平台官网的多客服功能中使用，若不使用多客服功能，则不必设置密码
media	是	该参数仅在设置客服头像时出现，是form-data中媒体文件标识，有filename、filelength、content-type等信息

# 客服接口-发消息

接口调用请求说明

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"
    }
}

发送文本消息时，支持插入跳小程序的文字链

文本内容<a href="http://www.qq.com" data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>

说明： 1.data-miniprogram-appid 项，填写小程序appid，则表示该链接跳小程序； 2.data-miniprogram-path项，填写小程序路径，路径与app.json中保持一致，可带参数； 3.对于不支持data-miniprogram-appid 项的客户端版本，如果有herf项，则仍然保持跳href中的网页链接； 4.data-miniprogram-appid对应的小程序必须与公众号有绑定关系。

发送图片消息

{
    "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" 
    }
}

发送图文消息（点击跳转到外链）图文消息条数限制在1条以内，注意，如果图文数超过1，则将会返回错误码45008。

{
    "touser":"OPENID",
    "msgtype":"news",
    "news":{
        "articles": [
         {
             "title":"Happy Day",
             "description":"Is Really A Happy Day",
             "url":"URL",
             "picurl":"PIC_URL"
         }
         ]
    }
}

发送图文消息（点击跳转到图文消息页面）图文消息条数限制在1条以内，注意，如果图文数超过1，则将会返回错误码45008。

{
    "touser":"OPENID",
    "msgtype":"mpnews",
    "mpnews":
    {
         "media_id":"MEDIA_ID"
    }
}

发送图文消息（点击跳转到图文消息页面）使用通过 “发布” 系列接口得到的 article_id

注意: 草稿接口灰度完成后，将不再支持此前客服接口中带 media_id 的 mpnews 类型的图文消息

{
    "touser":"OPENID",
    "msgtype":"mpnewsarticle",
    "mpnewsarticle": {
         "article_id":"ARTICLE_ID"
    }
}

发送菜单消息

{
  "touser": "OPENID",
  "msgtype": "msgmenu",
  "msgmenu": {
    "head_content": "您对本次服务是否满意呢? ",
    "list": [
      {
        "id": "101",
        "content": "满意"
      },
      {
        "id": "102",
        "content": "不满意"
      }
    ],
    "tail_content": "欢迎再次光临"
  }
}

按照上述例子，用户会看到这样的菜单消息：

“您对本次服务是否满意呢？

满意

不满意”

其中，“满意”和“不满意”是可点击的，当用户点击后，微信会发送一条XML消息到开发者服务器，格式如下：

<xml>
<ToUserName><![CDATA[ToUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>1500000000</CreateTime>
<MsgType><![CDATA[text]]></MsgType>
<Content><![CDATA[满意]]></Content>
<MsgId>1234567890123456</MsgId>
<bizmsgmenuid>101</bizmsgmenuid>
</xml>

XML参数说明：

参数	说明
ToUserName	开发者账号
FromUserName	接收方账号（OpenID）
CreateTime	消息创建时间戳
MsgType	Text
Content	点击的菜单名
MsgId	消息ID
bizmsgmenuid	点击的菜单ID

收到XML推送之后，开发者可以根据提取出来的bizmsgmenuid和Content识别出微信用户点击的是哪个菜单。该消息仅支持已认证服务号使用，其余账号类型不允许使用。

特别说明：用户点击菜单消息后，触发的事件为点击菜单事件，对应点击自定义菜单的规则，不会产生用户上行消息的客服消息下发额度。

发送卡券

{
  "touser":"OPENID", 
  "msgtype":"wxcard",
  "wxcard":
  {              
   "card_id":"123dsdajkasd231jhksad"        
   }
}

特别注意客服消息接口投放卡券仅支持非自定义Code码和导入code模式的卡券的卡券，详情请见：创建卡券。

发送小程序卡片（要求小程序与公众号已关联）

客户端效果如下图：

接口调用示例：

{
    "touser":"OPENID",
    "msgtype":"miniprogrampage",
    "miniprogrampage":
    {
        "title":"title",
        "appid":"appid",
        "pagepath":"pagepath",
        "thumb_media_id":"thumb_media_id"
    }
}

请注意，如果需要以某个客服账号来发消息（在微信6.0.2及以上版本中显示自定义头像），则需在JSON数据包的后半部分加入customservice参数，例如发送文本消息则改为：

{
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":"Hello World"
    },
    "customservice":
    {
         "kf_account": "test1@kftest"
    }
}

参数	是否必须	说明
access_token	是	调用接口凭证
touser	是	普通用户openid
msgtype	是	消息类型，文本为text，图片为image，语音为voice，视频消息为video，音乐消息为music，图文消息（点击跳转到外链）为news，图文消息（点击跳转到图文消息页面）为mpnews，卡券为wxcard，小程序为miniprogrampage
content	是	文本消息内容
media_id	是	发送的图片/语音/视频/图文消息（点击跳转到图文消息页）的媒体ID
thumb_media_id	是	缩略图/小程序卡片图片的媒体ID，小程序卡片图片建议大小为520*416
title	否	图文消息/视频消息/音乐消息/小程序卡片的标题
description	否	图文消息/视频消息/音乐消息的描述
musicurl	是	音乐链接
hqmusicurl	是	高品质音乐链接，wifi环境优先使用该链接播放音乐
url	否	图文消息被点击后跳转的链接
picurl	否	图文消息的图片链接，支持JPG、PNG格式，较好的效果为大图640320，小图8080
appid	是	小程序的appid，要求小程序的appid需要与公众号有关联关系
pagepath	是	小程序的页面路径，跟app.json对齐，支持参数，比如pages/index/index?foo=bar

# 客服输入状态

开发者可通过调用“客服输入状态”接口，返回客服当前输入状态给用户。

微信客户端效果图如下：

此接口需要客服消息接口权限。

如果不满足发送客服消息的触发条件，则无法下发输入状态。
下发输入状态，需要客服之前30秒内跟用户有过消息交互。
在输入状态中（持续15s），不可重复下发输入态。
在输入状态中，如果向用户下发消息，会同时取消输入状态。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/custom/typing?access_token=ACCESS_TOKEN

JSON数据包如下：

 { "touser":"OPENID", "command":"Typing"}

预期返回：

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

参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
touser	是	普通用户（openid）
command	是	"Typing"：对用户下发“正在输入"状态 "CancelTyping"：取消对用户的”正在输入"状态

返回码说明

参数	说明
45072	command字段取值不对
45080	下发输入状态，需要之前30秒内跟用户有过消息交互
45081	已经在输入状态，不可重复下发
40200	账号非小程序或已认证的服务号