wechatapi，微信二次开发-连载篇（二）通讯录模块

找不到对象就NEW一个2025-11-28 9:43

默认模块 wechatapi.net

Base URLs:wechatapi.net

Authentication

开发API/联系人相关接口

POST 获取通讯录列表(包含群聊)

POST /contacts/fetchContactsList

本接口为长耗时接口，耗时时间根据好友数量递增，若接口超时可通过获取通讯录列表缓存接口获取响应结果

注意：本接口返回的群聊仅为保存到通讯录中的群聊 此接口未返回的群聊，当有人在群内发言时，会有回调消息推送到对应的appid，拿到群id后可通过获取群信息接口拿到此群的信息做后续处理

Body 请求参数

json 复制代码 
{
  "appId": ""
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID

返回示例
200 Response

json 复制代码 
{
  "ret": 0,
  "msg": "string",
  "data": {
    "friends": [
      "string"
    ],
    "chatrooms": [
      "string"
    ],
    "ghs": [
      "string"
    ]
  }
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none
>> data object true none none
>>>> friends [string] true none 好友的wxid
>>>> chatrooms [string] true none 保存到通讯录中群聊的ID
>>>> ghs [string] true none 关注的公众号ID

POST 获取通讯录列表(包含群聊)缓存

POST /contacts/fetchContactsListCache

通讯录列表数据缓存10分钟，超时则需要重新调用获取通讯录列表接口

Body 请求参数

json 复制代码 
{
  "appId": ""
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID

返回示例
200 Response

json 复制代码 
{
  "ret": 0,
  "msg": "string"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none

POST 搜索好友

POST /contacts/search

搜索的联系人信息若已经是好友，响应结果的v3则为好友的wxid 本接口返回的数据可通过添加联系人接口发送添加好友请求

Body 请求参数

json 复制代码 
{
  "appId": "",
  "contactsInfo": "videosapi"
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> contactsInfo body string 是 搜索的联系人信息，微信号、手机号...

返回示例

json 复制代码 
{
  "ret": 200,
  "msg": "操作成功",
  "data": {
    "v3": "v3_020b3826fd0***********8b03@stranger",
    "nickName": "苏生-服务支持",
    "sex": 0,
    "signature": null,
    "bigHeadImgUrl": "http://wx.qlogo.cn/mmhead/ver_1/aFOVDS8d8s8CqSkv84ZzMdlvFzQ5TdTtibNqK5ibdUU1ibg55E71dCq5XXJWTS2Cb0AGicqxk0Ik9ibjk5Hep86njl3uzTxZe9A9puiaaB0DH1toFfDWdJs4ibDqd6rKh8GKnWfThSITqggGxpbiaajdibibibr0Q/0",
    "smallHeadImgUrl": "http://wx.qlogo.cn/mmhead/ver_1/aFOVDS8d8s8CqSkv84ZzMdlvFzQ5TdTtibNqK5ibdUU1ibg55E71dCq5XXJWTS2Cb0AGicqxk0Ik9ibjk5Hep86njl3uzTxZe9A9puiaaB0DH1toFfDWdJs4ibDqd6rKh8GKnWfThSITqggGxpbiaajdibibibr0Q/132",
    "v4": "v4_000b708f0b040000010******************@stranger"
  }
}
json 复制代码 
{
  "ret": 500,
  "msg": "搜索联系人失败",
  "data": {
    "code": "-4",
    "msg": "用户不存在"
  }
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none
>> data object true none none
>>>> v3 string true none 搜索好友的v3，添加好友时使用
>>>> nickName string true none 搜索好友的昵称
>>>> sex integer true none 搜索好友的性别
>>>> signature null true none 搜索好友的签名
>>>> bigHeadImgUrl string true none 搜索好友的大尺寸头像
>>>> smallHeadImgUrl string true none 搜索好友的小尺寸头像
>>>> v4 string true none 搜索好友的v4，添加好友时使用

POST 添加好友/同意好友

POST /contacts/addContacts

本接口建议在线3天后再进行调用。 好友添加成功后，会通过回调消息推送一条包含v3的消息，可用于判断好友是否添加成功。

Body 请求参数

json 复制代码 
{
  "appId": "",
  "scene": 3,
  "content": "hallo",
  "v4": "v4_000b708f0b04000001000000000054a9e826***********96a09d47e6e9e456cef2d2bd4a3cef771c8661331fa1939fbe54f4e479d6d9d4522d70aeba057ffd0dd82398730da44ee57332a7bdea4862304d4799758ba@stranger",
  "v3": "v3_020b3826fd030100000000003a070**********a0536a1adb690dcccc9bf58cc80765e6eb16bffa5996420bb1b2577634516ff82090419d8bdcd5689df8dfb21d40af93d286f72c3a0e8cfa6dcb68afed39226f008c6@stranger",
  "option": 2
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> scene body integer 是 添加来源，同意添加好友时传回调消息xml中的scene值。
>> option body integer 是 操作类型，2添加好友 3同意好友 4拒绝好友
>> v3 body string 是 通过搜索或回调消息获取到的v3
>> v4 body string 是 通过搜索或回调消息获取到的v4
>> content body string 是 添加好友时的招呼语
详细说明

>> scene: 添加来源，同意添加好友时传回调消息xml中的scene值。 添加好友时的枚举值如下： 3 ：微信号搜索 4 ：QQ好友 8 ：来自群聊 15：手机号

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "操作成功"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none

POST 删除好友

POST /contacts/deleteFriend

Body 请求参数

json 复制代码 
{
  "appId": "",
  "wxid": "wxid_***********"
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> wxid body string 是 删除好友的wxid

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "操作成功"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none

POST 获取群/好友简要信息

POST /contacts/getBriefInfo

Body 请求参数

json 复制代码 
"//单个好友/群\n{\n    \"appId\": \"{{appid}}\",\n    \"wxids\": [\n        \"wechatapi\"\n    ]\n}\n//多个好友/群\n{\n    \"appId\": \"{{appid}}\",\n    \"wxids\": [\n        \"ier****isi\",\n        \"kit****622\",\n        \"F10****0104\",\n        \"leo****001\",\n        \"kel****0428\",\n        \"wxi****612\",\n        \"wxi****522\"\n    ]\n}"

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> wxids body [string] 是 好友/群的wxid

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "获取联系人信息成功",
  "data": [
    {
      "userName": "wxid_************",
      "nickName": "videosapi",
      "pyInitial": "videosapi",
      "quanPin": "videosapi",
      "sex": 2,
      "remark": "",
      "remarkPyInitial": "",
      "remarkQuanPin": "",
      "signature": null,
      "alias": "zero-one_200906",
      "snsBgImg": null,
      "country": "AD",
      "bigHeadImgUrl": "https://wx.qlogo.cn/mmhead/ver_1/buiaXybHTBK3BuGr1edN72zBDermWVFJ7YC8Jib2RcCSdiauAtZcPgUQpdhE9KY5NsumDAWD16fsg3A6OKuhdEr97VAHdTGgk6R1Eibuj7ZNwJ4/0",
      "smallHeadImgUrl": "https://wx.qlogo.cn/mmhead/ver_1/buiaXybHTBK3BuGr1edN72zBDermWVFJ7YC8Jib2RcCSdiauAtZcPgUQpdhE9KY5NsumDAWD16fsg3A6OKuhdEr97VAHdTGgk6R1Eibuj7ZNwJ4/132",
      "description": null,
      "cardImgUrl": null,
      "labelList": "",
      "province": "",
      "city": "",
      "phoneNumList": null
    }
  ]
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none
>> data [object] true none none
>>>> userName string false none none
>>>> nickName string false none none
>>>> pyInitial string false none none
>>>> quanPin string false none none
>>>> sex integer false none none
>>>> remark string false none none
>>>> remarkPyInitial string false none none
>>>> remarkQuanPin string false none none
>>>> signature null false none none
>>>> alias string false none none
>>>> snsBgImg null false none none
>>>> country string false none none
>>>> bigHeadImgUrl string false none none
>>>> smallHeadImgUrl string false none none
>>>> description null false none none
>>>> cardImgUrl null false none none
>>>> labelList string false none none
>>>> province string false none none
>>>> city string false none none
>>>> phoneNumList null false none none

POST 获取群/好友详细信息

POST /contacts/getDetailInfo

Body 请求参数

json 复制代码 
"//单个好友/群\n{\n    \"appId\": \"{{appid}}\",\n    \"wxids\": [\n        \"wechatapi\"\n    ]\n}\n//多个好友/群\n{\n    \"appId\": \"{{appid}}\",\n    \"wxids\": [\n        \"ier****isi\",\n        \"kit****622\",\n        \"F10****0104\",\n        \"leo****001\",\n        \"kel****0428\",\n        \"wxi****612\",\n        \"wxi****522\"\n    ]\n}"

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> wxids body [string] 是 好友的wxid

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "获取联系人信息成功",
  "data": [
    {
      "userName": "wxid_**********",
      "nickName": "Ashley",
      "pyInitial": null,
      "quanPin": "Ashley",
      "sex": 2,
      "remark": null,
      "remarkPyInitial": null,
      "remarkQuanPin": null,
      "signature": "山林不向四季起誓 枯荣随缘。",
      "alias": "zero-one_200906",
      "snsBgImg": "http://shmmsns.qpic.cn/mmsns/UaAfqYic92wm7ZCrsEwlQMXSmBLs8dpwBzrXnrOyyP3B8bDibCCFInJ9PicC9LPYY17uWH1yIOmBYQ/0",
      "country": "AD",
      "bigHeadImgUrl": "https://wx.qlogo.cn/mmhead/ver_1/buiaXybHTBK3BuGr1edN72zBDermWVFJ7YC8Jib2RcCSdiauAtZcPgUQpdhE9KY5NsumDAWD16fsg3A6OKuhdEr97VAHdTGgk6R1Eibuj7ZNwJ4/0",
      "smallHeadImgUrl": "https://wx.qlogo.cn/mmhead/ver_1/buiaXybHTBK3BuGr1edN72zBDermWVFJ7YC8Jib2RcCSdiauAtZcPgUQpdhE9KY5NsumDAWD16fsg3A6OKuhdEr97VAHdTGgk6R1Eibuj7ZNwJ4/132",
      "description": null,
      "cardImgUrl": null,
      "labelList": null,
      "province": null,
      "city": null,
      "phoneNumList": null
    }
  ]
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none
>> data [object] true none none
>>>> userName string false none 好友的wxid
>>>> nickName string false none 好友的昵称
>>>> pyInitial null false none 好友昵称的拼音首字母
>>>> quanPin string false none 好友昵称的全拼
>>>> sex integer false none 好友的性别
>>>> remark null false none 好友备注
>>>> remarkPyInitial null false none 好友备注的拼音首字母
>>>> remarkQuanPin null false none 好友备注的全拼
>>>> signature string false none 好友的签名
>>>> alias string false none 好友的微信号
>>>> snsBgImg string false none 朋友圈背景图链接
>>>> country string false none 国家
>>>> bigHeadImgUrl string false none 大尺寸头像链接
>>>> smallHeadImgUrl string false none 小尺寸头像链接
>>>> description null false none 好友的描述
>>>> cardImgUrl null false none 好友描述的图片链接
>>>> labelList null false none 好友的标签ID
>>>> province null false none 省份
>>>> city null false none 城市
>>>> phoneNumList null false none 好友的手机号码

POST 设置好友仅聊天

POST /contacts/setFriendPermissions

设置完好友仅聊天后若发现手机展示不是设置的结果，可能是手机缓存未刷新，重新进入页面刷新查看

Body 请求参数

json 复制代码 
{
  "appId": "{{appid}}",
  "wxid": "wxid_**********",
  "onlyChat": true
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> wxid body string 是 好友的wxid
>> onlyChat body boolean 是 设置好友是否仅聊天

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "设置好友权限成功"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none

POST 检测好友关系

POST /contacts/checkRelation

Body 请求参数

json 复制代码 
"//单个好友\n{\n    \"appId\": \"{{appid}}\",\n    \"wxids\": [\n        \"wechatapi\"\n    ]\n}\n//多个好友\n{\n    \"appId\": \"{{appid}}\",\n    \"wxids\": [\n        \"ier****isi\",\n        \"kit****622\",\n        \"F10****0104\",\n        \"leo****001\",\n        \"kel****0428\",\n        \"wxi****612\",\n        \"wxi****522\"\n    ]\n}"

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> wxids body [string] 是 好友的wxid

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "检测好友关系成功",
  "data": [
    {
      "wxid": "wxid_adfwh232asd",
      "relation": 1
    },
    {
      "wxid": "wxid_adfgsfghe2322",
      "relation": 2
    },
    {
      "wxid": "wxid_adfgsfgfnytj2",
      "relation": 0
    }
  ]
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none
>> data [object] true none none
>>>> wxid string true none 好友的wxid
>>>> relation integer true none 0:正常 1:删除 2:被拉黑3:已拉黑对方4:功能异常5:检测频繁6:未知状态7:未知错误99:其他

POST 设置好友备注

POST /contacts/setFriendRemark

Body 请求参数

json 复制代码 
{
  "appId": "{{appid}}",
  "wxid": "wxid_**********",
  "remark": "备注"
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> wxid body string 是 好友的wxid
>> remark body string 是 备注的备注

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "设置好友权限成功"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none

POST 获取手机通讯录

POST /contacts/getPhoneAddressList

Body 请求参数

json 复制代码 
{
  "appId": "{{appid}}",
  "phones": []
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> phones body [string] 否 获取哪些手机号的好友详情，不传获取所有

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "获取手机通讯录成功",
  "data": [
    {
      "userName": "wxid_ddgsghdfafaphh22",
      "v4": null,
      "nickName": null,
      "sex": 1,
      "phoneMd5": "d36f4cc1c8bca1ef41b93d2215133cdb",
      "signature": "......",
      "alias": null,
      "country": "CN",
      "bigHeadImgUrl": "http://wx.qlogo.cn/mmhead/ver_1/vwGdLRK5jtpXagA7dfXlUiaU9VayWNSqia1c2Wib7icJNhPd6WHhqMIVuYuNDfEqPRC2TnmlRSkfYrib9fHyYONwdccv17gibCls7ia8elaunvgMmYicAw22wUJQ3CDw0Cm5ibrOT/0",
      "smallHeadImgUrl": "http://wx.qlogo.cn/mmhead/ver_1/vwGdLRK5jtpXagA7dfXlUiaU9VayWNSqia1c2Wib7icJNhPd6WHhqMIVuYuNDfEqPRC2TnmlRSkfYrib9fHyYONwdccv17gibCls7ia8elaunvgMmYicAw22wUJQ3CDw0Cm5ibrOT/132",
      "province": "Jiangsu",
      "city": "Xuzhou",
      "personalCard": 0
    }
  ]
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none
>> data [object] true none none
>>>> userName string false none none
>>>> v4 null false none none
>>>> nickName null false none none
>>>> sex integer false none none
>>>> phoneMd5 string false none none
>>>> signature string false none none
>>>> alias null false none none
>>>> country string false none none
>>>> bigHeadImgUrl string false none none
>>>> smallHeadImgUrl string false none none
>>>> province string false none none
>>>> city string false none none
>>>> personalCard integer false none none

POST 上传手机通讯录

POST /contacts/uploadPhoneAddressList

Body 请求参数

json 复制代码 
{
  "appId": "{{appid}}",
  "phones": [
    "18888888888",
    "19999999999"
  ],
  "opType": 1
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> phones body [string] 是 需要上传的手机号
>> opType body integer 是 操作类型，1:上传 2:删除

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "操作成功"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none

POST 同步企微好友

POST /im/sync

Body 请求参数

json 复制代码 
{
  "appId": "{{appid}}"
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "操作成功",
  "data": [
    {
      "userName": "259**nim",
      "nickName": "**",
      "remark": "",
      "bigHeadImg": "http://wew**qpoCghewE/",
      "smallHeadImg": "http://**sapevHrU/",
      "appId": "23**00",
      "descWordingId": "RwpR**KOP"
    }
  ]
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none
>> data object true none none
>>>> userName string true none 企业微信号
>>>> nickName string true none 企业微信名称
>>>> remark string true none 备注
>>>> bigHeadImg string true none 大头像
>>>> smallHeadImg string true none 小头像
>>>> appId string true none 企业微信APPID
>>>> descWordingId string true none 企业ID

POST 获取企微好友详情

POST /im/detail

Body 请求参数

json 复制代码 
{
  "appId": "{{appid}}",
  "toUserName": "259962145****456301@openim"
}

请求参数

名称 位置 类型 必选 说明
VideosApi-token header string 是 none
body body object 否 none
>> appId body string 是 设备ID
>> toUserName body string 是 企业微信号

返回示例
200 Response

json 复制代码 
{
  "ret": 200,
  "msg": "操作成功",
  "data": {
    "userName": "685992**236",
    "nickName": "******",
    "remark": "",
    "bigHeadImg": "http://wew**qpoCghewE/",
    "smallHeadImg": "http://**sapevHrU/",
    "appId": "56****635",
    "descWordingId": "EDFYH9F68S8**aewax",
    "wording": "******",
    "wordingPinyin": "******",
    "wordingQuanpin": "******"
  }
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK none Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
>> ret integer true none none
>> msg string true none none
>> data object true none none
>>>> userName string true none 企业微信号
>>>> nickName string true none 企业微信昵称
>>>> remark string true none 备注
>>>> bigHeadImg string true none 大头像
>>>> smallHeadImg string true none 小头像
>>>> appId string true none 企业微信APPID
>>>> descWordingId string true none 企业ID
>>>> wording string true none 企业全称
>>>> wordingPinyin string true none 企业全称拼音
>>>> wordingQuanpin string true none 企业名称全拼

数据模型

相关推荐
苏三的开发日记37 分钟前
grafana里面怎么添加Prometheus数据源监控MySQL
后端
Y***98511 小时前
【学术会议论文投稿】Spring Boot实战：零基础打造你的Web应用新纪元
前端·spring boot·后端
q***33371 小时前
SpringMVC新版本踩坑[已解决]
android·前端·后端
武子康1 小时前
大数据-166 Apache Kylin 1.6 Streaming Cubing 实战：Kafka 到分钟级 OLAP
大数据·后端·apache kylin
回家路上绕了弯1 小时前
彻底解决超卖问题：从单体到分布式的全场景技术方案
分布式·后端
8***29312 小时前
能懂！基于Springboot的用户增删查改（三层设计模式）
spring boot·后端·设计模式
IT_陈寒2 小时前
Python高手都在用的5个隐藏技巧，让你的代码效率提升50%
前端·人工智能·后端
FeiHuo565152 小时前
微信个人号开发中如何高效实现API二次开发
java·开发语言·python·微信
Qiuner2 小时前
Spring Boot 机制二：配置属性绑定 Binder 源码解析（ConfigurationProperties 全链路）
java·spring boot·后端·spring·binder
热门推荐
01GitHub 镜像站点02【保姆级教程】免费使用Gemini3的5种方法！免翻墙/国内直连03BongoCat - 跨平台键盘猫动画工具04UV安装并设置国内源05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06Linux下V2Ray安装配置指南07Google Antigravity：无法登录？早期错误、登录修复和用户反馈指南08Labelme从安装到标注：零基础完整指南09全球最强模型Grok4，国内已可免费使用！（附教程）1046个Nano-banana 精选提示词，持续更新中