smart-wx-demo/README.md

企业微信客户联系API Demo

这是一个使用企业微信客户联系API的TypeScript示例项目，演示如何获取客户列表和客户详情。

功能特性

• ✅ 获取access_token（带自动缓存和过期管理）
• ✅ 获取配置了客户联系功能的成员列表
• ✅ 获取客户列表
• ✅ 获取客户详情
• ✅ 批量获取客户详情
• ✅ 支持分页获取（跟进人超过500人时）
• ✅ 完整的TypeScript类型定义
• ✅ 错误处理和响应验证
• ✅ 自动使用第一个成员获取客户列表

项目结构

pg-demo/
├── src/
│   ├── main.ts                 # 主程序入口
│   ├── wechat-client.ts        # 企业微信API客户端
│   └── types/
│       └── wechat.ts           # TypeScript类型定义
├── .env.example                # 环境变量配置示例
├── package.json
└── tsconfig.json

快速开始

1. 安装依赖

pnpm install

2. 配置环境变量

复制 .env.example 为 .env 并填入实际的值：

cp .env.example .env

编辑 .env 文件：

WEIXIN_CORP_ID=your_corp_id
WEIXIN_CORP_SECRET=your_corp_secret
WEIXIN_EXTERNAL_USER_ID=your_external_user_id

3. 运行程序

# 自动使用第一个配置了客户联系功能的成员
pnpm start

# 或者指定特定的企业成员userid
pnpm start <userid>

示例:

# 自动使用第一个成员
pnpm start

# 指定特定成员
pnpm start zhangsan

程序会依次执行以下操作：

1. 获取access_token
2. 获取配置了客户联系功能的成员列表
3. 获取指定成员（或第一个成员）的客户列表
4. 获取第一个客户的详情
5. 批量获取所有客户详情

使用示例

获取配置了客户联系功能的成员列表

import { WeChatClient } from './wechat-client';

// 创建客户端
const client = new WeChatClient({
    corpId: process.env.WEIXIN_CORP_ID!,
    corpSecret: process.env.WEIXIN_CORP_SECRET!,
});

// 获取配置了客户联系功能的成员列表
const followUserList = await client.getFollowUserList();

console.log('成员数量:', followUserList.follow_user?.length || 0);
console.log('成员ID列表:', followUserList.follow_user);

// 使用第一个成员获取客户列表
if (followUserList.follow_user && followUserList.follow_user.length > 0) {
    const firstUserId = followUserList.follow_user[0];
    const contactList = await client.getExternalContactList(firstUserId);
    console.log('客户数量:', contactList.external_userid?.length || 0);
}

获取客户列表

// 获取指定成员的客户列表
const contactList = await client.getExternalContactList('zhangsan');

console.log('客户数量:', contactList.external_userid?.length || 0);
console.log('客户ID列表:', contactList.external_userid);

获取客户详情

// 获取单个客户的详细信息
const contactDetail = await client.getExternalContact('external_user_id');

console.log('客户姓名:', contactDetail.external_contact.name);
console.log('客户类型:', contactDetail.external_contact.type === 1 ? '微信用户' : '企业微信用户');
console.log('跟进人数量:', contactDetail.follow_user.length);

批量获取客户详情

// 批量获取客户详情（支持分页）
const batchContacts = await client.batchGetExternalContact('zhangsan', undefined, 100);

console.log('本次返回客户数量:', batchContacts.external_contact_list?.length || 0);

自动分页获取所有客户

// 自动分页获取所有客户详情
const allContacts = await client.batchGetExternalContactFull('zhangsan');

console.log('总客户数量:', allContacts.length);
allContacts.forEach((contact, index) => {
    console.log(`${index + 1}. ${contact.name} (${contact.external_userid})`);
});

获取客户详情（支持跟进人分页）

当跟进人超过500人时，使用 getExternalContactFull 方法自动获取所有跟进人：

const fullDetail = await client.getExternalContactFull('external_user_id');
console.log('总跟进人数量:', fullDetail.follow_user.length);

API说明

获取配置了客户联系功能的成员列表

接口地址: https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_follow_user_list

请求参数:

• access_token: 调用接口凭证

响应字段:

• follow_user: 配置了客户联系功能的成员userid列表

获取客户列表

接口地址: https://qyapi.weixin.qq.com/cgi-bin/externalcontact/list

请求参数:

• access_token: 调用接口凭证
• userid: 企业成员的userid

响应字段:

• external_userid: 外部联系人的userid列表

获取客户详情

接口地址: https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get

请求参数:

• access_token: 调用接口凭证
• external_userid: 外部联系人的userid
• cursor: （可选）上次请求返回的next_cursor，用于分页

响应字段:

• external_contact: 外部联系人详情
  • name: 名称
  • type: 1-微信用户，2-企业微信用户
  • gender: 0-未知，1-男性，2-女性
  • position: 职位（仅企业微信用户）
  • corp_name: 企业简称（仅企业微信用户）
• follow_user: 添加了此外部联系人的企业成员列表
  • userid: 成员userid
  • remark: 备注
  • description: 描述
  • createtime: 添加时间
  • tags: 标签列表

批量获取客户详情

接口地址: https://qyapi.weixin.qq.com/cgi-bin/externalcontact/batch/get_by_user

请求参数:

• access_token: 调用接口凭证
• userid: 企业成员的userid
• cursor: （可选）上次请求返回的next_cursor，用于分页
• limit: 返回的最大记录数，最大值1000，默认值为100

响应字段:

• external_contact_list: 外部联系人详情列表
• next_cursor: 下一次分页的起始位置

权限要求

应用需要配置到「客户联系 > 可调用接口的应用」中，并具有「客户基础信息」权限。

注意事项

1. access_token有效期: 7200秒，客户端会自动缓存并提前5分钟刷新
2. 分页限制: 当跟进人超过500人时，必须使用cursor参数分页获取
3. 字段限制: 第三方应用无法获取头像、性别、备注手机号、unionid等字段
4. external_userid: 需要通过其他接口（如获取客户列表）获取

相关文档

• 企业微信API文档 - 获取客户详情
• 企业微信API文档 - 获取access_token

许可证

MIT