分配客服会话
最后更新：2023/11/30
概述
从微信用户发起咨询到会话结束，该次会话可能会经过以下几个状态流转。**企业或第三方可使用API获取和变更会话状态，以实现对会话的分配管理。**变更会话状态时，只能从当前状态，变更成另一些特定的状态，具体如下：
| ID | 状态 | 说明 |
|---|---|---|
| 0 | 未处理 | 新会话接入（客户发消息咨询）。可选择：1.直接用API自动回复消息。2.放进待接入池等待接待人员接待。3.指定接待人员（接待人员须处于“正在接待”中，下同）进行接待 |
| 1 | 由智能助手接待 | 可使用API回复消息。可选择转入待接入池或者指定接待人员处理。 |
| 2 | 待接入池排队中 | 在待接入池中排队等待接待人员接入。可选择转为指定人员接待 |
| 3 | 由人工接待 | 人工接待中。可选择转接给其他接待人员处理或者结束会话。 |
| 4 | 已结束/未开始 | 会话已经结束或未开始（客户进入会话，还没上行消息）。不允许通过API变更会话状态，客户发消息咨询后会话状态变为“未处理”。接待人员通过客户端在已结束会话中成功发送消息后，会话状态变为“由人工接待”，此时会产生会话状态变更回调事件（4-重新接入已结束/已转接会话）。 |
**注：**一个微信用户向一个客服账号发起咨询后，在48h内，或主动结束会话前（包括接待人员手动结束，或企业通过API结束会话），都算是一次会话。
获取会话状态
请求方式: POST(HTTPS)
请求地址: https://qyapi.weixin.qq.com/cgi-bin/kf/service_state/get?access_token=ACCESS_TOKEN
请求实例:
{ "open_kfid": "wkxxxxxxxxxxxxxxxxxx", "external_userid": "wmxxxxxxxxxxxxxxxxxx"}
参数说明：
| 参数 | 是否必须 | 说明 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| open_kfid | 是 | 客服账号ID |
| external_userid | 是 | 微信客户的external_userid |
权限说明:
调用的应用需要满足如下的权限
| 应用类型 | 权限要求 |
|---|---|
| 自建应用 | 配置到「 微信客服- 可调用接口的应用」中 |
| 第三方应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
| 代开发自建应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
注： 从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响 查看详情
- 只能通过API管理企业指定的客服账号。企业可在管理后台“微信客服-通过API管理微信客服账号”处设置对应的客服账号通过API来管理。
- 操作的客服账号对应的接待人员应在应用的可见范围内
返回结果:
{ "errcode": 0, "errmsg": "ok", "service_state": 3, "servicer_userid": "zhangsan"}
参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | int | 返回码 |
| errmsg | string | 错误码描述 |
| service_state | int | 当前的会话状态，状态定义参考概述中的表格 |
| servicer_userid | string | 接待人员的userid。第三方应用为密文userid，即open_userid。仅当state=3时有效 |
变更会话状态
请求方式: POST(HTTPS)
请求地址: https://qyapi.weixin.qq.com/cgi-bin/kf/service_state/trans?access_token=ACCESS_TOKEN
请求实例:
{ "open_kfid": "wkxxxxxxxxxxxxxxxxxx", "external_userid": "wmxxxxxxxxxxxxxxxxxx", "service_state": 3, "servicer_userid": "zhangsan"}
参数说明：
| 参数 | 是否必须 | 说明 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| open_kfid | 是 | 客服账号ID |
| external_userid | 是 | 微信客户的external_userid |
| service_state | 是 | 变更的目标状态，状态定义和所允许的变更可参考概述中的流程图和表格 |
| servicer_userid | 否 | 接待人员的userid。第三方应用填密文userid，即open_userid。当state=3时要求必填，接待人员须处于“正在接待”中。注意：要求接待人员必须在企业微信激活使用，否则会返回95014错误。 |
权限说明:
调用的应用需要满足如下的权限
| 应用类型 | 权限要求 |
|---|---|
| 自建应用 | 配置到「 微信客服- 可调用接口的应用」中 |
| 第三方应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
| 代开发自建应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
注： 从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响 查看详情
- 只能通过API管理企业指定的客服账号。企业可在管理后台“微信客服-通过API管理微信客服账号”处设置对应的客服账号通过API来管理。
- 操作的客服账号对应的接待人员应在应用的可见范围内
返回结果:
{ "errcode": 0, "errmsg": "ok", "msg_code": "MSG_CODE"}
参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | int | 返回码 |
| errmsg | string | 错误码描述 |
| msg_code | string | 用于发送响应事件消息的code，将会话初次变更为service_state为2和3时，返回回复语code，service_state为4时，返回结束语code。可用该code调用发送事件响应消息接口给客户发送事件响应消息 |
接收消息和事件
最后更新：2024/12/23
概述
当微信客户、接待人员发消息或有行为动作时，企业微信后台会将事件的回调数据包发送到企业指定URL；企业收到请求后，再通过读取消息接口主动读取具体的消息内容。
回调事件
接收并解析事件的方法见：接收事件。
示例
<xml> <ToUserName><![CDATA[ww12345678910]]></ToUserName> <CreateTime>1348831860</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[kf_msg_or_event]]></Event> <Token><![CDATA[ENCApHxnGDNAVNY4AaSJKj4Tb5mwsEMzxhFmHVGcra996NR]]></Token> <OpenKfId><![CDATA[wkxxxxxxx]]></OpenKfId></xml>
说明
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| CreateTime | 消息创建时间，unix时间戳 |
| MsgType | 消息的类型，此时固定为：event |
| Event | 事件的类型，此时固定为：kf_msg_or_event |
| Token | 调用拉取消息接口时，需要传此token，用于校验请求的合法性 |
| OpenKfId | 有新消息的客服账号。可通过sync_msg接口指定open_kfid获取此客服账号的消息 |
读取消息
微信客户发送的消息、接待人员在企业微信回复的消息、发送消息接口发送失败事件（如被用户拒收）、客户点击菜单消息的回复消息，可以通过该接口获取最近3天内具体的消息内容和事件。不支持读取通过发送消息接口发送的消息。
支持的消息类型：文本、图片、语音、视频、文件、位置、链接、名片、小程序、菜单、事件。
图片、语音、视频、文件消息的媒体文件有如下大小限制，超出会获取到文本提示消息：
- 图片：2MB
- 语音：2MB
- 视频：10MB
- 文件：20MB
接口定义
请求方式: POST(HTTPS)
请求地址: https://qyapi.weixin.qq.com/cgi-bin/kf/sync_msg?access_token=ACCESS_TOKEN
请求示例
{ "cursor": "4gw7MepFLfgF2VC5npN", "token": "ENCApHxnGDNAVNY4AaSJKj4Tb5mwsEMzxhFmHVGcra996NR", "limit": 1000, "voice_format": 0, "open_kfid": "wkxxxxxx"}
参数说明:
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| cursor | 否 | string | 上一次调用时返回的next_cursor，第一次拉取可以不填。若不填，从3天内最早的消息开始返回。不多于64字节 |
| token | 否 | string | 回调事件返回的token字段，10分钟内有效；可不填，如果不填接口有严格的频率限制。不多于128字节 |
| limit | 否 | uint32 | 期望请求的数据量，默认值和最大值都为1000。注意：可能会出现返回条数少于limit的情况，需结合返回的has_more字段判断是否继续请求。 |
| voice_format | 否 | uint32 | 语音消息类型，0-Amr 1-Silk，默认0。可通过该参数控制返回的语音格式，开发者可按需选择自己程序支持的一种格式 |
| open_kfid | 是 | string | 指定拉取某个客服账号的消息 |
权限说明:
调用的应用需要满足如下的权限
| 应用类型 | 权限要求 |
|---|---|
| 自建应用 | 配置到「 微信客服- 可调用接口的应用」中 |
| 第三方应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
| 代开发自建应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
注： 从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响 查看详情
- 只能通过API管理企业指定的客服账号。企业可在管理后台“微信客服-通过API管理微信客服账号”处设置对应的客服账号通过API来管理。
- 操作的客服账号对应的接待人员应在应用的可见范围内
返回结果:
{ "errcode": 0, "errmsg": "ok", "next_cursor": "4gw7MepFLfgF2VC5npN", "has_more": 1, "msg_list": [ { "msgid": "from_msgid_4622416642169452483", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "send_time": 1615478585, "origin": 3, "servicer_userid": "Zhangsan", "msgtype": "MSG_TYPE" } ]}
参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | int32 | 返回码 |
| errmsg | string | 错误码描述 |
| next_cursor | string | 下次调用带上该值，则从当前的位置继续往后拉，以实现增量拉取。强烈建议对该字段入库保存，每次请求读取带上，请求结束后更新。避免因意外丢，导致必须从头开始拉取，引起消息延迟。 |
| has_more | uint32 | 是否还有更多数据。0-否；1-是。不能通过判断msg_list是否空来停止拉取，可能会出现has_more为1，而msg_list为空的情况 |
| msg_list | obj[] | 消息列表 |
| msg_list.msgid | string | 消息ID |
| msg_list.open_kfid | string | 客服账号ID（msgtype为event，该字段不返回） |
| msg_list.external_userid | string | 客户UserID（msgtype为event，该字段不返回） |
| msg_list.send_time | uint64 | 消息发送时间 |
| msg_list.origin | uint32 | 消息来源。3-微信客户发送的消息 4-系统推送的事件消息 5-接待人员在企业微信客户端发送的消息 |
| msg_list.servicer_userid | string | 从企业微信给客户发消息的接待人员userid（即仅origin为5才返回；msgtype为event，该字段不返回） |
| msg_list.msgtype | string | 对不同的msgtype，有相应的结构描述，下面进一步说明 |
消息类型
文本消息
返回示例：
{ "msgtype" : "text", "text" : { "content" : "hello world", "menu_id" : "101" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：text |
| text | obj | 文本消息 |
| text.content | string | 文本内容 |
| text.menu_id | string | 客户点击菜单消息，触发的回复消息中附带的菜单ID |
图片消息
返回示例：
{ "msgtype" : "image", "image" : { "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：image |
| image | obj | 图片消息 |
| image.media_id | string | 图片文件id |
语音消息
返回示例：
{ "msgtype" : "voice", "voice" : { "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：voice |
| voice | obj | 语音消息 |
| voice.media_id | string | 语音文件ID |
视频消息
返回示例：
{ "msgtype" : "video", "video" : { "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：video |
| video | obj | 视频消息 |
| video.media_id | string | 文件id |
文件消息
返回示例：
{ "msgtype" : "file", "file" : { "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：file |
| file | obj | 文件消息 |
| file.media_id | string | 文件id |
位置消息
返回示例：
{ "msgtype" : "location", "location" : { "latitude": 23.106021881103501, "longitude": 113.320503234863, "name": "广州国际媒体港(广州市海珠区)", "address": "广东省广州市海珠区滨江东路" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：location |
| location | obj | 地理位置消息 |
| location.latitude | float | 纬度 |
| location.longitude | float | 经度 |
| location.name | string | 位置名 |
| location.address | string | 地址详情说明 |
链接消息
返回示例：
{ "msgtype" : "link", "link" : { "title": "TITLE", "desc": "DESC", "url": "URL", "pic_url": "PIC_URL" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：link |
| link | obj | 链接消息 |
| link.title | string | 标题 |
| link.desc | string | 描述 |
| link.url | string | 点击后跳转的链接 |
| link.pic_url | string | 缩略图链接 |
名片消息
返回示例：
{ "msgtype" : "business_card", "business_card" : { "userid": "USERID" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：business_card |
| business_card | obj | 名片消息 |
| business_card.userid | string | 名片userid |
小程序消息
返回示例：
{ "msgtype" : "miniprogram", "miniprogram" : { "title": "TITLE", "appid": "APPID", "pagepath": "PAGE_PATH", "thumb_media_id": "THUMB_MEDIA_ID" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：miniprogram |
| miniprogram | obj | 小程序消息 |
| miniprogram.title | string | 标题 |
| miniprogram.appid | string | 小程序appid |
| miniprogram.pagepath | string | 点击消息卡片后进入的小程序页面路径 |
| miniprogram.thumb_media_id | string | 小程序消息封面的mediaid |
菜单消息
返回示例：
{ "msgtype" : "msgmenu", "msgmenu": { "head_content": "您对本次服务是否满意呢? ", "list": [ { "type": "click", "click": { "id": "101", "content": "满意" } }, { "type": "click", "click": { "id": "102", "content": "不满意" } }, { "type": "view", "view": { "url": "https://work.weixin.qq.com", "content": "点击跳转到自助查询页面" } }, { "type": "miniprogram", "miniprogram": { "appid": "wx123123123123123", "pagepath": "pages/index?userid=zhangsan&orderid=123123123", "content": "点击打开小程序查询更多" } } ], "tail_content": "欢迎再次光临" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：msgmenu |
| msgmenu | obj | 菜单消息 |
| msgmenu.head_content | string | 起始文本 |
| msgmenu.list | obj[] | 菜单项配置 |
| msgmenu.list.type | string | 菜单类型。click-回复菜单 view-超链接菜单 miniprogram-小程序菜单 |
| msgmenu.list.click | obj | type为click的菜单项 |
| msgmenu.list.click.id | string | 菜单ID |
| msgmenu.list.click.content | string | 菜单显示内容 |
| msgmenu.list.view | obj | type为view的菜单项 |
| msgmenu.list.view.url | string | 点击后跳转的链接 |
| msgmenu.list.view.content | string | 菜单显示内容 |
| msgmenu.list.miniprogram | obj | type为miniprogram的菜单项 |
| msgmenu.list.miniprogram.appid | string | 小程序appid |
| msgmenu.list.miniprogram.pagepath | string | 点击后进入的小程序页面 |
| msgmenu.list.miniprogram.content | string | 菜单显示内容 |
| msgmenu.tail_content | string | 结束文本 |
视频号商品消息
返回示例：
{ "msgtype" : "channels_shop_product", "channels_shop_product" : { "product_id": "PRODUCT_ID", "head_image": "PRODUCT_IMAGE_URL", "title": "TITLE", "sales_price": "SALES_PRICE", "shop_nickname": "SHOP_NICKNAME", "shop_head_image": "SHOP_HEAD_IMAGE" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：channels_shop_product |
| channels_shop_product | obj | 视频号商品消息 |
| channels_shop_product.product_id | string | 商品ID |
| channels_shop_product.head_image | string | 商品图片 |
| channels_shop_product.title | string | 商品标题 |
| channels_shop_product.sales_price | string | 商品价格，以分为单位 |
| channels_shop_product.shop_nickname | string | 店铺名称 |
| channels_shop_product.shop_head_image | string | 店铺头像 |
视频号订单消息
返回示例：
{ "msgtype" : "channels_shop_order", "channels_shop_order" : { "order_id": "ORDER_ID", "product_titles":"PRODUCT_TITLES", "price_wording":"PRICE_WORDING", "state":"STATE", "image_url":"IMAGE_URL", "shop_nickname":"SHOP_NICKNAME" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：channels_shop_order |
| channels_shop_order | obj | 视频号订单消息 |
| channels_shop_order.order_id | string | 订单号 |
| channels_shop_order.product_titles | string | 商品标题 |
| channels_shop_order.price_wording | string | 订单价格描述 |
| channels_shop_order.state | string | 订单状态 |
| channels_shop_order.image_url | string | 订单缩略图 |
| channels_shop_order.shop_nickname | string | 店铺名称 |
聊天记录消息
返回示例：
{ "msgtype" : "merged_msg", "merged_msg": { "title": "群聊的聊天记录", "item": [ { "send_time": 1665649618, "msgtype": "text", "sender_name": "发送者", "msg_content": "{\"msgtype\":\"text\",\"text\":{\"content\":\"消息内容\"}}" } ] }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：merged_msg |
| merged_msg | obj | 聊天记录消息 |
| merged_msg.title | string | 聊天记录标题 |
| merged_msg.item | obj[] | 消息记录内的消息内容 |
| merged_msg.item.send_time | uint32 | 发送时间 |
| merged_msg.item.msgtype | uint32 | 消息类型 |
| merged_msg.item.sender_name | uint32 | 发送者名称 |
| merged_msg.item.msg_content | string | 消息内容，Json字符串，结构可参考本文档消息类型说明 |
视频号消息
返回示例：
{ "msgtype" : "channels", "channels" : { "sub_type": 1, "nickname": "视频号名称", "title": "动态标题" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：channels目前仅部分返回详细消息内容。 |
| channels | obj | 视频号消息 |
| channels. sub_type | uint32 | 视频号消息类型，1视频号动态、2视频号直播、3视频号名片 |
| channels. nickname | string | 视频号名称 |
| channels. title | string | 视频号动态标题，视频号消息类型为“1视频号动态”时，返回动态标题 |
会议消息
返回示例：
{ "msgtype" : "meeting"}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：meeting目前暂不返回详细消息内容。 |
日程消息
返回示例：
{ "msgtype" : "calendar"}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：calendar目前暂不返回详细消息内容。 |
笔记消息
返回示例：
{ "msgtype" : "note"}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：note目前暂不返回详细消息内容。 |
事件消息
用户进入会话事件
通过客服链接进入会话，才会触发该事件。需要注意的是，从客服会话列表的已有会话点击进入，不会触发。
返回示例：
{ "msgtype" : "event", "event" : { "event_type": "enter_session", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "scene": "123", "scene_param": "abc", "welcome_code": "aaaaaa", "wechat_channels": { "nickname": "进入会话的视频号名称", "scene":1 } }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：enter_session |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.scene | string | 进入会话的场景值，获取客服账号链接开发者自定义的场景值 |
| event.scene_param | string | 进入会话的自定义参数，获取客服账号链接返回的url，开发者按规范拼接的scene_param参数 |
| event.welcome_code | string | 如果满足发送欢迎语条件（条件为：用户在过去48小时里未收过欢迎语，且未向客服发过消息），会返回该字段。可用该welcome_code调用发送事件响应消息接口给客户发送欢迎语。 |
| event.wechat_channels | obj | 进入会话的视频号信息，从视频号进入会话才有值 |
| event.wechat_channels.nickname | string | 视频号名称，视频号场景值为1、2、3时返回此项 |
| event.wechat_channels.shop_nickname | string | 视频号小店名称，视频号场景值为4、5时返回此项 |
| event.wechat_channels.scene | uint32 | 视频号场景值。1：视频号主页，2：视频号直播间商品列表页，3：视频号商品橱窗页，4：视频号小店商品详情页，5：视频号小店订单页 |
消息发送失败事件
返回示例：
{ "msgtype": "event", "event": { "event_type": "msg_send_fail", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "fail_msgid": "FAIL_MSGID", "fail_type": 4 }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：msg_send_fail |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.fail_msgid | string | 发送失败的消息msgid |
| event.fail_type | uint32 | 失败类型。0-未知原因 1-客服账号已删除 2-应用已关闭 4-会话已过期，超过48小时 5-会话已关闭 6-超过5条限制 8-主体未验证 10-用户拒收 11-企业未有成员登录企业微信App（排查方法：企业至少一个成员通过手机号验证/微信授权登录企业微信App即可）12-发送的消息为客服组件禁发的消息类型 13-安全限制 |
接待人员接待状态变更事件
返回示例：
{ "msgtype": "event", "event": { "event_type": "servicer_status_change", "servicer_userid": "SERVICER_USERID", "status": 2, "stop_type": 0, "open_kfid": "OPEN_KFID" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：servicer_status_change |
| event.servicer_userid | string | 接待人员userid |
| event.status | uint32 | 状态类型。1-接待中 2-停止接待 |
| event.stop_type | uint32 | 接待人员的状态为「停止接待」的子类型。0:停止接待,1:暂时挂起 |
| event.open_kfid | string | 客服账号ID |
会话状态变更事件
返回示例：
{ "msgtype" : "event", "event" : { "event_type": "session_status_change", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "change_type": 1, "old_servicer_userid": "OLD_SERVICER_USERID", "new_servicer_userid": "NEW_SERVICER_USERID", "msg_code": "MSG_CODE" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：session_status_change |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.change_type | uint32 | 变更类型，均为接待人员在企业微信客户端操作触发。1-从接待池接入会话 2-转接会话 3-结束会话 4-重新接入已结束/已转接会话 |
| event.old_servicer_userid | string | 老的接待人员userid。仅change_type为2、3和4有值 |
| event.new_servicer_userid | string | 新的接待人员userid。仅change_type为1、2和4有值 |
| event.msg_code | string | 用于发送事件响应消息的code，仅change_type为1和3时，会返回该字段。可用该msg_code调用发送事件响应消息接口给客户发送回复语或结束语。 |
用户撤回消息事件
返回示例：
{ "msgtype" : "event", "event" : { "event_type": "user_recall_msg", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "recall_msgid": "RECALL_MSGID" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：user_recall_msg |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.recall_msgid | string | 撤回的消息msgid |
接待人员撤回消息事件
返回示例：
{ "msgtype" : "event", "event" : { "event_type": "servicer_recall_msg", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "recall_msgid": "RECALL_MSGID", "servicer_userid": "SERVICER_USERID" }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：servicer_recall_msg |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.recall_msgid | string | 撤回的消息msgid |
| event.servicer_userid | string | 接待人员userid |
拒收客户消息变更事件
返回示例：
{ "msgtype" : "event", "event" : { "event_type": "reject_customer_msg_switch_change", "servicer_userid": "Zhangsan", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "reject_switch": 1 }}
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：reject_customer_msg_switch_change |
| event.servicer_userid | string | 操作的接待人员userid |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.reject_switch | uint32 | 拒收客户消息，1表示接待人员拒收了客户消息，0表示接待人员取消拒收客户消息 |
发送消息
最后更新：2023/12/19
概述
当微信客户处于“新接入待处理”或“由智能助手接待”状态下，可调用该接口给用户发送消息。
注意仅当微信客户在主动发送消息给客服后的48小时内，企业可发送消息给客户，最多可发送5条消息；若用户继续发送消息，企业可再次下发消息。
支持发送消息类型：文本、图片、语音、视频、文件、图文、小程序、菜单消息、地理位置、获客链接。
目前该接口允许下发消息条数和下发时限如下：
| 用户动作 | 允许下发条数限制 | 下发时限 |
|---|---|---|
| 用户发送消息 | 5条 | 48 小时 |
接口定义
请求方式: POST(HTTPS)
请求地址: https://qyapi.weixin.qq.com/cgi-bin/kf/send_msg?access_token=ACCESS_TOKEN
参数说明：
| 参数 | 是否必须 | 说明 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
权限说明:
调用的应用需要满足如下的权限
| 应用类型 | 权限要求 |
|---|---|
| 自建应用 | 配置到「 微信客服- 可调用接口的应用」中 |
| 第三方应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
| 代开发自建应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
注： 从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响 查看详情
- 只能通过API管理企业指定的客服账号。企业可在管理后台“微信客服-通过API管理微信客服账号”处设置对应的客服账号通过API来管理。
- 操作的客服账号对应的接待人员应在应用的可见范围内
返回结果:
{ "errcode": 0, "errmsg": "ok", "msgid": "MSG_ID"}
注意：接口返回成功，不代表消息最终发送成功，还需要关注
参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | int32 | 返回码 |
| errmsg | string | 错误码描述 |
| msgid | string | 消息ID。如果请求参数指定了msgid，则原样返回，否则系统自动生成并返回。若指定msgid，开发者需确保客服账号内唯一，否则接口返回错误。不多于32字节字符串取值范围(正则表达式)：[0-9a-zA-Z_-]* |
消息类型
文本消息
请求示例：
{ "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "text", "text" : { "content" : "你购买的物品已发货，可点击链接查看物流状态http://work.weixin.qq.com/xxxxxx" }}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：text |
| text | 是 | obj | 文本消息 |
| text.content | 是 | string | 消息内容，最长不超过2048个字节 |
图片消息
请求示例：
{ "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "image", "image" : { "media_id" : "MEDIA_ID" }}
请求参数：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：image |
| image | 是 | obj | 图片消息 |
| image.media_id | 是 | string | 图片文件id，可以调用上传临时素材接口获取 |
语音消息
请求示例：
{ "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgtype" : "voice", "voice" : { "media_id" : "MEDIA_ID" }}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：voice |
| voice | 是 | obj | 语音消息 |
| voice.media_id | 是 | string | 语音文件id，可以调用上传临时素材接口获取 |
视频消息
请求示例：
{ "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "video", "video" : { "media_id" : "MEDIA_ID" }}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：video |
| video | 是 | obj | 视频消息 |
| video.media_id | 是 | string | 视频媒体文件id，可以调用上传临时素材接口获取 |
视频消息展现：
文件消息
请求示例：
{ "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "file", "file" : { "media_id" : "1Yv-zXfHjSjU-7LH-GwtYqDGS-zz6w22KmWAT5COgP7o" }}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：file |
| file | 是 | obj | 文件消息 |
| file.media_id | 是 | string | 文件id，可以调用上传临时素材接口获取 |
文件消息展现：
图文链接消息
请求示例：
{ "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "link", "link" : { "title" : "企业如何增长？企业微信给出3个答案", "desc" : "今年中秋节公司有豪礼相送", "url" : "URL", "thumb_media_id": "MEDIA_ID" }}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：link |
| link | 是 | obj | 链接消息 |
| link.title | 是 | string | 标题，不超过128个字节，超过会自动截断 |
| link.desc | 否 | string | 描述，不超过512个字节，超过会自动截断 |
| link.url | 是 | string | 点击后跳转的链接。 最长2048字节，请确保包含了协议头(http/https) |
| link.thumb_media_id | 是 | string | 缩略图的media_id, 可以通过素材管理接口获得。此处thumb_media_id即上传接口返回的media_id |
图文链接消息展现：
小程序消息
请求示例：
{ "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "miniprogram" "miniprogram" : { "appid": "APPID", "title": "欢迎报名夏令营", "thumb_media_id": "MEDIA_ID", "pagepath": "PAGE_PATH" }}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：miniprogram |
| miniprogram | 是 | obj | 小程序消息 |
| miniprogram.appid | 是 | string | 小程序appid |
| miniprogram.title | 否 | string | 小程序消息标题，最多64个字节，超过会自动截断 |
| miniprogram.thumb_media_id | 是 | string | 小程序消息封面的mediaid，封面图建议尺寸为520*416 |
| miniprogram.pagepath | 是 | string | 点击消息卡片后进入的小程序页面路径。注意路径要以.html为后缀，否则在微信中打开会提示找不到页面 |
菜单消息
请求示例：
{ "touser": "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype": "msgmenu", "msgmenu": { "head_content": "您对本次服务是否满意呢? ", "list": [ { "type": "click", "click": { "id": "101", "content": "满意" } }, { "type": "click", "click": { "id": "102", "content": "不满意" } }, { "type": "view", "view": { "url": "https://work.weixin.qq.com", "content": "点击跳转到自助查询页面" } }, { "type": "miniprogram", "miniprogram": { "appid": "wx123123123123123", "pagepath": "pages/index.html?userid=zhangsan&orderid=123123123", "content": "点击打开小程序查询更多" } }, { "type": "text", "text": { "content": "纯文本，支持\n换行", "no_newline": 0 } } ], "tail_content": "欢迎再次光临" }}
参数说明：
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：msgmenu |
| msgmenu | 是 | obj | 菜单消息 |
| msgmenu.head_content | 否 | string | 起始文本不多于1024字节 |
| msgmenu.list | 否 | obj[] | 菜单项配置，不超过50个，其中click/view/miniprogram的菜单类型加起来不超过10个 |
| msgmenu.list.type | 是 | string | 菜单类型。click-回复菜单 view-超链接菜单 miniprogram-小程序菜单 text-文本 |
| msgmenu.list.click | 否 | obj | type为click的菜单项 |
| msgmenu.list.click.id | 否 | string | 菜单ID。建议只使用以下字符集a-z、A-Z、0-9、_，不建议用#，否则可能会出现截断。不少于1字节不多于128字节 |
| msgmenu.list.click.content | 是 | string | 菜单显示内容不少于1字节不多于128字节 |
| msgmenu.list.view | 否 | obj | type为view的菜单项 |
| msgmenu.list.view.url | 是 | string | 点击后跳转的链接。不少于1字节不多于2048字节 |
| msgmenu.list.view.content | 是 | string | 菜单显示内容。不少于1字节不多于1024字节 |
| msgmenu.list.miniprogram | 否 | obj | type为miniprogram的菜单项 |
| msgmenu.list.miniprogram.appid | 是 | string | 小程序appid。不少于1字节不多于32字节 |
| msgmenu.list.miniprogram.pagepath | 是 | string | 点击后进入的小程序页面。不少于1字节不多于1024字节 |
| msgmenu.list.miniprogram.content | 是 | string | 菜单显示内容。不多于1024字节 |
| msgmenu.list.text | 否 | obj | type为text的菜单项 |
| msgmenu.list.text.content | 是 | string | 文本内容，支持\n（\和n两个字符）换行。不少于1字节不多于256字节 |
| msgmenu.list.text.no_newline | 否 | bool | 内容后面是否不换行，0-换行 1-不换行，默认为0。可用于普通文本和其他菜单类型混排，消息内容更丰富 |
| msgmenu.tail_content | 否 | string | 结束文本不多于1024字节 |
其中，“满意”和“不满意”两个菜单当用户点击后，用户会自动回复一条文本消息，同时附带对应的菜单ID。
菜单消息展现：
地理位置消息
请求示例：
{ "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "location", "location": { "name": "测试小区", "address": "实例小区，不真实存在，经纬度无意义", "latitude": 0, "longitude": 0 }}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：location |
| location | 是 | obj | 地理位置消息 |
| location.name | 否 | string | 位置名 |
| location.address | 否 | string | 地址详情说明 |
| location.latitude | 是 | float | 纬度，浮点数，范围为90 ~ -90 |
| location.longitude | 是 | float | 经度，浮点数，范围为180 ~ -180 |
获客链接消息
将获客链接转成名片消息下发给微信客户。
微信客户通过这种方式打开名片，在获客助手的数据统计上，暂不会计算到打开链接的客户数中，其他添加等数据不影响。
请求示例：
{ "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "ca_link", "ca_link": { "link_url": "https://work.weixin.qq.com/ca/xxxxxx" }}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| touser | 是 | string | 指定接收消息的客户UserID |
| open_kfid | 是 | string | 指定发送消息的客服账号ID |
| msgid | 否 | string | 指定消息ID |
| msgtype | 是 | string | 消息类型，此时固定为：ca_link |
| ca_link | 是 | obj | 获客链接消息 |
| ca_link.link_url | 是 | string | 通过获客助手创建的获客链接 |
发送欢迎语等事件响应消息
最后更新：2023/11/30
概述
当特定的事件回调消息包含code字段，或通过接口变更到特定的会话状态，会返回code字段。
开发者可以此code为凭证，调用该接口给用户发送相应事件场景下的消息，如客服欢迎语、客服提示语和会话结束语等。
除"用户进入会话事件"以外，响应消息仅支持会话处于获取该code的会话状态时发送，如将会话转入待接入池时获得的code仅能在会话状态为”待接入池排队中“时发送。
目前支持的事件场景和相关约束如下：
| 事件场景 | 允许下发条数 | code有效期 | 支持的消息类型 | 获取code途径 |
|---|---|---|---|---|
| 用户进入会话，用于发送客服欢迎语 | 1条 | 20秒 | 文本、菜单 | 事件回调 |
| 进入接待池，用于发送排队提示语等 | 1条 | 48小时 | 文本 | 转接会话接口 |
| 从接待池接入会话，用于发送非工作时间的提示语或超时未回复的提示语等 | 1条 | 48小时 | 文本 | 事件回调、转接会话接口 |
| 结束会话，用于发送结束会话提示语或满意度评价等 | 1条 | 20秒 | 文本、菜单 | 事件回调、转接会话接口 |
接口定义
请求方式: POST(HTTPS)
请求地址: https://qyapi.weixin.qq.com/cgi-bin/kf/send_msg_on_event?access_token=ACCESS_TOKEN
请求示例
{ "code": "CODE", "msgid": "MSG_ID", "msgtype": "MSG_TYPE"}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| code | 是 | string | 事件响应消息对应的code。通过事件回调下发，仅可使用一次。 |
| msgid | 否 | string | 消息ID。如果请求参数指定了msgid，则原样返回，否则系统自动生成并返回。不多于32字节字符串取值范围(正则表达式)：[0-9a-zA-Z_-]* |
| msgtype | 是 | string | 消息类型。对不同的msgtype，有相应的结构描述，详见消息类型 |
「进入会话事件」响应消息：
用户在过去48小时里未收过欢迎语，且未向客服发过消息
welcome_codecode
权限说明:
调用的应用需要满足如下的权限
| 应用类型 | 权限要求 |
|---|---|
| 自建应用 | 配置到「 微信客服- 可调用接口的应用」中 |
| 第三方应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
| 代开发自建应用 | 具有“微信客服->管理账号、分配会话和收发消息”权限 |
注： 从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响 查看详情
- 只能通过API管理企业指定的客服账号。企业可在管理后台“微信客服-通过API管理微信客服账号”处设置对应的客服账号通过API来管理。
- 操作的客服账号对应的接待人员应在应用的可见范围内
返回结果:
{ "errcode": 0, "errmsg": "ok", "msgid": "MSG_ID"}
参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | int32 | 返回码 |
| errmsg | string | 错误码描述 |
| msgid | string | 消息ID |
消息类型
文本消息
请求示例：
{ "code": "CODE", "msgid": "MSG_ID", "msgtype" : "text", "text" : { "content" : "欢迎咨询" }}
参数说明：
| 参数 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| msgtype | 是 | string | 消息类型，此时固定为：text |
| text | 是 | obj | 文本消息 |
| text.content | 是 | string | 消息内容，最长不超过2048个字节 |
菜单消息
请求示例：
{ "code": "CODE" "msgid": "MSGID", "msgtype": "msgmenu", "msgmenu": { "head_content": "您对本次服务是否满意呢? ", "list": [ { "type": "click", "click": { "id": "101", "content": "满意" } }, { "type": "click", "click": { "id": "102", "content": "不满意" } }, { "type": "view", "view": { "url": "https://work.weixin.qq.com", "content": "点击跳转到自助查询页面" } }, { "type": "miniprogram", "miniprogram": { "appid": "wx123123123123123", "pagepath": "pages/index?userid=zhangsan&orderid=123123123", "content": "点击打开小程序查询更多" } }, { "type": "text", "text": { "content": "纯文本，支持\n换行", "no_newline": 0 } } ], "tail_content": "欢迎再次光临" }}
参数说明：
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
| msgtype | 是 | string | 消息类型，此时固定为：msgmenu |
| msgmenu | 是 | obj | 菜单消息 |
| msgmenu.head_content | 否 | string | 起始文本不多于1024字节 |
| msgmenu.list | 否 | obj[] | 菜单项配置，不超过10个 |
| msgmenu.list.type | 是 | string | 菜单类型。click-回复菜单 view-超链接菜单 miniprogram-小程序菜单 text-文本 |
| msgmenu.list.click | 否 | obj | type为click的菜单项 |
| msgmenu.list.click.id | 否 | string | 菜单ID。不少于1字节不多于128字节 |
| msgmenu.list.click.content | 是 | string | 菜单显示内容不少于1字节不多于128字节 |
| msgmenu.list.view | 否 | obj | type为view的菜单项 |
| msgmenu.list.view.url | 是 | string | 点击后跳转的链接。不少于1字节不多于2048字节 |
| msgmenu.list.view.content | 是 | string | 菜单显示内容。不少于1字节不多于1024字节 |
| msgmenu.list.miniprogram | 否 | obj | type为miniprogram的菜单项 |
| msgmenu.list.miniprogram.appid | 是 | string | 小程序appid。不少于1字节不多于32字节 |
| msgmenu.list.miniprogram.pagepath | 是 | string | 点击后进入的小程序页面。不少于1字节不多于1024字节 |
| msgmenu.list.miniprogram.content | 是 | string | 菜单显示内容。不多于1024字节 |
| msgmenu.list.text | 否 | obj | type为text的菜单项 |
| msgmenu.list.text.content | 是 | string | 文本内容，支持\n（\和n两个字符）换行。不少于1字节不多于256字节 |
| msgmenu.list.text.no_newline | 否 | bool | 内容后面是否不换行，0-换行 1-不换行，默认为0 |
| msgmenu.tail_content | 否 | string | 结束文本不多于1024字节 |