获取手机通讯录

查询当前微信实例已同步的手机通讯录匹配结果。

接口地址： POST /phoneAddressList

前置条件

• 微信实例已登录，并已获得可用 wId。
• 如需查询新上传的手机号，请先调用 上传通讯录。
• 通讯录匹配结果受微信侧同步状态影响，刚上传后可能需要等待一段时间再查询。

请求参数

参数名	必选	类型	说明
wId	是	string	登录实例标识

响应参数

参数名	类型	说明
code	string	1000 成功，1001 失败
message	string	反馈信息
data	array	通讯录联系人列表
data[].phoneMD5	string	手机号 MD5 值
data[].userName	string	微信原始 ID
data[].nickName	string	昵称
data[].signature	string	个性签名
data[].sex	int	性别
data[].aliasName	string	微信号，用户设置后返回
data[].country	string	国家
data[].bigHead	string	大头像 URL
data[].smallHead	string	小头像 URL
data[].v1	string	添加好友凭证 1；如果已经是好友，可能返回微信原始 ID
data[].v2	string	添加好友凭证 2

请求示例

{
  "wId": "0000016f-a2f0-03e3-0003-65e826091614"
}

成功响应

{
  "code": "1000",
  "message": "获取通讯录成功",
  "data": [
    {
      "phoneMD5": "a0a5as32a1936da33fa3376ac14f5023c",
      "userName": "wxid_u5s1f1jnuyijd22",
      "nickName": "朱忠亮爷爷",
      "signature": null,
      "sex": 0,
      "aliasName": null,
      "country": null,
      "bigHead": "http://wx.qlogo.cn/mmhead/ver_1/WzRtKEXrNq7N84qiaVQB0ZSST5sUibCXq11zOib7ujS5tGeDYKwaIZzXbFicRcXsHEJia1wzhvicaLI8fwJl3E80d3OxwyHQK4mDe0DliceUPicOa3s0/0",
      "smallHead": "http://wx.qlogo.cn/mmhead/ver_1/WzRtKEXrNq7N84qiaVQB0ZSST5sUibCXq11zOib7ujS5tGeDYKwaIZzXbFicRcXsHEJia1wzhvicaLI8fwJl3E80d3OxwyHQK4mDe0DliceUPicOa3s0/132",
      "v1": "v3_020b3826fd0301000817533cb3000000501ea9a3dba12f95f6b60a0536a1adb690dcccc9bf58cc80765e6eb16b0219e8063600d0a992cf51f7288e34a104279c9a0a8e0c9b3566caf01d2dc6fb767d83dc8326be166023326841421f09@stranger",
      "v2": "v4_000b708f0b04000001000000005c9bdbbd15c8bb5e536f1d641000000050ded0b020927e3c97896a09d47e6e9e123bccee7113c1059f23719f0475e252e23a8974c9afd6f9040bbe75e494a97eac07500433c50f03501dd3e3e712843a093e453545c1c6c01360a188478298f3f180134ac7d91d47c9@stranger"
    },
    {
      "phoneMD5": "30363ed6bed82sef887727cf93c054f42",
      "userName": "wxid_ss2anfqssb0tu11",
      "nickName": "coco",
      "signature": null,
      "sex": 2,
      "aliasName": null,
      "country": "中国",
      "bigHead": "https://wx.qlogo.cn/mmhead/ver_1/mP3bOfckoXf3e3d6pUFr1jlsfgISsQxLngqBd2QGGuNQguF2ACzCeFjmicXia0MeK8L8iaWE7NvoWibOJmciaHtktqa95UxW4dtV3gMZ2546wiccZ8/0",
      "smallHead": "http://wx.qlogo.cn/mmhead/ver_1/mP3bOfckoXf3e3d6pUFr1jlsfgISQsxLngqBd2QGGuNQguF2ACzCeFjmicXia0MeK8L8iaWE7NvoWibOJmciaHtktqa95UxW4dtV3gMZ2546wiccZ8/132",
      "v1": "v3_020b3826fd0301000817533cb3000000501ea9a3dba12f95f6b60a0536a1adb690dcccc9bf58cc80765e6eb16b0219e8063600d0a992cf51f7288e34a104279c9a0a8e0c9b3c6fb767d83dc8326be166023326841421f09@stranger",
      "v2": "v4_000b708f0b04000001000000005c9bdbbd15c8bb5e536f1d641000000050ded0b020927e3c97896a09d47e6e9e123bccee7113c1059f23719f0475e252e23a8974c9afd6f9040bbe75e494a97433c50f03501dd3e3e712843a093e453545c1c6c01360a188478298f3f180134ac7d91d47c9@stranger"
    },
    {
      "phoneMD5": "fc8e92fbbs5ddf4fa6350c9e9e0653ae38",
      "userName": "wxid_gth3sdfrkq9lk622",
      "nickName": "苏醒",
      "signature": null,
      "sex": 2,
      "aliasName": null,
      "country": "中国",
      "bigHead": "http://wx.qlogo.cn/smmhead/ver_1/f6zWOO8ZXBCU69rTTG14UnKuIeicY6Vs5hVuKN6FDRIkGyQlGCCQYgKVIUJCA7eMohRIA9RRLrx9UZuAvZkhKWzVQnxIK0mqRvx14YjApXbA/0",
      "smallHead": "http://wx.qlogo.cns/mmhead/ver_1/f6zWOO8ZXBCU69rTTG14UnKuIeicY6Vs5hVuKN6FDRIkGyQlGCCQYgKVIUJCA7eMohRIA9RRLrx9UZuAvZkhKWzVQnxIK0mqRvx14YjApXbA/132",
      "v1": "v3_020b3826fd0301000817533cb30000003dba12f95f6b60a0536a1adb690dcccc9bf58cc80765e6eb16b0219e8063600d0a992cf51f7288e34a104279c9a0a8e0c9b3566caf01d2dc6fb767d83dc8326be166023326841421f09@stranger",
      "v2": "v4_000b708f0b04000001000000005c9bdbbd15000000050ded0b020927e3c97896a09d47e6e9e123bccee7113c1059f23719f0475e252e23a8974c9afd6f9040bbe75e494a97eac07500433c50f03501dd3e3e712843a093e453545c1c6c01360a188478298f3f180134ac7d91d47c9@stranger"
    }
  ]
}

错误响应

{
  "message": "失败",
  "code": "1001",
  "data": null
}

使用建议

• phoneMD5 可用于和业务侧手机号哈希结果做匹配，不建议在前端展示原始手机号。
• 添加好友时优先使用接口返回的 v1、v2 等凭证字段，不要只依赖昵称。
• 通讯录数据涉及个人信息，建议按最小权限开放查询能力。