获取联系人详情（完整版）

批量获取好友或群聊的完整资料。相比基础版联系人详情，本接口会返回 v3 字段，适合在好友通过后确认好友关系，并补全头像、地区、标签、拼音等更完整的联系人信息。

接口地址： POST /getContactPlus

前置条件

• 微信实例已登录，并已获得可用的 wId。
• 已知道目标好友 wcId 或群聊 ID。
• 参数与 获取联系人详情 一致。
• 好友通过后，如需判断是否已经成为好友，建议调用本接口获取 v3。

请求参数

参数名	必选	类型	说明
wId	是	string	登录实例标识
wcId	是	string	好友微信 ID 或群 ID；多个用英文逗号分隔，单次最多 20 个

响应参数

参数名	类型	说明
code	string	1000 成功，1001 失败
message	string	反馈信息
data	array	联系人信息列表
data[].userName	string	微信原始 ID
data[].nickName	string	昵称
data[].remark	string/null	备注名
data[].signature	string/null	个性签名
data[].sex	int	性别：1 男、2 女、0 未知
data[].aliasName	string/null	微信号，用户设置后返回
data[].country	string/null	国家编码
data[].province	string/null	省份
data[].city	string/null	城市
data[].bigHead	string/null	大头像 URL
data[].smallHead	string/null	小头像 URL
data[].labelList	string/null	标签 ID 列表
data[].v1	string/null	加好友凭证或联系人标识
data[].v3	string/null	好友关系确认凭证；好友通过后可用来判断是否已成为好友
data[].desc	string/null	描述信息
data[].cardImgUrl	string/null	名片图片 URL
data[].pyInitial	string/null	昵称拼音首字母
data[].remarkPyInitial	string/null	备注拼音首字母
data[].phoneNumList	array	手机号列表

请求示例

{
  "wId": "349be9b5-8734-45ce-811d-4e10ca568c67",
  "wcId": "wxid_r5ycs8ocuz8h22"
}

成功响应

{
  "code": "1000",
  "message": "获取联系人信息成功",
  "data": [
    {
      "userName": "wxid_r5ycs8ocuz8h22",
      "nickName": "程序猿",
      "remark": null,
      "signature": null,
      "sex": 0,
      "aliasName": "bubaishenha",
      "country": "CN",
      "bigHead": "https://wx.qlogo.cn/mmhead/ver_1/JnnAv1QlF5WqhGdTib6CbH09niamLp1B4NWiar01icwJglRkEibpNzmsNOys56syZ2Xs6B3SpgFAV8TuxSzOnHH56YdNVWtDZMTLmcHJY5fFB46sDd2k32XoFrBwo6e35iaw4c/0",
      "smallHead": "https://wx.qlogo.cn/mmhead/ver_1/JnnAv1QlF5WqhGdTib6CbH09niamLp1B4NWiar01icwJglRkEibpNzmsNOys56syZ2Xs6B3SpgFAV8TuxSzOnHH56YdNVWtDZMTLmcHJY5fFB46sDd2k32XoFrBwo6e35iaw4c/132",
      "labelList": null,
      "v1": "wxid_r5ycs8ocuz8h22",
      "province": "Guangdong",
      "city": "Dongguan",
      "v3": "v3_020b3826fd03010000000000f69403f5c228ee000000501ea9a3dba12f95f6b60a0536a1adb6a211e59d39105c28ae26309d370bbb648b53cbdf9adbf5fef66aebba598c0a776711eab023c7f804b27b34168ae5e14c405ab4a70116849c51e1ae6db0@stranger",
      "desc": null,
      "cardImgUrl": null,
      "pyInitial": "CXY",
      "remarkPyInitial": null,
      "phoneNumList": []
    }
  ]
}

错误响应

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

使用建议

• 好友通过后，优先调用本接口获取 v3，再把好友状态更新为“已通过”。
• v3 为空或未返回时，不要只凭昵称、头像判断好友已通过，建议稍后重试或结合回调确认。
• 批量查询时，每次调用间隔建议 300ms-800ms，避免请求过于频繁。
• 业务系统应保存 userName、aliasName、v1、v3 等稳定字段，展示字段如昵称、头像、地区可按需更新。