企业微信联系人开发实战

为什么企业微信联系人值得单独开发

很多团队在接入企业微信时，第一反应是只做消息推送和扫码登录。但真正做深之后会发现，企业微信联系人才是业务闭环的核心：外部客户、上下游伙伴、内部员工，都挂在同一个通讯录体系下。把联系人打通，CRM、工单、审批、群运营才能串起来。

本文基于我最近一个客户管理项目，分享一套可落地的企业微信联系人开发方法，覆盖通讯录同步、外部联系人获取、回调事件处理三个关键环节。

一、先理清三类联系人

• 内部成员：通过user/list接口按部门拉取，属于企业通讯录。
• 外部联系人：客户、供应商，通过external_contact系列接口获取，需要成员授权。
• 互联企业联系人：上下游企业成员，走corpgroup接口。

三者数据模型不同，建议在数据库里用contact_type字段区分，避免后期混表。

二、内部通讯录同步方法

同步逻辑不复杂，难点在增量与限流。企业微信通讯录接口有调用频率限制，全量拉取容易触发45009错误。我的做法是：

1. 用department/list先拉部门树，缓存到本地。
2. 按部门递归调用user/list，每次只取fetch_child=0的直接成员。
3. 用user/get补全详情，写入时以userid为唯一键做 upsert。
4. 记录last_sync_time，下一次只处理变更。

async function syncDept(deptId) {
  const users = await wxwork.user.list({
    department_id: deptId,
    fetch_child: 0
  });
  for (const u of users.userlist) {
    await db.contact.upsert({
      where: { userid: u.userid },
      update: { name: u.name, mobile: u.mobile },
      create: { ...u, contact_type: 'internal' }
    });
  }
}

三、外部联系人的获取姿势

外部联系人是企业微信联系人开发里最容易踩坑的部分。它不能直接批量拉，必须先拿到成员的follow_user列表，再逐个查详情。

1. 配置客户联系权限

在管理后台开启「客户联系」，把需要使用的成员加入使用范围，并配置好可调用接口的应用。否则调用external_contact/list会直接返回无权限。

2. 拉取成员的外部联系人

const res = await wxwork.externalContact.list({
  userid: 'zhangsan'
});
// res.external_userid 是外部联系人的 id 列表
for (const eid of res.external_userid) {
  const detail = await wxwork.externalContact.get({
    external_userid: eid
  });
  // detail.external_contact 含昵称、头像、类型
}

3. 注意 external_userid 的不稳定性

同一个客户在不同企业下external_userid不同，且换绑后可能变化。建议在本地生成union_id作为业务主键，把external_userid当映射字段，方便后续换绑时做合并。

四、回调事件才是实时性的关键

轮询同步永远有延迟，真正让联系人保持鲜活的是回调。企业微信提供change_external_contact事件，覆盖添加、删除、修改备注等动作。

• add_external_contact：客户添加成员，立即落库。
• del_external_contact：客户删除，标记失效而非物理删除。
• change_external_contact：备注、标签变化，更新对应字段。

回调地址需要做 URL 验证和 AES 解密，推荐用官方 SDK 的 WXBizMsgCrypt 处理。收到事件后先返回 success，再异步写库，避免超时重推。

五、几个实战建议

• 字段冗余：外部联系人详情接口字段有限，常用信息如手机号、备注建议本地维护。
• 权限最小化：只申请必要接口权限，客户联系权限审核较严，提前准备使用场景说明。
• 限流兜底：所有接口调用加队列和重试，遇到45009指数退避。
• 数据脱敏：手机号、姓名入库前脱敏，符合合规要求。

企业微信联系人开发不是一次性的活，而是一套持续同步、回调驱动、本地增强的工程。把这三层搭好，后面的客户运营和自动化才有地基。