wechatapi，微信二次开发-连载篇（二）通讯录模块默认模块 wechatapi.net Base URLs: we

默认模块 wechatapi.net

Base URLs: wechatapi.net

Authentication

开发API/联系人相关接口

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

POST /contacts/fetchContactsList

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

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

Body 请求参数

{
  "appId": ""
}

请求参数

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

返回示例

200 Response

{
  "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 请求参数

{
  "appId": ""
}

请求参数

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

返回示例

200 Response

{
  "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 请求参数

{
  "appId": "",
  "contactsInfo": "videosapi"
}

请求参数

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

返回示例

{
  "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"
  }
}

{
  "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 请求参数

{
  "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

{
  "ret": 200,
  "msg": "操作成功"
}

返回结果

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

返回数据结构

状态码 200

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

POST 删除好友

POST /contacts/deleteFriend

Body 请求参数

{
  "appId": "",
  "wxid": "wxid_***********"
}

请求参数

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

返回示例

200 Response

{
  "ret": 200,
  "msg": "操作成功"
}

返回结果

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

返回数据结构

状态码 200

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

POST 获取群/好友简要信息

POST /contacts/getBriefInfo

Body 请求参数

"//单个好友/群\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

{
  "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 请求参数

"//单个好友/群\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

{
  "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 请求参数

{
  "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

{
  "ret": 200,
  "msg": "设置好友权限成功"
}

返回结果

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

返回数据结构

状态码 200

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

POST 检测好友关系

POST /contacts/checkRelation

Body 请求参数

"//单个好友\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

{
  "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 请求参数

{
  "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

{
  "ret": 200,
  "msg": "设置好友权限成功"
}

返回结果

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

返回数据结构

状态码 200

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

POST 获取手机通讯录

POST /contacts/getPhoneAddressList

Body 请求参数

{
  "appId": "{{appid}}",
  "phones": []
}

请求参数

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

返回示例

200 Response

{
  "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 请求参数

{
  "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

{
  "ret": 200,
  "msg": "操作成功"
}

返回结果

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

返回数据结构

状态码 200

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

POST 同步企微好友

POST /im/sync

Body 请求参数

{
  "appId": "{{appid}}"
}

请求参数

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

返回示例

200 Response

{
  "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 请求参数

{
  "appId": "{{appid}}",
  "toUserName": "259962145****456301@openim"
}

请求参数

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

返回示例

200 Response

{
  "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	企业名称全拼

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

默认模块 wechatapi.net

Authentication

开发API/联系人相关接口

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

请求参数

返回结果

返回数据结构

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

请求参数

返回结果

返回数据结构

POST 搜索好友

请求参数

返回结果

返回数据结构

POST 添加好友/同意好友

请求参数

详细说明

返回结果

返回数据结构

POST 删除好友

请求参数

返回结果

返回数据结构

POST 获取群/好友简要信息

请求参数

返回结果

返回数据结构

POST 获取群/好友详细信息

请求参数

返回结果

返回数据结构

POST 设置好友仅聊天

请求参数

返回结果

返回数据结构

POST 检测好友关系

请求参数

返回结果

返回数据结构

POST 设置好友备注

请求参数

返回结果

返回数据结构

POST 获取手机通讯录

请求参数

返回结果

返回数据结构

POST 上传手机通讯录

请求参数

返回结果

返回数据结构

POST 同步企微好友

请求参数

返回结果

返回数据结构

POST 获取企微好友详情

请求参数

返回结果

返回数据结构

数据模型