Merge #65

65: feat: add BatchExternalContact r=xen0n a=w3xse7en

 BatchExternalContact doc: https://work.weixin.qq.com/api/doc/90000/90135/92994

Co-authored-by: w3xse7en <w3xse7en@outlook.com>

Author: bors[bot]

README.md

@@ -60,7 +60,7 @@ in at least 2 of Qiniu's internal systems.
 ## Supported APIs
 
 * [x] 通讯录管理 (**部分支持**，见下)
-* [ ] 外部联系人管理
+* [ ] 客户联系
 * [ ] 应用管理
 * [x] 消息发送 (除修改群聊会话外全部支持)
 * [x] 消息接收 (**接口尚不稳定，极有可能做出不兼容改动，先不要用**)
@@ -110,12 +110,13 @@ in at least 2 of Qiniu's internal systems.
 </details>
 
 <details>
-<summary>外部联系人管理 API</summary>
+<summary>客户联系 API</summary>
 
 * [x] 成员对外信息
 * [x] 客户管理
     - [x] 获取客户列表
     - [x] 获取客户详情
+    - [x] 批量获取客户详情
     - [x] 修改客户备注信息
 * [x] 客户标签管理
    - [x] 管理企业标签

apis.md.go

@@ -75,6 +75,7 @@ Name|Request Type|Response Type|Access Token|URL|Doc
 :---|------------|-------------|------------|:--|:--
 `execExternalContactList`|`reqExternalContactList`|`respExternalContactList`|+|`GET /cgi-bin/externalcontact/list`|[获取客户列表](https://work.weixin.qq.com/api/doc/90000/90135/92113)
 `execExternalContactGet`|`reqExternalContactGet`|`respExternalContactGet`|+|`GET /cgi-bin/externalcontact/get`|[获取客户详情](https://work.weixin.qq.com/api/doc/90000/90135/92114)
+`execExternalContactBatchList`|`reqExternalContactBatchList`|`respExternalContactBatchList`|+|`POST /cgi-bin/externalcontact/batch/get_by_user`|[批量获取客户详情](https://work.weixin.qq.com/api/doc/90000/90135/92994)
 `execExternalContactRemark`|`reqExternalContactRemark`|`respExternalContactRemark`|+|`POST /cgi-bin/externalcontact/remark`|[修改客户备注信息](https://work.weixin.qq.com/api/doc/90000/90135/92115)
 
 # 外部联系人管理 - 客户标签管理

docs/apis.md

@@ -74,14 +74,28 @@ const (
 
 Name|JSON|Type|Doc
 :---|:---|:---|:--
-`Userid`|`userid`|`string`| 外部联系人的userid
+``|``|`FollowUserInfo`| 添加了外部联系人的企业成员
+`Tags`|`tags`|`[]FollowUserTag`| 该成员添加此外部联系人所打标签
+
+### `FollowInfo` 企业成员客户跟进信息，可以参考获取客户详情，但标签信息只会返回企业标签的tag_id，个人标签将不再返回
+
+Name|JSON|Type|Doc
+:---|:---|:---|:--
+``|``|`FollowUserInfo`| 添加了外部联系人的企业成员
+`TagID`|`tag_id`|`[]string`| 该成员添加此外部联系人所打标签
+
+### `FollowUserInfo` 添加了外部联系人的企业成员
+
+Name|JSON|Type|Doc
+:---|:---|:---|:--
+`UserID`|`userid`|`string`| 外部联系人的userid
 `Remark`|`remark`|`string`| 该成员对此外部联系人的备注
 `Description`|`description`|`string`| 该成员对此外部联系人的描述
 `Createtime`|`createtime`|`int`| 该成员添加此外部联系人的时间
-`Tags`|`tags`|`[]FollowUserTag`| 该成员添加此外部联系人所打标签
 `RemarkCorpName`|`remark_corp_name`|`string`| 该成员对此客户备注的企业名称
 `RemarkMobiles`|`remark_mobiles`|`[]string`| 该成员对此客户备注的手机号码，第三方不可获取
 `AddWay`|`add_way`|`FollowUserAddWay`| 该成员添加此客户的来源
+`OperUserID`|`oper_userid`|`string`| 发起添加的userid，如果成员主动添加，为成员的userid；如果是客户主动添加，则为客户的外部联系人userid；如果是内部成员共享/管理员分配，则为对应的成员/管理员userid
 `State`|`state`|`string`| 企业自定义的state参数，用于区分客户具体是通过哪个「联系我」添加，由企业通过[创建「联系我」方式](https://work.weixin.qq.com/api/doc/90000/90135/92114#15645/%E9%85%8D%E7%BD%AE%E5%AE%A2%E6%88%B7%E8%81%94%E7%B3%BB%E3%80%8C%E8%81%94%E7%B3%BB%E6%88%91%E3%80%8D%E6%96%B9%E5%BC%8F)指定
 
 ### `FollowUserTag` 该成员添加此外部联系人所打标签
@@ -92,7 +106,6 @@ Name|JSON|Type|Doc
 `TagName`|`tag_name`|`string`| 该成员添加此外部联系人所打标签名称
 `Type`|`type`|`FollowUserTagType`| 该成员添加此外部联系人所打标签类型, 1-企业设置, 2-用户自定义
 
-
 ```go
 // FollowUserTagType 该成员添加此外部联系人所打标签类型
 //

docs/external_contact.md

@@ -26,6 +26,19 @@ func (c *WorkwxApp) GetExternalContact(externalUserid string) (*ExternalContactI
 	return &resp.ExternalContactInfo, nil
 }
 
+// BatchListExternalContact 批量获取客户详情
+func (c *WorkwxApp) BatchListExternalContact(userID string, cursor string, limit int) (*BatchListExternalContactsResp, error) {
+	resp, err := c.execExternalContactBatchList(reqExternalContactBatchList{
+		UserID: userID,
+		Cursor: cursor,
+		Limit:  limit,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &BatchListExternalContactsResp{Result: resp.ExternalContactList, NextCursor: resp.NextCursor}, nil
+}
+
 // RemarkExternalContact 修改客户备注信息
 func (c *WorkwxApp) RemarkExternalContact(req *ExternalContactRemark) error {
 	_, err := c.execExternalContactRemark(reqExternalContactRemark{

external_contact.go

@@ -387,11 +387,51 @@ type respExternalContactGet struct {
 	ExternalContactInfo
 }
 
+// ExternalContactInfo 外部联系人信息
 type ExternalContactInfo struct {
 	ExternalContact ExternalContact `json:"external_contact"`
 	FollowUser      []FollowUser    `json:"follow_user"`
 }
 
+// ExternalContactBatchInfo 外部联系人信息
+type ExternalContactBatchInfo struct {
+	ExternalContact ExternalContact `json:"external_contact"`
+	FollowInfo      FollowInfo      `json:"follow_info"`
+}
+
+// BatchListExternalContactsResp 外部联系人信息
+type BatchListExternalContactsResp struct {
+	Result     []ExternalContactBatchInfo
+	NextCursor string
+}
+
+// reqExternalContactBatchList 批量获取客户详情
+type reqExternalContactBatchList struct {
+	UserID string `json:"userid"`
+	Cursor string `json:"cursor"`
+	Limit  int    `json:"limit"`
+}
+
+var _ bodyer = reqExternalContactBatchList{}
+
+func (x reqExternalContactBatchList) intoBody() ([]byte, error) {
+	result, err := json.Marshal(x)
+	if err != nil {
+		// should never happen unless OOM or similar bad things
+		// TODO: error_chain
+		return nil, err
+	}
+
+	return result, nil
+}
+
+// respExternalContactBatchList 批量获取客户详情
+type respExternalContactBatchList struct {
+	respCommon
+	NextCursor          string                     `json:"next_cursor"`
+	ExternalContactList []ExternalContactBatchInfo `json:"external_contact_list"`
+}
+
 // reqExternalContactRemark 获取客户详情
 type reqExternalContactRemark struct {
 	Remark *ExternalContactRemark