获取客户基础信息
最后更新：2025/11/18
请求方式: POST(HTTPS)
请求地址: https://qyapi.weixin.qq.com/cgi-bin/kf/customer/batchget?access_token=ACCESS_TOKEN
请求实例:
{ "external_userid_list": [ "wmxxxxxxxxxxxxxxxxxxxxxx", "zhangsan" ], "need_enter_session_context": 0}
参数说明：
| 参数 | 是否必须 | 说明 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| external_userid_list | 是 | external_userid列表可填充个数：1 ~ 100。超过100个需分批调用。 |
| need_enter_session_context | 否 | 是否需要返回客户48小时内最后一次进入会话的上下文信息。0-不返回 1-返回。默认不返回 |
权限说明:
调用的应用需要满足如下的权限
| 应用类型 | 权限要求 |
|---|---|
| 自建应用 | 配置到「 微信客服- 可调用接口的应用」中 |
| 第三方应用 | 具有“微信客服->获取基础信息”权限 |
| 代开发自建应用 | 具有“微信客服->获取基础信息”权限 |
注意
[](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHJ4PSI4IiBmaWxsPSIjQjM2NzFEIi8+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik04IDNDNy40NDc3MiAzIDcgMy40NDc3MiA3IDRWOEM3IDguNTUyMjggNy40NDc3MiA5IDggOUM4LjU1MjI4IDkgOSA4LjU1MjI4IDkgOFY0QzkgMy40NDc3MiA4LjU1MjI4IDMgOCAzWk04IDExQzcuNDQ3NzIgMTEgNyAxMS40NDc3IDcgMTJDNyAxMi41NTIzIDcuNDQ3NzIgMTMgOCAxM0M4LjU1MjI4IDEzIDkgMTIuNTUyMyA5IDEyQzkgMTEuNDQ3NyA4LjU1MjI4IDExIDggMTFaIiBmaWxsPSJ3aGl0ZSIvPjwvc3ZnPg==)
从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响 查看详情。external_userid 需为最近 48 小时内有触发用户进入会话事件或向该客服账号发过消息的客户，否则在 invalid_external_userid 返回。「营销获客」应用只能获取到该应用带来的客户，也就是「营销获客」应用管理的微信客服账号的客户
返回结果:
{ "errcode": 0, "errmsg": "ok", "customer_list": [ { "external_userid": "wmxxxxxxxxxxxxxxxxxxxxxx", "nickname": "张三", "avatar": "http://xxxxx", "gender": 1, "unionid": "oxasdaosaosdasdasdasd", "enter_session_context": { "scene": "123", "scene_param": "abc", "wechat_channels": { "nickname": "进入会话的视频号名称", "scene": 1 } } } ], "invalid_external_userid": [ "zhangsan" ]}
参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | int | 返回码 |
| errmsg | string | 错误码描述 |
| customer_list | array | 返回结果 |
| customer_list.external_userid | string | 微信客户的external_userid |
| customer_list.nickname | string | 微信昵称 |
| customer_list.avatar | string | 微信头像。第三方应用和代开发应用均不可获取 |
| customer_list.gender | int | 性别。第三方应用和代开发应用均不可获取，统一返回0 |
| customer_list.unionid | string | unionid，需要绑定微信开发者账号才能获取到，查看绑定方法。第三方不可获取 |
| customer_list.enter_session_context | obj | 48小时内最后一次进入会话的上下文信息。请求的need_enter_session_context参数设置为1才返回 |
| customer_list.enter_session_context.scene | string | 进入会话的场景值，获取客服账号链接开发者自定义的场景值 |
| customer_list.enter_session_context.scene_param | string | 进入会话的自定义参数，获取客服账号链接返回的url，开发者按规范拼接的scene_param参数 |
| customer_list.enter_session_context.wechat_channels | obj | 进入会话的视频号信息，从视频号进入会话才有值 |
| customer_list.enter_session_context.wechat_channels.nickname | string | 视频号名称，视频号场景值为1、2、3时返回此项 |
| customer_list.enter_session_context.wechat_channels.shop_nickname | string | 视频号小店名称，视频号场景值为4、5时返回此项 |
| customer_list.enter_session_context.wechat_channels.scene | uint32 | 视频号场景值。1：视频号主页，2：视频号直播间商品列表页，3：视频号商品橱窗页，4：视频号小店商品详情页，5：视频号小店订单页 |
如何获取微信客户的Unionid
企业内部开发和第三方应用开发，获取Unionid的方式不同。
企业内部开发
- 在企业微信管理后台“应用管理-微信客服-通过API管理微信客服”处，点击“绑定”去到微信公众平台进行授权，支持绑定公众号和小程序（需要同时绑定微信开放平台）；绑定的公众号或小程序主体需与企业微信主体一致，暂且支持绑定一个
- 绑定完成后，当客户进入客服会话或发起咨询时，即可通过此接口获取微信客户所对应的微信Unionid
第三方应用开发
- 企业授权第三方应用管理指定的客服账号的会话消息时，当微信客户进入该客服会话或发起咨询时，第三方可获取该客户的external_userid
- 第三方需自行通过其他已有的方式获取客户的Unionid
- 再通过Unionid与external_userid关联接口 ，将获取到的Unionid和external_userid实现关联识别。
获取「客户数据统计」企业汇总数据
最后更新：2023/11/30
通过此接口，可以获取咨询会话数、咨询客户数等企业汇总统计数据
请求方式: POST(HTTPS)
请求地址: https://qyapi.weixin.qq.com/cgi-bin/kf/get_corp_statistic?access_token=ACCESS_TOKEN
请求示例
{ "open_kfid": "OPEN_KFID", "start_time": 1645545600, "end_time": 1645632000}
参数说明:
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| open_kfid | 是 | string | 客服账号ID |
| start_time | 是 | uint32 | 起始日期的时间戳，填这一天的0时0分0秒（否则系统自动处理为当天的0分0秒）。取值范围：昨天至前180天 |
| end_time | 是 | uint32 | 结束日期的时间戳，填这一天的0时0分0秒（否则系统自动处理为当天的0分0秒）。取值范围：昨天至前180天 |
查询时间区间[start_time, end_time]为闭区间，最大查询跨度为31天，用户最多可获取最近180天内的数据。当天的数据需要等到第二天才能获取，建议在第二天早上六点以后再调用此接口获取前一天的数据
当传入的时间不为0点时，会向下取整，如传入1554296400(Wed Apr 3 21:00:00 CST 2019)会被自动转换为1554220800（Wed Apr 3 00:00:00 CST 2019）;
开启API或授权第三方应用管理会话，没有2022年3月11日以前的统计数据
权限说明:
调用的应用需要满足如下的权限
| 应用类型 | 权限要求 |
|---|---|
| 自建应用 | 配置到「 微信客服- 可调用接口的应用」中 |
| 第三方应用 | 具有“微信客服->服务工具->获取客服数据统计”权限 |
| 代开发自建应用 | 具有“微信客服->服务工具->获取客服数据统计”权限 |
注： 从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响 查看详情
- 操作的客服账号对应的接待人员应在应用的可见范围内
返回结果:
{ "errcode": 0, "errmsg": "ok", "statistic_list" : [ { "stat_time" : 1645545600, "statistic" : { "session_cnt" : 2, "customer_cnt" : 1, "customer_msg_cnt" : 6, "upgrade_service_customer_cnt" : 0, "ai_session_reply_cnt" : 1, "ai_transfer_rate" : 1, "ai_knowledge_hit_rate" : 0, "msg_rejected_customer_cnt" : 1 }, }, { "stat_time" : 1645632000, "statistic" : { ... } } ]}
参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | int32 | 返回码 |
| errmsg | string | 错误码描述 |
| statistic_list | obj | 统计数据列表 |
| statistic_list.stat_time | uint32 | 数据统计日期，为当日0点的时间戳 |
| statistic_list.statistic | obj | 一天的统计数据。若当天未产生任何下列统计数据或统计数据还未计算完成则不会返回此项 |
| statistic_list.statistic.session_cnt | uint64 | 咨询会话数。客户发过消息并分配给接待人员或智能助手的客服会话数，转接不会产生新的会话 |
| statistic_list.statistic.customer_cnt | uint64 | 咨询客户数。在会话中发送过消息的客户数量，若客户多次咨询只计算一个客户 |
| statistic_list.statistic.customer_msg_cnt | uint64 | 咨询消息总数。客户在会话中发送的消息的数量 |
| statistic_list.statistic.upgrade_service_customer_cnt | uint64 | 升级服务客户数。通过「升级服务」功能成功添加专员或加入客户群的客户数，若同一个客户添加多个专员或客户群，只计算一个客户。在2022年3月10日以后才会有对应统计数据 |
| statistic_list.statistic.ai_session_reply_cnt | uint64 | 智能回复会话数。客户发过消息并分配给智能助手的咨询会话数。通过API发消息或者开启智能回复功能会将客户分配给智能助手 |
| statistic_list.statistic.ai_transfer_rate | float | 转人工率。一个自然日内，客户给智能助手发消息的会话中，转人工的会话的占比。 |
| statistic_list.statistic.ai_knowledge_hit_rate | float | 知识命中率。一个自然日内，客户给智能助手发送的消息中，命中知识库的占比。只有在开启了智能回复原生功能并配置了知识库的情况下，才会产生该项统计数据。当api托管了会话分配，智能回复原生功能失效。若不返回，代表没有向配置知识库的智能接待助手发送消息，该项无法计算 |
| statistic_list.statistic.msg_rejected_customer_cnt | uint64 | 被拒收消息的客户数。被接待人员设置了“不再接收消息”的客户数 |
获取「客户数据统计」接待人员明细数据
最后更新：2023/11/30
通过此接口，可获取接入人工会话数、咨询会话数等与接待人员相关的统计信息
请求方式: POST(HTTPS)
请求地址: https://qyapi.weixin.qq.com/cgi-bin/kf/get_servicer_statistic?access_token=ACCESS_TOKEN
请求示例
{ "open_kfid": "OPEN_KFID", "servicer_userid":"zhangsan", "start_time": 1645545600, "end_time": 1645632000}
参数说明:
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| open_kfid | 是 | string | 客服账号ID |
| servicer_userid | 否 | string | 接待人员的userid。第三方应用为密文userid，即open_userid |
| start_time | 是 | uint32 | 起始日期的时间戳，填当天的0时0分0秒（否则系统自动处理为当天的0分0秒）。取值范围：昨天至前180天 |
| end_time | 是 | uint32 | 结束日期的时间戳，填当天的0时0分0秒（否则系统自动处理为当天的0分0秒）。取值范围：昨天至前180天 |
servicer_userid为非必填参数:
查询时间区间[start_time, end_time]为闭区间，最大查询跨度为31天，用户最多可获取最近180天内的数据。当天的数据需要等到第二天才能获取，建议在第二天早上六点以后再调用此接口获取前一天的数据
当传入的时间不为0点时，会向下取整，如传入1554296400(Wed Apr 3 21:00:00 CST 2019)会被自动转换为1554220800（Wed Apr 3 00:00:00 CST 2019）;
开启API或授权第三方应用管理会话，没有2022年3月11日以前的统计数据
权限说明:
调用的应用需要满足如下的权限
| 应用类型 | 权限要求 |
|---|---|
| 自建应用 | 配置到「 微信客服- 可调用接口的应用」中 |
| 第三方应用 | 具有“微信客服->服务工具->获取客服数据统计”权限 |
| 代开发自建应用 | 具有“微信客服->服务工具->获取客服数据统计”权限 |
注： 从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响 查看详情
- 操作的客服账号对应的接待人员应在应用的可见范围内
返回结果:
{ "errcode": 0, "errmsg": "ok", "statistic_list" : [ { "stat_time" : 1645545600, "statistic" : { "session_cnt" : 1, "customer_cnt" : 1, "customer_msg_cnt" : 1, "reply_rate" : 1, "first_reply_average_sec" : 17, "satisfaction_investgate_cnt" : 1, "satisfaction_participation_rate" : 1, "satisfied_rate" : 1, "middling_rate" : 0, "dissatisfied_rate" : 0, "upgrade_service_customer_cnt" : 0, "upgrade_service_member_invite_cnt" : 0, "upgrade_service_member_customer_cnt" : 0, "upgrade_service_groupchat_invite_cnt" : 0, "upgrade_service_groupchat_customer_cnt" : 0, "msg_rejected_customer_cnt" : 1 } }, { "stat_time" : 1645632000, "statistic" : { ... } } ]}
参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | int32 | 返回码 |
| errmsg | string | 错误码描述 |
| statistic_list | obj | 统计数据列表 |
| statistic_list.stat_time | uint32 | 数据统计日期，为当日0点的时间戳 |
| statistic_list.statistic | obj | 一天的统计数据。若当天未产生任何下列统计数据或统计数据还未计算完成则不会返回此项 |
| statistic_list.statistic.session_cnt | uint64 | 接入人工会话数。客户发过消息并分配给接待人员的咨询会话数 |
| statistic_list.statistic.customer_cnt | uint64 | 咨询客户数。在会话中发送过消息且接入了人工会话的客户数量，若客户多次咨询只计算一个客户 |
| statistic_list.statistic.customer_msg_cnt | uint64 | 咨询消息总数。客户在会话中发送的消息的数量 |
| statistic_list.statistic.reply_rate | float | 人工回复率。一个自然日内，客户给接待人员发消息的会话中，接待人员回复了的会话的占比。若数据项不返回，代表没有给接待人员发送消息的客户，此项无法计算。 |
| statistic_list.statistic.first_reply_average_sec | float | 平均首次响应时长，单位：秒。一个自然日内，客户给接待人员发送的第一条消息至接待人员回复之间的时长，为首次响应时长。所有的首次回复总时长/已回复的咨询会话数，即为平均首次响应时长 。若数据项不返回，代表没有给接待人员发送消息的客户，此项无法计算 |
| statistic_list.statistic.satisfaction_investgate_cnt | uint64 | 满意度评价发送数。当api托管了会话分配，满意度原生功能失效，满意度评价发送数为0 |
| statistic_list.statistic.satisfaction_participation_rate | float | 满意度参评率 。当api托管了会话分配，满意度原生功能失效。若数据项不返回，代表没有发送满意度评价，此项无法计算 |
| statistic_list.statistic.satisfied_rate | float | “满意”评价占比 。在客户参评的满意度评价中，评价是“满意”的占比。当api托管了会话分配，满意度原生功能失效。若数据项不返回，代表没有客户参评的满意度评价，此项无法计算 |
| statistic_list.statistic.middling_rate | float | “一般”评价占比 。在客户参评的满意度评价中，评价是“一般”的占比。当api托管了会话分配，满意度原生功能失效。若数据项不返回，代表没有客户参评的满意度评价，此项无法计算 |
| statistic_list.statistic.dissatisfied_rate | float | “不满意”评价占比。在客户参评的满意度评价中，评价是“不满意”的占比。当api托管了会话分配，满意度原生功能失效。若数据项不返回，代表没有客户参评的满意度评价，此项无法计算 |
| statistic_list.statistic.upgrade_service_customer_cnt | uint64 | 升级服务客户数。通过「升级服务」功能成功添加专员或加入客户群的客户数，若同一个客户添加多个专员或客户群，只计算一个客户。在2022年3月10日以后才会有对应统计数据 |
| statistic_list.statistic.upgrade_service_member_invite_cnt | uint64 | 专员服务邀请数。接待人员通过「升级服务-专员服务」向客户发送服务专员名片的次数。在2022年3月10日以后才会有对应统计数据 |
| statistic_list.statistic.upgrade_service_member_customer_cnt | uint64 | 添加专员的客户数 。客户成功添加专员为好友的数量，若同一个客户添加多个专员，则计算多个客户数。在2022年3月10日以后才会有对应统计数据 |
| statistic_list.statistic.upgrade_service_groupchat_invite_cnt | uint64 | 客户群服务邀请数。接待人员通过「升级服务-客户群服务」向客户发送客户群二维码的次数。在2022年3月10日以后才会有对应统计数据 |
| statistic_list.statistic.upgrade_service_groupchat_customer_cnt | uint64 | 加入客户群的客户数。客户成功加入客户群的数量，若同一个客户加多个客户群，则计算多个客户数。在2022年3月10日以后才会有对应统计数据 |
| statistic_list.statistic.msg_rejected_customer_cnt | uint64 | 被拒收消息的客户数。被接待人员设置了“不再接收消息”的客户数 |