微信企業號開發之如何管理通訊錄
企業號通訊錄具備完全開放的接口，你的應用可以調用這些接口管理部門、成員和標簽。
你的應用也可以使用部門、成員、標簽發消息，或更改應用的可見范圍。
注意，每個部門的直屬員工上限為1000個；出于安全考慮，某些接口需要在管理端有明確的授權。
一、管理部門
1、創建部門
- 請求說明
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/department/create?access_token=ACCESS_TOKEN
請求包結構體為:
- {
- "name": "郵箱產品組",
- "parentid": "1"
- }
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| name | 是 | 部門名稱。長度限制為1~64個字符 |
| parentid | 是 | 父親部門id。根部門id為1 |
- 權限說明
管理員須擁有“操作通訊錄”的接口權限，以及父部門的管理權限。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "created",
- "id": 2
- }
| 參數 | 說明 |
|---|---|
| errcode | 返回碼 |
| errmsg | 對返回碼的文本描述內容 |
| id | 創建的部門id。 |
2、更新部門
- 請求說明
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/department/update?access_token=ACCESS_TOKEN
請求包結構體為（如果非必須的字段未指定，則不更新該字段之前的設置值）:
- {
- "id": 2,
- "name": "郵箱產品部"
- }
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| id | 是 | 部門id。 |
| name | 否 | 更新的部門名稱。長度限制為0~64個字符。修改部門名稱時指定該參數 |
- 權限說明
管理員須擁有“操作通訊錄”的接口權限，以及該部門的管理權限。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "updated"
- }
3、刪除部門
- 請求說明
Https請求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/department/delete?access_token=ACCESS_TOKEN&id=1&id=2
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| id | 是 | 部門id。（注：不能刪除根部門；不能刪除含有子部門、成員的部門） |
- 權限說明
管理員須擁有“操作通訊錄”的接口權限，以及該部門的管理權限。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "deleted"
- }
4、獲取部門列表
- 請求說明
Https請求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/department/list?access_token=ACCESS_TOKEN
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
- 權限說明
管理員須擁有’獲取部門列表’的接口權限，以及對部門的查看權限。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "ok",
- "department": [
- {
- "id": 1,
- "name": "廣州研發中心",
- "parentid": 0
- },
- {
- "id": 2
- "name": "郵箱產品部",
- "parentid": 1
- }
- ]
- }
| 參數 | 說明 |
|---|---|
| errcode | 返回碼 |
| errmsg | 對返回碼的文本描述內容 |
| department | 部門列表數據 |
| id | 部門id |
| name | 部門名稱 |
| parentid | 父親部門id。根部門為1 |
#p#
二、管理成員
1、創建成員
- 請求說明
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/user/create?access_token=ACCESS_TOKEN
請求包結構體為:
- {
- "userid": "zhangsan",
- "name": "張三",
- "department": [1, 2],
- "position": "產品經理",
- "mobile": "15913215421",
- "gender": 1,
- "tel": "62394",
- "email": "zhangsan@gzdev.com",
- "weixinid": "zhangsan4dev"
- }
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| userid | 是 | 員工UserID。對應管理端的帳號，企業內必須唯一 |
| name | 是 | 成員名稱。長度為1~64個字符 |
| department | 否 | 成員所屬部門id列表。注意，每個部門的直屬員工上限為1000個 |
| position | 否 | 職位信息。長度為0~64個字符 |
| mobile | 否 | 手機號碼。企業內必須唯一，mobile/weixinid/email三者不能同時為空 |
| gender | 否 | 性別。gender=0表示男，=1表示女。默認gender=0 |
| tel | 否 | 辦公電話。長度為0~64個字符 |
| 否 | 郵箱。長度為0~64個字符。企業內必須唯一 | |
| weixinid | 否 | 微信號。企業內必須唯一 |
- 權限說明
管理員須擁有“操作通訊錄”的接口權限，以及指定部門的管理權限。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "created"
- }
2、更新成員
- 請求說明
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/user/update?access_token=ACCESS_TOKEN
請求包示例如下（如果非必須的字段未指定，則不更新該字段之前的設置值）:
- {
- "userid": "zhangsan",
- "name": "李四",
- "department": [1],
- "position": "后臺工程師",
- "mobile": "15913215421",
- "gender": 1,
- "tel": "62394",
- "email": "zhangsan@gzdev.com",
- "weixinid": "lisifordev",
- "enable": 1
- }
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| userid | 是 | 員工UserID。對應管理端的帳號，企業內必須唯一 |
| name | 否 | 成員名稱。長度為0~64個字符 |
| department | 否 | 成員所屬部門id列表。注意，每個部門的直屬員工上限為1000個 |
| position | 否 | 職位信息。長度為0~64個字符 |
| mobile | 否 | 手機號碼。企業內必須唯一，更新后的成員mobile/weixinid/email三者不能同時為空 |
| gender | 否 | 性別。gender=0表示男，=1表示女。默認gender=0 |
| tel | 否 | 辦公電話。長度為0~64個字符。必須企業內唯一 |
| 否 | 郵箱。長度為0~64個字符。企業內必須唯一 | |
| weixinid | 否 | 微信號。企業內必須唯一 |
| enable | 否 | 啟用/禁用成員。1表示啟用成員，0表示禁用成員 |
- 權限說明
管理員須擁有“操作通訊錄”的接口權限，以及指定部門、成員的管理權限。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "updated"
- }
3、刪除成員
- 請求說明
Https請求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/user/delete?access_token=ACCESS_TOKEN&userid=lisi
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| userid | 是 | 員工UserID。對應管理端的帳號 |
- 權限說明
管理員須擁有“操作通訊錄”的接口權限，以及指定部門、成員的管理權限。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "deleted"
- }
4、獲取成員
- 請求說明
Https請求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&userid=lisi
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| userid | 是 | 員工UserID |
- 返回結果
- {
- "errcode": 0,
- "errmsg": "ok",
- "userid": "zhangsan",
- "name": "李四",
- "department": [1, 2],
- "position": "后臺工程師",
- "mobile": "15913215421",
- "gender": 1,
- "tel": "62394",
- "email": "zhangsan@gzdev.com",
- "weixinid": "lisifordev",
- "avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0",
- "status": 1
- }
| 參數 | 說明 |
|---|---|
| errcode | 返回碼 |
| errmsg | 對返回碼的文本描述內容 |
| userid | 員工UserID |
| name | 成員名稱 |
| department | 成員所屬部門id列表 |
| position | 職位信息 |
| mobile | 手機號碼 |
| gender | 性別。gender=0表示男，=1表示女 |
| tel | 辦公電話 |
| 郵箱 | |
| weixinid | 微信號 |
| avatar | 頭像url。注：如果要獲取小圖將url***的"/0"改成"/64"即可 |
| status | 關注狀態: 1=已關注，2=已凍結，4=未關注 |
- 權限說明
管理員須擁有’獲取成員’的接口權限，以及成員的查看權限。
5、獲取部門成員
- 請求說明
Https請求方式: GET
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| department_id | 是 | 獲取的部門id |
| fetch_child | 否 | 1/0：是否遞歸獲取子部門下面的成員 |
| status | 否 | 0獲取全部員工，1獲取已關注成員列表，2獲取禁用成員列表，4獲取未關注成員列表。status可疊加 |
- 權限說明
管理員須擁有’獲取部門成員’的接口權限，以及指定部門的查看權限。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "ok",
- "userlist": [
- {
- "userid": "zhangsan",
- "name": "李四"
- }
- ]
- }
| 參數 | 說明 |
|---|---|
| errcode | 返回碼 |
| errmsg | 對返回碼的文本描述內容 |
| userlist | 成員列表 |
| userid | 員工UserID |
| name | 成員名稱 |
#p#
三、管理標簽
1、創建標簽
- 請求說明
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/tag/create?access_token=ACCESS_TOKEN
注：標簽鎖默認為未加鎖狀態
請求包結構體為:
- {
- "tagname": "UI"
- }
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| tagname | 是 | 標簽名稱。長度為1~64個字符，標簽不可與其他同組的標簽重名，也不可與全局標簽重名 |
- 權限說明
無限定。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "created"
- "tagid": "1"
- }
2、更新標簽名字
- 請求說明
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/tag/update?access_token=ACCESS_TOKEN
請求包示例如下:
- {
- "tagid": "1",
- "tagname": "UI design"
- }
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| tagid | 是 | 標簽ID |
| tagname | 是 | 標簽名稱。最長64個字符 |
- 權限說明
管理員必須是指定標簽的創建者。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "updated"
- }
3、刪除標簽
- 請求說明
Https請求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/tag/delete?access_token=ACCESS_TOKEN&tagid=1
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| tagid | 是 | 標簽ID |
- 權限說明
管理員必須是指定標簽的創建者，并且標簽的成員列表為空。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "deleted"
- }
4、獲取標簽成員
- 請求說明
Https請求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/tag/get?access_token=ACCESS_TOKEN&tagid=1
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| tagid | 是 | 標簽ID |
- 權限說明
管理員須擁有“獲取標簽成員”的接口權限，標簽須對管理員可見；返回列表僅包含管理員管轄范圍的成員。
- 返回結果
- {
- "errcode": 0,
- "errmsg": "ok",
- "userlist": [
- {
- "userid": "zhangsan",
- "name": "李四"
- }
- ]
- }
| 參數 | 說明 |
|---|---|
| errcode | 錯誤碼 |
| errmsg | 錯誤消息 |
| userlist | 成員列表 |
| userid | 員工UserID |
5、增加標簽成員
- 請求說明
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/tag/addtagusers?access_token=ACCESS_TOKEN
請求包示例如下:
- {
- "tagid": "1",
- "userlist":[ "user1","user2"]
- }
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| tagid | 是 | 標簽ID |
| userlist | 是 | 企業員工ID列表 |
- 權限說明
標簽對管理員可見且未加鎖，成員屬于管理員管轄范圍。
- 返回結果
a)正確時返回
- {
- "errcode": 0,
- "errmsg": "ok"
- }
b)若部分userid非法，則返回
- {
- "errcode": 0,
- "errmsg": "invalid userlist failed"
- "invalidlist"："usr1|usr2|usr"
- }
c)當包含userid全部非法時返回
- {
- "errcode": 40070,
- "errmsg": "all list invalid "
- }
| 參數 | 說明 |
|---|---|
| errcode | 錯誤碼 |
| errmsg | 錯誤消息 |
| invalidlist | 不在權限內的員工ID列表，以“|”分隔 |
6、刪除標簽成員
- 請求說明
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/tag/deltagusers?access_token=ACCESS_TOKEN
請求包如下
- {
- "tagid": "1",
- "userlist":[ "user1","user2"]
- }
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| tagid | 是 | 標簽ID |
| userlist | 是 | 企業員工ID列表 |
- 權限說明
標簽對管理員可見且未加鎖，成員屬于管理員管轄范圍。
- 返回結果
a)正確時返回
- {
- "errcode": 0,
- "errmsg": "deleted"
- }
b)若部分userid非法，則返回
- {
- "errcode": 0,
- "errmsg": "invalid userlist failed"
- "invalidlist"："usr1|usr2|usr"
- }
c)當包含的userid全部非法時返回
- {
- "errcode": 40031,
- "errmsg": "all list invalid"
- }
| 參數 | 說明 |
|---|---|
| errcode | 錯誤碼 |
| errmsg | 錯誤消息 |
| invalidlist | 不在權限內的或者非法的員工ID列表，以“|”分隔 |
