📌 引言

在企业微信的客户联系场景中，前端开发者经常需要调用 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.agentConfig	ww.register
调用接口	wx.invoke('getCurExternalContact')	ww.getCurExternalContact()
错误处理	回调函数 success/fail	Promise then/catch
工程化支持	较弱	更符合现代前端

---

✅ 总结

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

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

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