引言

在企业微信的客户联系场景中，前端开发者经常需要调用 JS-SDK 提供的接口来获取外部联系人信息。其中，getCurExternalContact 是一个常用方法。但很多人会遇到报错：

getCurExternalContact:fail no permission

这类错误往往让人摸不着头脑。本文将系统梳理出现该错误的原因，并提供详细的排查与解决步骤，同时介绍新版 SDK 的模块化用法。

功能描述

ww.getCurExternalContact() 用于获取当前外部联系人的 userId。
兼容性：企业微信 2.5.8 开始支持。

使用限制

  • 必须使用应用身份进行注册（即新版的 ww.register 或旧版的 agentConfig）。
  • 「营销获客」应用只能获取到该应用带来的客户。
  • 不同入口对应用及用户有相应限制，目前支持的入口有：
    • 联系人详情页
    • 外部单聊工具栏
    • 微信客服工具栏（企业微信 3.1.10 起支持）

入口限制表

entry 值自建应用权限要求第三方应用权限要求用户要求支持最低版本
contact_profile客户联系功能权限企业客户权限->客户基础信息配置了客户联系功能企业微信 2.5.8
single_chat_tools客户联系功能权限企业客户权限->客户基础信息配置了客户联系功能企业微信 2.8.10
single_kf_tools所有微信客服权限->获取基础信息所有企业微信 3.1.10

️ 参数说明

params: Object

  • success (Function) 成功回调
  • fail (Function) 失败回调
  • cancel (Function) 取消回调
  • complete (Function) 完成回调

返回值：Promise<Object>

  • errMsg (string) 通用错误信息
  • errCode (number) 通用错误码
  • userId (string) 当前外部联系人的 userId

❌ 常见错误信息

  • getCurExternalContact:ok → 执行成功
  • getCurExternalContact:fail no permission → 应用签名校验失败或应用不满足权限条件
  • getCurExternalContact:fail without context of external contact → 当前页面入口不支持调用

调用示例

新版调用（推荐）

import * as ww from '@wecom/jssdk';
ww.register({
corpId: 'ww7ca4776b2a70000',       // 必填，企业ID
agentId: 1000247,                  // 必填，应用的AgentID
jsApiList: ['getCurExternalContact'], // 必填，需要使用的JSAPI列表
getConfigSignature,                // 必填，根据url生成企业签名
getAgentConfigSignature            // 必填，根据url生成应用签名
});
async function getConfigSignature(url) {
// 根据 url 生成企业签名
return { timestamp, nonceStr, signature };
}
async function getAgentConfigSignature(url) {
// 根据 url 生成应用签名
return { timestamp, nonceStr, signature };
}
// 调用接口
ww.getCurExternalContact()
.then(res => {
if (res.errMsg === "getCurExternalContact:ok") {
console.log("当前客户ID:", res.userId);
} else {
console.error("调用失败:", res);
}
})
.catch(err => {
console.error("异常:", err);
});

旧版调用（兼容）

wx.config({
beta: true, // 必须启用 beta
debug: true, // 开启调试模式，方便排查
appId: corpId,
timestamp: timestamp,
nonceStr: nonceStr,
signature: signature,
jsApiList: ['getCurExternalContact']
});
wx.ready(function() {
wx.agentConfig({
corpid: corpId,
agentid: agentId,
timestamp: timestamp,
nonceStr: nonceStr,
signature: agentSignature,
jsApiList: ['getCurExternalContact'],
success: function(res) {
console.log("agentConfig ok", res);
},
fail: function(res) {
console.error("agentConfig fail", res);
}
});
});
wx.invoke('getCurExternalContact', {}, function(res){
if(res.err_msg == "getCurExternalContact:ok"){
const userId = res.userId; // 返回当前外部联系人userId
console.log("当前客户ID:", userId);
} else {
console.error("调用失败:", res);
}
});

⚡ 排查步骤（解决 fail no permission）

  1. 确认后台权限配置

    • 企业微信管理后台 → 客户联系 → 权限配置
    • 确认调用成员已在范围内。
      确认后台权限配置

  2. 检查应用权限

    • 应用必须开通客户联系相关接口权限。
    • 确认已绑定开发者ID。
      检查应用权限

  3. 验证签名

    • 确认 getConfigSignature 和 getAgentConfigSignature 返回的签名正确。
    • URL 必须和实际访问地址完全一致。

  4. 确认入口

    • 必须在企业微信内置浏览器调用。
    • 确认入口为联系人详情页或外部单聊工具栏。

  5. 调试技巧

    • 开启 debug:true，查看日志输出。
    • 确认 ww.register 或 wx.agentConfig 返回成功。

对照表：旧版 vs 新版初始化

场景旧版写法新版写法
初始化wx.config + wx.agentConfigww.register
调用接口wx.invoke('getCurExternalContact')ww.getCurExternalContact()
错误处理回调函数 success/failPromise then/catch
工程化支持较弱更符合现代前端

✅ 总结

getCurExternalContact:fail no permission 的根本原因在于 权限配置或调用环境不符。排查顺序如下：

  1. 确认后台权限配置
  2. 检查应用是否开通客户联系接口权限
  3. 验证初始化流程（旧版或新版）是否成功
  4. 确认调用入口在企业微信内置浏览器
  5. 开启调试模式，查看日志

新版 SDK 的 ww.register 提供了更现代的 Promise 风格写法，推荐在工程化项目中使用。