接口说明

更新时间：2026-11-03

"客户资料接口"是为增强客服能力，对有自建客户系统，同时又具备一定开发对接能力的用户，提供的对接接口。完成对接后，可以在知你客服后台显示用户在您的客户管理系统中的用户信息，如订单，历史服务记录等等。接口分为两个部分："查询接口"和"绑定接口（非必须）"。

查询接口

查询接口是通过知你唯一用户ID(uid)去你方的客户系统查询具体的客户信息。返回结果显示在聚合聊天的"客户资料"选项卡里。

查询接口配置方法：

1. 超级管理账号在设置-API对接中填写你方的查询地址
举例：https://example.zhinikefu.com/query
接口说明示意图

配置好后，当公众号或小程序用户点击客服发起咨询时，我们会带上用户咨询来源小程序或公众号的appid，用户在该公众号或小程序的openid及其他相关参数信息，向这个查询接口获取具体的客户信息。

示例：https://example.zhinikefu.com/query?uid=xxx&timestamp=xxx&nonce=xxx&sign=xxx。具体参数如下：

接口请求参数说明

参数名	说明	备注
uid	用户ID	必选参数
appid	查询公众号和小程序信息时，用户所在公众号或小程序的appid	公众号、小程序用户使用此参数，其它渠道用户不使用此参数
openid	查询公众号和小程序信息时，用户openid	公众号、小程序用户使用此参数，其它渠道用户不使用此参数
cid	网站接入网页在线客服插件代码中的channel_id	网页在线客服咨询用户使用此参数，其它渠道用户不使用此参数
tpuid	网页在线客服插件中自定义的访客唯一身份标识client_id	网页在线客服咨询用户使用此参数，其它渠道用户不使用此参数
timestamp	请求时间戳	可以对时间做一个校验，降低重放攻击
nonce	长度16的随机数（字母+数字）	增加签名结果的随机性
sign	签名	详情见「关于签名」

2. 查询结果输出参数要求
如果客户系统查询到相关客户信息，请您按以下参数要求输出返回JSON的形式数据：

{
    "errcode": 0,  // 0 为正常响应
    "data": {
        "crm_info": [
            {
                "label": "手机号",
                "type": "text", //文本类型信息
                "value": "13100000000"
            },
            {
                "label": "订单记录",
                "type": "link", //链接类型信息
                "value": "点击查看订单详情",
                "url": "https://zhinikefu.com/" //需要打开的链接
            },
            {
                "label": "活动名称",
                "value": "活动详情",
                "type": "wxmapp", //微信小程序类型信息
                "appid": "wx899webu3383a", //微信小程序的appid
                "ghid": "gh_ae6449501a82", //微信小程序gh开头的原始ID
                "path": "/pages/detail/detail?eid=676a24ad3f16efd7c6965924", //选填，需要打开的小程序路径，默认空时会打开首页
                 "url": "https://zhinikefu.com/"  //选填，备用链接，如果无法打开小程序会打开此url       
            }
        ]
    }
}

返回参数说明：
data里的每一个对象，都是一组用户信息，label表示标题，value表示具体的客户信息。errcode为-100的时候，表示用户未绑定，会展示下图页面,其它非0值表示获取用户信息失败
接口说明示意图

绑定接口（非必须）

对于公众号和小程序用户，如果您的客户系统中可以通过 appid 和 openid 确定并返回用户信息，则不需要绑定。

但如果您的客户系统除了appid 和 openid外，需要更多用户信息参数（如手机号）才能允许查询到您客户系统对应的用户信息，则需要您额外配置 "绑定接口" 。

绑定接口配置完成后，当客户咨询发起对话时，客服需要在我的对话页面中的"客户资料"选项卡界面，手动填写额外的用户信息后才能完整用户绑定过程，绑定后就可以直接查询到该用户在您客户系统中的信息了。\

绑定接口配置方法：
1. 超级管理账号在设置-API对接中填写你方的绑定地址
接口说明示意图
当客服在"客户资料"选项卡界面发起绑定操作的。发送POST请求到绑定地址。绑定参数这一栏，"绑定参数名"是给客服看到，参数key是给服务端对接获取用的。例如，我们给自己客服系统增加的配置：

2. 客服同学手动填写额外用户信息完成绑定过程
当客户咨询发起对话时，客服需要在我的对话页面中的"客户资料"选项卡界面，手动填写额外的用户信息后完成用户绑定过程，你方系统需要记录客服手动填写的用户绑定信息和该用户的绑定关系，绑定后我方系统会通过上面的查询接口去你方客户系统中查询该用户在的信息。例如：接口说明示意图
当客服填入手机号：13100000000，点击绑定后，我们会组装一个POST请求，发送到绑定地址。具体发送参数如下：

参数名	说明	备注
uid	用户ID
appid	公众号或小程序appid	公众号、小程序使用此参数查询，其它渠道用户不使用此参数
openid	公众号或小程序openid	公众号、小程序使用此参数查询，其它渠道用户不使用此参数
bind	表示绑定还是解绑（0：解绑 1：绑定）
bind_key	参数名（bind=0不存在此字段）	比如：phone
bind_value	参数值（bind=0不存在此字段）	比如：13100000000
name	用户名称（bind=0不存在此字段）
avatar	用户头像（bind=0不存在此字段）
timestamp	请求时间
nonce	长度16的随机数（字母+数字）
sign	签名	用于合法性验证

返回参数说明：
如果客服输入的手机号在客户系统查到，绑定成功后，应返回JSON格式的消息体，errcode为0，如：{"errcode":0}，网页端收到正确的返回值后，会自动调用一次查询接口，查询关联的客户信息。当收到errcode值不为0时，则认为绑定失败，会重新显示绑定界面。

关于签名

为了接口合法使用，我们对接口调用进行了鉴权。在设置界面完善信息后，我们系统会生成一串随机码，即密钥（SecretKey）。在调用贵司接口的时候，我们服务端会根据SecretKey，计算出签名值，即sign，具体算法如下：
所有发送的数据为集合M，集合M中添加secret= SecretKey (客户资料对接界面显示的secretKey)，将集合M内参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2...）拼接成字符串stringA，并对stringA进行sha256运算，再将得到的字符串所有字符转换为大写，得到sign值signValue