feat: 添加微信客服-获取客户基础信息

kf.go

@@ -1,5 +1,7 @@
 package workwx
 
+import "errors"
+
 // CreateKfAccount 创建客服账号
 func (c *WorkwxApp) CreateKfAccount(name, mediaID string) (openKfID string, err error) {
 	resp, err := c.execKfAccountCreate(reqKfAccountCreate{
@@ -139,3 +141,31 @@ func (c *WorkwxApp) KfSyncMsg(openKfID, token, cursor string, limit int64, voice
 	}
 	return resp.MsgList, resp.HasMore, resp.NextCursor, nil
 }
+
+// KfCustomerBatchGet 获取客户基础信息
+// 参数：
+//   - externalUseridList: 需要查询的 external_userid 列表。可填充个数：1 ~ 100。超过100个需分批调用。
+//   - needEnterSessionContext: 是否需要返回客户48小时内最后一次进入会话的上下文信息。
+//
+// 返回：
+//   - []KfCustomerInfo: 成功返回的客户信息
+//   - []string: 查询失败的 external_userid
+func (c *WorkwxApp) KfCustomerBatchGet(externalUseridList []string, needEnterSessionContext bool) ([]KfCustomerInfo, []string, error) {
+	needEnterSessionContextInt := 0
+	if needEnterSessionContext {
+		needEnterSessionContextInt = 1
+	}
+
+	if len(externalUseridList) == 0 || len(externalUseridList) > 100 {
+		return nil, nil, errors.New("externalUseridList length must be between 1 and 100")
+	}
+
+	resp, err := c.execKfCustomerBatchGet(reqKfCustomerBatchGet{
+		ExternalUseridList:      externalUseridList,
+		NeedEnterSessionContext: needEnterSessionContextInt,
+	})
+	if err != nil {
+		return nil, nil, err
+	}
+	return resp.CustomerList, resp.InvalidExternalUserid, nil
+}

models.go

@@ -2099,6 +2099,42 @@ type respKfSyncMsg struct {
 	MsgList    []KfMsg `json:"msg_list"`
 }
 
+// reqKfCustomerBatchGet 获取客户基础信息 请求
+type reqKfCustomerBatchGet struct {
+	ExternalUseridList      []string `json:"external_userid_list"`
+	NeedEnterSessionContext int      `json:"need_enter_session_context"`
+}
+
+var _ bodyer = reqKfCustomerBatchGet{}
+
+func (x reqKfCustomerBatchGet) intoBody() ([]byte, error) {
+	return marshalIntoJSONBody(x)
+}
+
+// respKfCustomerBatchGet 获取客户基础信息 响应
+type respKfCustomerBatchGet struct {
+	respCommon
+	CustomerList          []KfCustomerInfo `json:"customer_list"`
+	InvalidExternalUserid []string         `json:"invalid_external_userid"`
+}
+
+// KfCustomerInfo 客户基础信息
+type KfCustomerInfo struct {
+	ExternalUserid      string                 `json:"external_userid"`
+	Nickname            string                 `json:"nickname"`
+	Avatar              string                 `json:"avatar"`
+	Gender              int                    `json:"gender"`
+	Unionid             string                 `json:"unionid"`
+	EnterSessionContext *KfEnterSessionContext `json:"enter_session_context,omitempty"`
+}
+
+// KfEnterSessionContext 进入会话的上下文信息
+type KfEnterSessionContext struct {
+	Scene          string            `json:"scene"`
+	SceneParam     string            `json:"scene_param"`
+	WechatChannels *KfWechatChannels `json:"wechat_channels,omitempty"`
+}
+
 // reqOAGetCorpVacationConf 获取企业假期管理配置
 type reqOAGetCorpVacationConf struct {
 }