在微信机器人的好友关系处理中，有一个比较特殊但很实用的能力——获取手机通讯录。它解决的核心问题是：把一批手机号与微信号建立对应关系。在 微信个人号二次开发 的客户资料补全、手机号加好友前置校验等场景中，这个接口经常会用到。本文记录一下 WTAPI 微信机器人接口 中 获取手机通讯录 接口（getPhoneAddressList）的对接思路。

接口地址为 /finder/v2/api/contacts/getPhoneAddressList，采用 HTTP POST 调用，属于 微信 API 通讯录模块。

入参只有两个：

• appId：设备实例 ID，登录后获取；
• phones：手机号数组，可选参数。传入时只查询指定手机号对应的好友信息；不传则获取当前设备通讯录中的全部匹配结果。

这个设计的好处是灵活：既可以做单条/批量手机号精确查询，也可以做一次全量拉取后在本地建立映射库。

返回结果是一个数组，每个元素对应一个匹配到的联系人，关键字段包括：

• userName：对方的 wxid，这是后续发消息、加好友等操作的核心标识；
• phoneMd5：手机号的 MD5 值，用于和本地导入的号码做匹配对照；
• nickName、alias、sex、signature：昵称、微信号、性别、签名等基础资料；
• country、province、city：地区信息；
• bigHeadImgUrl、smallHeadImgUrl：大小尺寸头像；
• v4：在部分未匹配场景下用于后续添加好友流程的凭证；
• personalCard：名片相关标识。
  调用示例

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://wx.chuapi.com/finder/v2/api/contacts/getPhoneAddressList")
   .header("X-finder-TOKEN", "")
   .header("Authorization", "Bearer eyJhbGciOiJIUzUxMiJ9.eyJsb2dpbl91c2VyX2tleSI6IjAxNmM2ZDQ5LWIxNWMtNGRjMy05YzQzLWZmYzZmNDhhMTg3MyJ9.1JWq9ntjam20_XDlSbklWTxbV-vg-F_dY1LYVX05BndRAuaJbv3iSwoDY-BuMwe1sdKxDXtDTMWJgXNMff4nOg")
   .header("Content-Type", "application/json")
   .body("{\n    \"appId\": \"{{appid}}\",\n    \"phones\": []\n}")
   .asString();

实际开发中有几点需要注意：

第一，返回的手机号是 MD5 加密形式，不会回传明文，所以匹配逻辑需要在本地把手机号做同样的 MD5 处理后再比对，这也保证了数据安全。第二，phones 数组建议分批传入，号码量过大时拆成多次请求，避免单次请求过重。第三，不是每个手机号都一定能匹配到微信号，未开通"通过手机号搜索到我"或本身未注册微信的号码不会返回结果，业务上要做好空值兼容。第四，拿到的资料建议落库缓存，地区、头像、昵称这类信息变更频率低，没必要重复拉取。

典型使用流程是：导入手机号名单 → 调用获取手机通讯录接口 → 用 phoneMd5 与本地号码匹配 → 拿到 wxid 和资料入库 → 后续直接通过 微信接口 发消息或走添加好友流程。

小结

获取手机通讯录接口本质上是一座"手机号 → wxid"的桥梁。配合本地 MD5 匹配和资料缓存，它能让微信机器人快速完成号码与微信身份的绑定，是 微信个人号二次开发 中客户数据整合环节很基础的一环。