From 60a31e0514c1c125176fd50503684c83a12250bd Mon Sep 17 00:00:00 2001
From: hi2code <51270649+hi2code@users.noreply.github.com>
Date: Tue, 25 Nov 2025 09:05:46 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E5=BE=AE=E4=BF=A1?=
 =?UTF-8?q?=E5=AE=A2=E6=9C=8D-=E8=8E=B7=E5=8F=96=E5=AE=A2=E6=88=B7?=
 =?UTF-8?q?=E5=9F=BA=E7=A1=80=E4=BF=A1=E6=81=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 apis.md.go | 11 +++++++++++
 kf.go      | 30 ++++++++++++++++++++++++++++++
 models.go  | 36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 77 insertions(+)

diff --git a/apis.md.go b/apis.md.go
index a5dc972..b585c72 100644
--- a/apis.md.go
+++ b/apis.md.go
@@ -936,3 +936,14 @@ func (c *WorkwxApp) execKfOnEventSend(req reqMessage) (respMessageSend, error) {
 
 	return resp, nil
 }
+
+// execKfCustomerBatchGet 获取客户基础信息
+func (c *WorkwxApp) execKfCustomerBatchGet(req reqKfCustomerBatchGet) (respKfCustomerBatchGet, error) {
+	var resp respKfCustomerBatchGet
+	err := executeQyapiJSONPost(c, "/cgi-bin/kf/customer/batchget", req, &resp, true)
+	if err != nil {
+		return respKfCustomerBatchGet{}, err
+	}
+
+	return resp, nil
+}
diff --git a/kf.go b/kf.go
index 96e7a73..d0828c1 100644
--- a/kf.go
+++ b/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
+}
diff --git a/models.go b/models.go
index 43280cc..e159f5a 100644
--- a/models.go
+++ b/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 {
 }