增加获客助手部分接口

README.md

@@ -184,6 +184,12 @@ CI 会在 Go 的当前稳定版本、上一个稳定版本上跑测试，只有
   - [ ] 获取企业的全部群发记录
   - [x] 发送新客户欢迎语
   - [ ] 入群欢迎语素材管理
+* [x] 获客助手
+    - [x] 获取获客链接列表
+    - [x] 获取获客链接详情
+    - [x] 创建获客链接
+    - [ ] 编辑获客链接
+    - [x] 获取获客客户列表
 
 </details>
 

docs/apis.md

@@ -83,6 +83,18 @@ Name|Request Type|Response Type|Access Token|URL|Doc
 `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)
 
+# 外部联系人管理 - 获客助手
+
+## API calls
+
+Name| Request Type                                    | Response Type                                    |Access Token| URL                                                            |Doc
+:---|-------------------------------------------------|--------------------------------------------------|------------|:---------------------------------------------------------------|:--
+`execExternalContactCustomerAcquisitionLinkList`| `reqExternalContactCustomerAcquisitionLinkList` | `respExternalContactCustomerAcquisitionLinkList` |+| `POST /cgi-bin/externalcontact/customer_acquisition/list_link` |[获取获客链接列表](https://developer.work.weixin.qq.com/document/path/97394#%E8%8E%B7%E5%8F%96%E8%8E%B7%E5%AE%A2%E9%93%BE%E6%8E%A5%E5%88%97%E8%A1%A8)
+`execExternalContactCustomerAcquisitionInfo`| `reqExternalContactCustomerAcquisitionInfo`     | `respExternalContactCustomerAcquisitionInfo`     |+| `POST /cgi-bin/externalcontact/customer_acquisition/get`       |[获取获客链接详情](https://developer.work.weixin.qq.com/document/path/97394#%E8%8E%B7%E5%8F%96%E8%8E%B7%E5%AE%A2%E9%93%BE%E6%8E%A5%E8%AF%A6%E6%83%85)
+`execExternalContactCustomerAcquisitionCreate`| `reqExternalContactCustomerAcquisitionCreate`   | `respExternalContactCustomerAcquisitionCreate`     |+| `POST /cgi-bin/externalcontact/customer_acquisition/create_link`       |[创建获客链接](https://developer.work.weixin.qq.com/document/path/97394#%E5%88%9B%E5%BB%BA%E8%8E%B7%E5%AE%A2%E9%93%BE%E6%8E%A5)
+`execExternalContactCustomerAcquisitionCustomer`| `reqExternalContactCustomerAcquisitionCustomer` | `respExternalContactCustomerAcquisitionCustomer` |+| `POST /cgi-bin/externalcontact/customer_acquisition/customer`  |[获取获客客户列表](https://developer.work.weixin.qq.com/document/path/97298)
+
+
 # 外部联系人管理 - 客户标签管理
 
 ## API calls

external_contact.go

@@ -39,6 +39,68 @@
 	return &BatchListExternalContactsResp{Result: resp.ExternalContactList, NextCursor: resp.NextCursor}, nil
 }
 
+// ListExternalContactCustomerAcquisitionLink 获取获客链接列表
+func (c *WorkwxApp) ListExternalContactCustomerAcquisitionLink(cursor string, limit int) (*ExternalContactCustomerAcquisitionLinkListResp, error) {
+	resp, err := c.execExternalContactCustomerAcquisitionLinkList(reqExternalContactCustomerAcquisitionLinkList{
+		Cursor: cursor,
+		Limit:  limit,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &ExternalContactCustomerAcquisitionLinkListResp{Result: resp.LinkIdList, NextCursor: resp.NextCursor}, nil
+}
+
+// GetExternalContactCustomerAcquisitionLink 获取获客链接详情
+func (c *WorkwxApp) GetExternalContactCustomerAcquisitionLink(linkId string) (*ExternalContactCustomerAcquisitionInfo, error) {
+	resp, err := c.execExternalContactCustomerAcquisitionInfo(reqExternalContactCustomerAcquisitionInfo{
+		LinkId: linkId,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &ExternalContactCustomerAcquisitionInfo{
+		LinkName:       resp.Link.LinkName,
+		Url:            resp.Link.Url,
+		CreateTime:     time.Unix(int64(resp.Link.CreateTime), 0),
+		SkipVerify:     resp.Link.SkipVerify,
+		Range:          resp.Link.Range,
+		PriorityOption: resp.Link.PriorityOption,
+	}, nil
+}
+
+// CreateExternalContactCustomerAcquisitionLink 创建获客链接
+func (c *WorkwxApp) CreateExternalContactCustomerAcquisitionLink(linkName string, customerAcquisitionRange ExternalContactCustomerAcquisitionRange, priorityOption ExternalContactCustomerAcquisitionPriorityOption, skipVerify bool) (*ExternalContactCustomerAcquisitionCreateResp, error) {
+	resp, err := c.execExternalContactCustomerAcquisitionCreate(reqExternalContactCustomerAcquisitionCreate{
+		LinkName:       linkName,
+		Range:          customerAcquisitionRange,
+		PriorityOption: priorityOption,
+		SkipVerify:     skipVerify,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &ExternalContactCustomerAcquisitionCreateResp{
+		LinkId:     resp.Link.LinkId,
+		LinkName:   resp.Link.LinkName,
+		Url:        resp.Link.Url,
+		CreateTime: time.Unix(int64(resp.Link.CreateTime), 0),
+	}, nil
+}
+
+// ExternalContactCustomerAcquisitionCustomer 获取获客客户列表
+func (c *WorkwxApp) ExternalContactCustomerAcquisitionCustomer(linkId string, cursor string, limit int) (*ExternalContactCustomerAcquisitionCustomerResp, error) {
+	resp, err := c.execExternalContactCustomerAcquisitionCustomer(reqExternalContactCustomerAcquisitionCustomer{
+		LinkId: linkId,
+		Cursor: cursor,
+		Limit:  limit,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &ExternalContactCustomerAcquisitionCustomerResp{Result: resp.CustomerList, NextCursor: resp.NextCursor}, nil
+}
+
 // RemarkExternalContact 修改客户备注信息
 func (c *WorkwxApp) RemarkExternalContact(req *ExternalContactRemark) error {
 	_, err := c.execExternalContactRemark(reqExternalContactRemark{

models.go

@@ -593,6 +593,186 @@
 	ExternalContactList []ExternalContactBatchInfo `json:"external_contact_list"`
 }
 
+// ExternalContactCustomerAcquisitionLinkListResp 获取获客链接列表
+type ExternalContactCustomerAcquisitionLinkListResp struct {
+	Result     []string
+	NextCursor string
+}
+
+// reqExternalContactCustomerAcquisitionLinkList 获取获客链接列表
+type reqExternalContactCustomerAcquisitionLinkList struct {
+	Cursor string `json:"cursor"`
+	Limit  int    `json:"limit"`
+}
+
+var _ bodyer = reqExternalContactCustomerAcquisitionLinkList{}
+
+func (x reqExternalContactCustomerAcquisitionLinkList) intoBody() ([]byte, error) {
+	return marshalIntoJSONBody(x)
+}
+
+// respExternalContactBatchList 获取获客链接列表
+type respExternalContactCustomerAcquisitionLinkList struct {
+	respCommon
+	NextCursor string   `json:"next_cursor"`
+	LinkIdList []string `json:"link_id_list"`
+}
+
+// ExternalContactCustomerAcquisitionInfo 获客链接信息
+type ExternalContactCustomerAcquisitionInfo struct {
+	//获客链接的名称
+	LinkName string `json:"link_name"`
+	//获客链接实际的url
+	Url string `json:"url"`
+	//创建时间
+	CreateTime time.Time `json:"create_time"`
+	//是否无需验证，默认为true
+	SkipVerify bool `json:"skip_verify"`
+	//该获客链接使用范围
+	Range ExternalContactCustomerAcquisitionRange `json:"range"`
+	//优先级选项
+	PriorityOption ExternalContactCustomerAcquisitionPriorityOption `json:"priority_option"`
+}
+
+// ExternalContactCustomerAcquisitionRange 该获客链接使用范围
+type ExternalContactCustomerAcquisitionRange struct {
+	//该获客链接使用范围成员列表
+	UserList []string `json:"user_list"`
+	//该获客链接使用范围的部门列表
+	DepartmentList []int `json:"department_list"`
+}
+
+// ExternalContactCustomerAcquisitionPriorityOption 优先级选项
+type ExternalContactCustomerAcquisitionPriorityOption struct {
+	//优先分配类型，1-全企业范围内优先分配给有好友关系的；2-指定范围内优先分配有好友关系的
+	PriorityType int `json:"priority_type"`
+	//priority_type为2时的指定成员列表
+	PriorityUseridList []string `json:"priority_userid_list"`
+}
+
+// reqExternalContactCustomerAcquisitionCreate 创建获客链接
+type reqExternalContactCustomerAcquisitionCreate struct {
+	//获客链接的名称
+	LinkName string `json:"link_name"`
+	//该获客链接使用范围
+	Range ExternalContactCustomerAcquisitionRange `json:"range"`
+	//优先级选项
+	PriorityOption ExternalContactCustomerAcquisitionPriorityOption `json:"priority_option"`
+	//是否无需验证，默认为true
+	SkipVerify bool `json:"skip_verify"`
+}
+
+var _ bodyer = reqExternalContactCustomerAcquisitionCreate{}
+
+func (x reqExternalContactCustomerAcquisitionCreate) intoBody() ([]byte, error) {
+
+	obj := map[string]any{
+		"link_name":   x.LinkName,
+		"skip_verify": x.SkipVerify,
+	}
+
+	if len(x.Range.UserList) > 0 || len(x.Range.DepartmentList) > 0 {
+		obj["range"] = x.Range
+	}
+	if len(x.PriorityOption.PriorityUseridList) > 0 || x.PriorityOption.PriorityType != 0 {
+		obj["priority_option"] = x.PriorityOption
+	}
+	return marshalIntoJSONBody(obj)
+}
+
+// respExternalContactCustomerAcquisitionCreate 创建获客链接
+type respExternalContactCustomerAcquisitionCreate struct {
+	respCommon
+	Link struct {
+		//获客链接的id
+		LinkId string `json:"link_id"`
+		//获客链接的名称
+		LinkName string `json:"link_name"`
+		//获客链接实际的url
+		Url string `json:"url"`
+		//创建时间
+		CreateTime int `json:"create_time"`
+	} `json:"link"`
+}
+
+type ExternalContactCustomerAcquisitionCreateResp struct {
+	LinkId string `json:"link_id"`
+	//获客链接的名称
+	LinkName string `json:"link_name"`
+	//获客链接实际的url
+	Url string `json:"url"`
+	//创建时间
+	CreateTime time.Time `json:"create_time"`
+}
+
+// reqExternalContactCustomerAcquisitionInfo 获客链接信息
+type reqExternalContactCustomerAcquisitionInfo struct {
+	LinkId string `json:"link_id"`
+}
+
+var _ bodyer = reqExternalContactCustomerAcquisitionInfo{}
+
+func (x reqExternalContactCustomerAcquisitionInfo) intoBody() ([]byte, error) {
+	return marshalIntoJSONBody(x)
+}
+
+// respExternalContactCustomerAcquisitionInfo 获客链接信息
+type respExternalContactCustomerAcquisitionInfo struct {
+	respCommon
+	Link struct {
+		//获客链接的名称
+		LinkName string `json:"link_name"`
+		//获客链接实际的url
+		Url string `json:"url"`
+		//创建时间
+		CreateTime int `json:"create_time"`
+		//是否无需验证，默认为true
+		SkipVerify bool `json:"skip_verify"`
+		//该获客链接使用范围
+		Range ExternalContactCustomerAcquisitionRange `json:"range"`
+		//优先级选项
+		PriorityOption ExternalContactCustomerAcquisitionPriorityOption `json:"priority_option"`
+	} `json:"link"`
+}
+
+// ExternalContactCustomerAcquisitionCustomerInfo 获客助手客户信息
+type ExternalContactCustomerAcquisitionCustomerInfo struct {
+	//客户external_userid
+	ExternalUserid string `json:"external_userid"`
+	//通过获客链接添加此客户的跟进人userid
+	UserId string `json:"userid"`
+	//会话状态，0-客户未发消息 1-客户已发送消息 2-客户发送消息状态未知
+	ChatStatus int `json:"chat_status"`
+	//用于区分客户具体是通过哪个获客链接进行添加，用户可在获客链接后拼接customer_channel=自定义字符串，字符串不超过64字节，超过会被截断。通过点击带有customer_channel参数的链接获取到的客户，调用获客信息接口或获取客户详情接口时，返回的state参数即为链接后拼接自定义字符串
+	State string `json:"state"`
+}
+
+// ExternalContactCustomerAcquisitionCustomerResp 获客助手客户信息
+type ExternalContactCustomerAcquisitionCustomerResp struct {
+	Result     []ExternalContactCustomerAcquisitionCustomerInfo
+	NextCursor string
+}
+
+// reqExternalContactCustomerAcquisitionCustomer 获客助手客户信息
+type reqExternalContactCustomerAcquisitionCustomer struct {
+	LinkId string `json:"link_id"`
+	Cursor string `json:"cursor"`
+	Limit  int    `json:"limit"`
+}
+
+var _ bodyer = reqExternalContactCustomerAcquisitionCustomer{}
+
+func (x reqExternalContactCustomerAcquisitionCustomer) intoBody() ([]byte, error) {
+	return marshalIntoJSONBody(x)
+}
+
+// respExternalContactBatchList 获客助手客户信息
+type respExternalContactCustomerAcquisitionCustomer struct {
+	respCommon
+	NextCursor   string                                           `json:"next_cursor"`
+	CustomerList []ExternalContactCustomerAcquisitionCustomerInfo `json:"customer_list"`
+}
+
 // reqExternalContactRemark 获取客户详情
 type reqExternalContactRemark struct {
 	Remark *ExternalContactRemark