feat: add customer session refresh functionality and improve session management

- Introduced RealtimeCustomerSessionRefreshPayload and RealtimeCustomerSessionRefreshEvent types for handling session refresh events.
- Updated ws_service to verify customer session and handle session refresh notifications.
- Enhanced API client to manage customer session tokens and expiration.
- Implemented customer session validation and storage in session storage.
- Added functions to exchange and ensure customer sessions.
- Updated IM real-time connection to include customer session tokens in WebSocket requests.
- Modified SDK and widget configurations to support external IDs and user tokens.

config/config.example.yaml

@@ -20,6 +20,14 @@ auth:
   maxFailedAttempts: 5
   credentialLockMinute: 15
 
+customerSession:
+  # 客服会话 token 签名密钥。必须使用独立高强度随机字符串，不要复用渠道 userTokenSecret。
+  secret: ""
+  # 客服会话 token 默认有效期，单位分钟。
+  ttlMinutes: 120
+  # token 剩余有效期小于该值时自动续期，单位分钟。
+  refreshThresholdMinutes: 30
+
 storage:
   default: local
   maxUploadSizeMB: 20

internal/bootstrap/server.go

@@ -28,9 +28,9 @@ func NewServer() (*iris.Application, error) {
 	app := iris.New()
 	corsHandler := cors.New().
 		AllowOrigin("*").
-		AllowHeaders("Origin", "Content-Type", "Accept", "Authorization", "X-Requested-With", "X-Guest-Id", "X-Channel-Id", "X-External-Id", "X-External-Name").
+		AllowHeaders("Origin", "Content-Type", "Accept", "Authorization", "X-Requested-With", "X-Guest-Id", "X-Channel-Id", "X-External-Id", "X-External-Name", "X-Customer-Session-Token", "X-Customer-Session-Expires-At").
 		MaxAge(600).
-		ExposeHeaders("Content-Length", "Content-Type", "Authorization", "X-Guest-Id", "X-Channel-Id", "X-External-Id", "X-External-Name").
+		ExposeHeaders("Content-Length", "Content-Type", "Authorization", "X-Guest-Id", "X-Channel-Id", "X-External-Id", "X-External-Name", "X-Customer-Session-Token", "X-Customer-Session-Expires-At").
 		Handler()
 	app.UseRouter(func(ctx iris.Context) {
 		// WebSocket upgrade is validated by the upgrader's origin policy.
@@ -95,6 +95,7 @@ func addRouter(app *iris.Application) {
 	mvc.Configure(app.Party("/api"), func(m *mvc.Application) {
 		m.Party("/auth").Handle(new(api.AuthController))
 		m.Party("/channel").Handle(new(api.ChannelController))
+		m.Party("/customer").Handle(new(api.CustomerController))
 		m.Party("/conversation", middleware.ExternalUserMiddleware).Handle(new(api.ConversationController))
 		m.Party("/message", middleware.ExternalUserMiddleware).Handle(new(api.MessageController))
 	})

internal/controllers/api/customer_controller.go

@@ -0,0 +1,29 @@
+package api
+
+import (
+	"cs-agent/internal/pkg/openidentity"
+	"cs-agent/internal/services"
+
+	"github.com/kataras/iris/v12"
+	"github.com/mlogclub/simple/web"
+)
+
+type CustomerController struct {
+	Ctx iris.Context
+}
+
+func (c *CustomerController) PostSession_exchange() *web.JsonResult {
+	channel := services.ChannelService.GetEnabledChannel(c.Ctx)
+	if channel == nil {
+		return web.JsonErrorMsg("接入渠道不存在或已停用")
+	}
+	externalUser, err := openidentity.GetExternalUser(c.Ctx, services.ChannelService.GetUserTokenSecret(channel))
+	if err != nil {
+		return web.JsonError(err)
+	}
+	resp, err := services.CustomerSessionService.Exchange(channel, *externalUser)
+	if err != nil {
+		return web.JsonError(err)
+	}
+	return web.JsonData(resp)
+}

internal/middleware/chat_middleware.go

@@ -2,7 +2,6 @@ package middleware
 
 import (
 	"cs-agent/internal/pkg/irisx"
-	"cs-agent/internal/pkg/openidentity"
 	"cs-agent/internal/services"
 
 	"github.com/kataras/iris/v12"
@@ -16,13 +15,13 @@ func ExternalUserMiddleware(ctx iris.Context) {
 		_ = ctx.JSON(web.JsonErrorMsg("接入渠道异常"))
 		return
 	}
-	secret := services.ChannelService.GetUserTokenSecret(channel)
+	result, err := services.CustomerSessionService.VerifyRequest(ctx, channel)
-	ext, err := openidentity.GetExternalUser(ctx, secret)
 	if err != nil {
 		ctx.StopExecution()
 		_ = ctx.JSON(web.JsonError(err))
 		return
 	}
-	irisx.SetExternalUser(ctx, ext)
+	services.CustomerSessionService.SetRefreshHeaders(ctx, result)
+	irisx.SetExternalUser(ctx, result.ExternalUser)
 	ctx.Next()
 }

internal/pkg/config/config.go

@@ -9,14 +9,15 @@ import (
 )
 
 type Config struct {
-	Server   ServerConfig   `yaml:"server"`
+	Server          ServerConfig          `yaml:"server"`
-	DB       DBConfig       `yaml:"db"`
+	DB              DBConfig              `yaml:"db"`
-	Logger   LoggerConfig   `yaml:"logger"`
+	Logger          LoggerConfig          `yaml:"logger"`
-	Auth     AuthConfig     `yaml:"auth"`
+	Auth            AuthConfig            `yaml:"auth"`
-	Storage  StorageConfig  `yaml:"storage"`
+	Storage         StorageConfig         `yaml:"storage"`
-	VectorDB VectorDBConfig `yaml:"vectorDB"`
+	VectorDB        VectorDBConfig        `yaml:"vectorDB"`
-	MCP      MCPConfig      `yaml:"mcp"`
+	MCP             MCPConfig             `yaml:"mcp"`
-	WxWork   WxWorkConfig   `yaml:"wxWork"`
+	WxWork          WxWorkConfig          `yaml:"wxWork"`
+	CustomerSession CustomerSessionConfig `yaml:"customerSession"`
 }
 
 type WxWorkNotifyConfig struct {
@@ -60,6 +61,26 @@ type AuthConfig struct {
 	CredentialLockMinute int `yaml:"credentialLockMinute"`
 }
 
+type CustomerSessionConfig struct {
+	Secret                  string `yaml:"secret"`
+	TTLMinutes              int    `yaml:"ttlMinutes"`
+	RefreshThresholdMinutes int    `yaml:"refreshThresholdMinutes"`
+}
+
+func (c CustomerSessionConfig) TTL() int {
+	if c.TTLMinutes <= 0 {
+		return 120
+	}
+	return c.TTLMinutes
+}
+
+func (c CustomerSessionConfig) RefreshThreshold() int {
+	if c.RefreshThresholdMinutes <= 0 {
+		return 30
+	}
+	return c.RefreshThresholdMinutes
+}
+
 type StorageConfig struct {
 	Default         enums.AssetProvider `yaml:"default"`
 	MaxUploadSizeMB int64               `yaml:"maxUploadSizeMB"`

internal/pkg/dto/response/customer_session_response.go

@@ -0,0 +1,13 @@
+package response
+
+type CustomerSessionCustomerResponse struct {
+	ID   int64  `json:"id"`
+	Name string `json:"name"`
+}
+
+type CustomerSessionExchangeResponse struct {
+	CustomerSessionToken string                          `json:"customerSessionToken"`
+	ExpiresAt            string                          `json:"expiresAt"`
+	IdentityKey          string                          `json:"identityKey"`
+	Customer             CustomerSessionCustomerResponse `json:"customer"`
+}

internal/pkg/enums/im.go

@@ -251,6 +251,7 @@ const (
 	IMRealtimeEventConversationClosed      = "conversation.closed"
 	IMRealtimeEventConversationRead        = "conversation.read"
 	IMRealtimeEventNotificationCreated     = "notification.created"
+	IMRealtimeEventCustomerSessionRefresh  = "customer_session.refresh"
 )
 
 const (

internal/services/customer_session_service.go

@@ -0,0 +1,251 @@
+package services
+
+import (
+	"errors"
+	"strings"
+	"time"
+
+	"cs-agent/internal/models"
+	"cs-agent/internal/pkg/config"
+	"cs-agent/internal/pkg/dto/response"
+	"cs-agent/internal/pkg/enums"
+	"cs-agent/internal/pkg/errorsx"
+	"cs-agent/internal/pkg/openidentity"
+	"cs-agent/internal/repositories"
+
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/kataras/iris/v12"
+	"github.com/mlogclub/simple/sqls"
+	"github.com/mlogclub/simple/web/params"
+)
+
+const (
+	customerSessionTokenType = "customer_session"
+	customerSessionHeader    = "X-Customer-Session-Token"
+	customerSessionExpHeader = "X-Customer-Session-Expires-At"
+)
+
+var CustomerSessionService = newCustomerSessionService()
+
+func newCustomerSessionService() *customerSessionService {
+	return &customerSessionService{}
+}
+
+type customerSessionService struct {
+}
+
+type customerSessionClaims struct {
+	TokenType    string `json:"typ"`
+	ChannelID    int64  `json:"channelId"`
+	ChannelCode  string `json:"channelCode"`
+	CustomerID   int64  `json:"customerId"`
+	CustomerName string `json:"customerName"`
+	IdentityKey  string `json:"identityKey"`
+	jwt.RegisteredClaims
+}
+
+type CustomerSessionVerifyResult struct {
+	ExternalUser *openidentity.ExternalUser
+	Token        string
+	ExpiresAt    time.Time
+	Refreshed    bool
+}
+
+func (s *customerSessionService) Exchange(channel *models.Channel, externalUser openidentity.ExternalUser) (*response.CustomerSessionExchangeResponse, error) {
+	if channel == nil || channel.Status != enums.StatusOk {
+		return nil, errorsx.InvalidParam("接入渠道不存在或已停用")
+	}
+	var customerID int64
+	if err := sqls.WithTransaction(func(ctx *sqls.TxContext) error {
+		id, err := CustomerService.EnsureExternalCustomer(ctx.Tx, externalUser)
+		if err != nil {
+			return err
+		}
+		customerID = id
+		return nil
+	}); err != nil {
+		return nil, err
+	}
+	customer := CustomerService.Get(customerID)
+	if customer == nil || customer.Status == enums.StatusDeleted {
+		return nil, errorsx.InvalidParam("客户不存在")
+	}
+	token, expiresAt, err := s.Sign(channel, customer, externalUser)
+	if err != nil {
+		return nil, err
+	}
+	return &response.CustomerSessionExchangeResponse{
+		CustomerSessionToken: token,
+		ExpiresAt:            expiresAt.Format(time.DateTime),
+		IdentityKey:          s.identityKey(externalUser),
+		Customer: response.CustomerSessionCustomerResponse{
+			ID:   customer.ID,
+			Name: strings.TrimSpace(customer.Name),
+		},
+	}, nil
+}
+
+func (s *customerSessionService) Sign(channel *models.Channel, customer *models.Customer, externalUser openidentity.ExternalUser) (string, time.Time, error) {
+	cfg := config.Current().CustomerSession
+	secret := strings.TrimSpace(cfg.Secret)
+	if secret == "" {
+		return "", time.Time{}, errorsx.BusinessError(1, "客服会话密钥未配置")
+	}
+	if channel == nil || customer == nil {
+		return "", time.Time{}, errorsx.InvalidParam("客服会话参数不完整")
+	}
+	now := time.Now()
+	expiresAt := now.Add(time.Duration(cfg.TTL()) * time.Minute)
+	claims := customerSessionClaims{
+		TokenType:    customerSessionTokenType,
+		ChannelID:    channel.ID,
+		ChannelCode:  strings.TrimSpace(channel.ChannelID),
+		CustomerID:   customer.ID,
+		CustomerName: strings.TrimSpace(customer.Name),
+		IdentityKey:  s.identityKey(externalUser),
+		RegisteredClaims: jwt.RegisteredClaims{
+			IssuedAt:  jwt.NewNumericDate(now),
+			ExpiresAt: jwt.NewNumericDate(expiresAt),
+		},
+	}
+	token, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(secret))
+	if err != nil {
+		return "", time.Time{}, err
+	}
+	return token, expiresAt, nil
+}
+
+func (s *customerSessionService) VerifyRequest(ctx iris.Context, channel *models.Channel) (*CustomerSessionVerifyResult, error) {
+	token := s.getCustomerSessionToken(ctx)
+	if token == "" {
+		return nil, errorsx.Unauthorized("客服会话不能为空")
+	}
+	claims, err := s.verifyToken(token)
+	if err != nil {
+		return nil, err
+	}
+	if channel == nil || channel.Status != enums.StatusOk {
+		return nil, errorsx.InvalidParam("接入渠道不存在或已停用")
+	}
+	if claims.ChannelID != channel.ID || strings.TrimSpace(claims.ChannelCode) != strings.TrimSpace(channel.ChannelID) {
+		return nil, errorsx.Unauthorized("客服会话校验失败")
+	}
+	customer := CustomerService.Get(claims.CustomerID)
+	if customer == nil || customer.Status == enums.StatusDeleted {
+		return nil, errorsx.Unauthorized("客服会话校验失败")
+	}
+	external, err := s.externalUserFromClaims(claims, customer)
+	if err != nil {
+		return nil, err
+	}
+	result := &CustomerSessionVerifyResult{
+		ExternalUser: external,
+		Token:        token,
+		ExpiresAt:    claims.ExpiresAt.Time,
+	}
+	if s.shouldRefresh(claims.ExpiresAt.Time) {
+		newToken, expiresAt, err := s.Sign(channel, customer, *external)
+		if err != nil {
+			return nil, err
+		}
+		result.Token = newToken
+		result.ExpiresAt = expiresAt
+		result.Refreshed = true
+	}
+	return result, nil
+}
+
+func (s *customerSessionService) SetRefreshHeaders(ctx iris.Context, result *CustomerSessionVerifyResult) {
+	if ctx == nil || result == nil || !result.Refreshed {
+		return
+	}
+	ctx.Header(customerSessionHeader, result.Token)
+	ctx.Header(customerSessionExpHeader, result.ExpiresAt.Format(time.DateTime))
+}
+
+func (s *customerSessionService) verifyToken(rawToken string) (*customerSessionClaims, error) {
+	cfg := config.Current().CustomerSession
+	secret := strings.TrimSpace(cfg.Secret)
+	if secret == "" {
+		return nil, errorsx.BusinessError(1, "客服会话密钥未配置")
+	}
+	claims := &customerSessionClaims{}
+	token, err := jwt.ParseWithClaims(rawToken, claims, func(token *jwt.Token) (any, error) {
+		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, errors.New("unsupported signing method")
+		}
+		return []byte(secret), nil
+	}, jwt.WithExpirationRequired(), jwt.WithValidMethods([]string{
+		jwt.SigningMethodHS256.Alg(),
+		jwt.SigningMethodHS384.Alg(),
+		jwt.SigningMethodHS512.Alg(),
+	}))
+	if err != nil {
+		if errors.Is(err, jwt.ErrTokenExpired) {
+			return nil, errorsx.Unauthorized("客服会话已过期")
+		}
+		return nil, errorsx.Unauthorized("客服会话校验失败")
+	}
+	if token == nil || !token.Valid || claims.TokenType != customerSessionTokenType || claims.ExpiresAt == nil {
+		return nil, errorsx.Unauthorized("客服会话校验失败")
+	}
+	if claims.ChannelID <= 0 || strings.TrimSpace(claims.ChannelCode) == "" || claims.CustomerID <= 0 || strings.TrimSpace(claims.IdentityKey) == "" {
+		return nil, errorsx.Unauthorized("客服会话校验失败")
+	}
+	return claims, nil
+}
+
+func (s *customerSessionService) externalUserFromClaims(claims *customerSessionClaims, customer *models.Customer) (*openidentity.ExternalUser, error) {
+	identityKey := strings.TrimSpace(claims.IdentityKey)
+	parts := strings.SplitN(identityKey, ":", 2)
+	if len(parts) != 2 || strings.TrimSpace(parts[1]) == "" {
+		return nil, errorsx.Unauthorized("客服会话校验失败")
+	}
+	var source enums.ExternalSource
+	switch parts[0] {
+	case "user":
+		source = enums.ExternalSourceUser
+	case "guest":
+		source = enums.ExternalSourceGuest
+	default:
+		return nil, errorsx.Unauthorized("客服会话校验失败")
+	}
+	identity := repositories.CustomerIdentityRepository.GetBy(sqls.DB(), source, parts[1])
+	if identity == nil || identity.CustomerID != claims.CustomerID {
+		return nil, errorsx.Unauthorized("客服会话校验失败")
+	}
+	name := strings.TrimSpace(claims.CustomerName)
+	if customer != nil && strings.TrimSpace(customer.Name) != "" {
+		name = strings.TrimSpace(customer.Name)
+	}
+	return &openidentity.ExternalUser{
+		ExternalSource: source,
+		ExternalID:     parts[1],
+		ExternalName:   name,
+	}, nil
+}
+
+func (s *customerSessionService) shouldRefresh(expiresAt time.Time) bool {
+	threshold := config.Current().CustomerSession.RefreshThreshold()
+	return time.Until(expiresAt) <= time.Duration(threshold)*time.Minute
+}
+
+func (s *customerSessionService) identityKey(externalUser openidentity.ExternalUser) string {
+	switch externalUser.ExternalSource {
+	case enums.ExternalSourceUser:
+		return "user:" + strings.TrimSpace(externalUser.ExternalID)
+	default:
+		return "guest:" + strings.TrimSpace(externalUser.ExternalID)
+	}
+}
+
+func (s *customerSessionService) getCustomerSessionToken(ctx iris.Context) string {
+	auth := strings.TrimSpace(ctx.GetHeader("Authorization"))
+	if len(auth) > 7 && strings.EqualFold(auth[:7], "Bearer ") {
+		if token := strings.TrimSpace(auth[7:]); token != "" {
+			return token
+		}
+	}
+	token, _ := params.Get(ctx, "customerSessionToken")
+	return strings.TrimSpace(token)
+}

internal/services/ws_realtime_types.go

@@ -239,6 +239,25 @@ func (e RealtimeNotificationCreatedEvent) EventPayload() RealtimeEventPayload {
 	return e.Payload
 }
 
+type RealtimeCustomerSessionRefreshPayload struct {
+	CustomerSessionToken string `json:"customerSessionToken"`
+	ExpiresAt            string `json:"expiresAt"`
+}
+
+func (RealtimeCustomerSessionRefreshPayload) realtimeEventPayload() {}
+
+type RealtimeCustomerSessionRefreshEvent struct {
+	Payload RealtimeCustomerSessionRefreshPayload
+}
+
+func (e RealtimeCustomerSessionRefreshEvent) EventType() string {
+	return enums.IMRealtimeEventCustomerSessionRefresh
+}
+
+func (e RealtimeCustomerSessionRefreshEvent) EventPayload() RealtimeEventPayload {
+	return e.Payload
+}
+
 type realtimeClientMessage struct {
 	Type    string   `json:"type"`
 	Topics  []string `json:"topics,omitempty"`

internal/services/ws_service.go

@@ -75,25 +75,27 @@ func (s *wsService) HandleOpenWS(ctx iris.Context) {
 	}
 
 	var (
-		principal = AuthService.GetAuthPrincipal(ctx)
+		principal           = AuthService.GetAuthPrincipal(ctx)
-		external  *openidentity.ExternalUser
+		external            *openidentity.ExternalUser
+		customerSessionInfo *CustomerSessionVerifyResult
 	)
 	if principal == nil {
-		ext, err := openidentity.GetExternalUser(ctx, ChannelService.GetUserTokenSecret(channel))
+		result, err := CustomerSessionService.VerifyRequest(ctx, channel)
 		if err != nil {
 			_ = ctx.StopWithJSON(iris.StatusUnauthorized, web.JsonError(err))
 			return
 		}
-		external = ext
+		external = result.ExternalUser
+		customerSessionInfo = result
 	}
-	if err := s.upgradeConnection(ctx, principal, external, realtimeRoleUser); err != nil {
+	if err := s.upgradeConnection(ctx, principal, external, realtimeRoleUser, customerSessionInfo); err != nil {
 		slog.Error("upgrade open im websocket failed", "error", err, "path", ctx.Path(), "channelId", channel.ChannelID, "channel_id", channel.ID)
 		ctx.StopExecution()
 		return
 	}
 }
 
-func (s *wsService) upgradeConnection(ctx iris.Context, principal *dto.AuthPrincipal, external *openidentity.ExternalUser, role string) error {
+func (s *wsService) upgradeConnection(ctx iris.Context, principal *dto.AuthPrincipal, external *openidentity.ExternalUser, role string, customerSessionInfo ...*CustomerSessionVerifyResult) error {
 	conn, err := s.upgrader.Upgrade(ctx.ResponseWriter().Naive(), ctx.Request(), nil)
 	if err != nil {
 		return err
@@ -151,6 +153,14 @@ func (s *wsService) upgradeConnection(ctx iris.Context, principal *dto.AuthPrinc
 			Topics:       session.topicList(),
 		},
 	}))
+	if len(customerSessionInfo) > 0 && customerSessionInfo[0] != nil && customerSessionInfo[0].Refreshed {
+		session.enqueueEvent(s.newEvent("", RealtimeCustomerSessionRefreshEvent{
+			Payload: RealtimeCustomerSessionRefreshPayload{
+				CustomerSessionToken: customerSessionInfo[0].Token,
+				ExpiresAt:            customerSessionInfo[0].ExpiresAt.Format(time.DateTime),
+			},
+		}))
+	}
 	return nil
 }
 

web/lib/api/client.ts

@@ -14,6 +14,7 @@ type RequestOptions = RequestInit & {
   skipAuth?: boolean
   retryOnAuthError?: boolean
   baseUrl?: string
+  onResponse?: (response: Response) => void
 }
 
 async function parseResult<T>(response: Response) {
@@ -58,9 +59,10 @@ export async function request<T>(
   options: RequestOptions = {},
   retryOnAuthError = true
 ): Promise<T> {
-  const { headers, skipAuth, baseUrl, ...rest } = options
+  const { headers, skipAuth, baseUrl, onResponse, ...rest } = options
   delete (rest as RequestOptions).retryOnAuthError
   delete (rest as RequestOptions).baseUrl
+  delete (rest as RequestOptions).onResponse
   const session = readSession()
   const authHeaders = new Headers(headers)
 
@@ -81,6 +83,7 @@ export async function request<T>(
     headers: authHeaders,
     cache: "no-store",
   })
+  onResponse?.(response)
 
   try {
     return await parseResult<T>(response)

web/lib/api/im.ts

@@ -112,12 +112,33 @@ export type ImWidgetConfig = {
   width?: string
 }
 
+export type ImCustomerSessionCustomer = {
+  id: number
+  name: string
+}
+
+export type ImCustomerSessionExchangeResponse = {
+  customerSessionToken: string
+  expiresAt: string
+  identityKey: string
+  customer: ImCustomerSessionCustomer
+}
+
+export type ImCustomerSession = ImCustomerSessionExchangeResponse & {
+  channelId: string
+}
+
 const GUEST_STORAGE_KEY = "cs_agent_im_guest_id"
+const CUSTOMER_SESSION_STORAGE_KEY = "cs_agent_customer_session"
+const CUSTOMER_SESSION_TOKEN_HEADER = "X-Customer-Session-Token"
+const CUSTOMER_SESSION_EXPIRES_HEADER = "X-Customer-Session-Expires-At"
 const API_BASE_URL =
   process.env.NEXT_PUBLIC_API_BASE_URL?.trim() || ""
 const OPEN_IM_CHANNEL_ID =
   process.env.NEXT_PUBLIC_OPEN_IM_CHANNEL_ID?.trim() || ""
 
+let entryUserTokenExchangeKey = ""
+
 function buildGuestId() {
   return `guest_${generateUUID()}`
 }
@@ -149,7 +170,95 @@ function getRuntimeImConfig() {
   }
 }
 
-function createImHeaders() {
+function parseExpiresAt(value: string) {
+  const normalized = value.trim().replace(" ", "T")
+  const timestamp = Date.parse(normalized)
+  return Number.isFinite(timestamp) ? timestamp : 0
+}
+
+function isCustomerSessionValid(
+  session: ImCustomerSession | null,
+  channelId?: string,
+  identityKey?: string
+) {
+  if (!session?.customerSessionToken || !session.expiresAt) {
+    return false
+  }
+  if (channelId && session.channelId !== channelId) {
+    return false
+  }
+  if (identityKey && session.identityKey !== identityKey) {
+    return false
+  }
+  return parseExpiresAt(session.expiresAt) > Date.now() + 5000
+}
+
+export function readCustomerSession(): ImCustomerSession | null {
+  if (typeof window === "undefined") {
+    return null
+  }
+  const raw = window.sessionStorage.getItem(CUSTOMER_SESSION_STORAGE_KEY)
+  if (!raw) {
+    return null
+  }
+  try {
+    return JSON.parse(raw) as ImCustomerSession
+  } catch {
+    window.sessionStorage.removeItem(CUSTOMER_SESSION_STORAGE_KEY)
+    return null
+  }
+}
+
+function writeCustomerSession(session: ImCustomerSession) {
+  if (typeof window === "undefined") {
+    return
+  }
+  window.sessionStorage.setItem(CUSTOMER_SESSION_STORAGE_KEY, JSON.stringify(session))
+}
+
+export function getCustomerSessionToken() {
+  const config = getRuntimeImConfig()
+  const session = readCustomerSession()
+  return isCustomerSessionValid(session, config.channelId)
+    ? session?.customerSessionToken ?? ""
+    : ""
+}
+
+export function applyCustomerSessionRefresh(payload?: {
+  customerSessionToken?: string
+  expiresAt?: string
+}) {
+  const token = payload?.customerSessionToken?.trim()
+  const expiresAt = payload?.expiresAt?.trim()
+  if (!token || !expiresAt) {
+    return
+  }
+  const current = readCustomerSession()
+  if (!current) {
+    return
+  }
+  writeCustomerSession({
+    ...current,
+    customerSessionToken: token,
+    expiresAt,
+  })
+}
+
+function applyCustomerSessionHeaders(response: Response) {
+  applyCustomerSessionRefresh({
+    customerSessionToken: response.headers.get(CUSTOMER_SESSION_TOKEN_HEADER) ?? "",
+    expiresAt: response.headers.get(CUSTOMER_SESSION_EXPIRES_HEADER) ?? "",
+  })
+}
+
+function createChannelHeaders() {
+  const config = getRuntimeImConfig()
+  return {
+    "X-Channel-Id": config.channelId,
+  }
+}
+
+function createExchangeHeaders() {
   const config = getRuntimeImConfig()
   const headers: Record<string, string> = {
     "X-Channel-Id": config.channelId,
@@ -167,9 +276,24 @@ function createImHeaders() {
   }
 }
 
+function createImHeaders() {
+  const sessionToken = getCustomerSessionToken()
+  if (!sessionToken) {
+    throw new Error("客服会话未初始化")
+  }
+  return {
+    ...createChannelHeaders(),
+    Authorization: `Bearer ${sessionToken}`,
+  }
+}
+
 function createRequestOptions(
   init?: RequestInit
-): RequestInit & { baseUrl?: string; skipAuth?: boolean } {
+): RequestInit & {
+  baseUrl?: string
+  skipAuth?: boolean
+  onResponse?: (response: Response) => void
+} {
   return {
     ...init,
     skipAuth: true,
@@ -177,6 +301,7 @@ function createRequestOptions(
       ...createImHeaders(),
       ...(init?.headers as Record<string, string> | undefined),
     },
+    onResponse: applyCustomerSessionHeaders,
     baseUrl: getRuntimeImConfig().baseUrl,
   }
 }
@@ -197,6 +322,50 @@ function toQueryString(query?: Record<string, string | number | undefined>) {
   return output ? `?${output}` : ""
 }
 
+export async function exchangeCustomerSession() {
+  const config = getRuntimeImConfig()
+  const result = await request<ImCustomerSessionExchangeResponse>(
+    "/api/customer/session_exchange",
+    {
+      method: "POST",
+      skipAuth: true,
+      baseUrl: config.baseUrl,
+      headers: createExchangeHeaders(),
+    }
+  )
+  const session = {
+    ...result,
+    channelId: config.channelId,
+  }
+  writeCustomerSession(session)
+  if (config.userToken) {
+    entryUserTokenExchangeKey = `${config.channelId}:${config.userToken}`
+  }
+  return session
+}
+
+export async function ensureCustomerSession() {
+  const config = getRuntimeImConfig()
+  const cached = readCustomerSession()
+  if (config.userToken) {
+    const exchangeKey = `${config.channelId}:${config.userToken}`
+    if (
+      entryUserTokenExchangeKey === exchangeKey &&
+      isCustomerSessionValid(cached, config.channelId)
+    ) {
+      return cached
+    }
+    return exchangeCustomerSession()
+  }
+
+  const externalId = config.externalId || getGuestId()
+  const identityKey = `guest:${externalId}`
+  if (isCustomerSessionValid(cached, config.channelId, identityKey)) {
+    return cached
+  }
+  return exchangeCustomerSession()
+}
+
 export function fetchImConversationDetail(id: number) {
   return request<ImConversationDetail>(`/api/conversation/${id}`, {
     ...createRequestOptions(),
@@ -212,7 +381,6 @@ export function fetchImMessages(
   )
 }
 
-/** 外部身份仅通过 createImHeaders()（Authorization 或 X-External-Id/Name）传递，无 JSON body */
 export function createOrMatchImConversation() {
   return request<ImConversation>("/api/conversation/create_or_match", {
     ...createRequestOptions({ method: "POST" }),
@@ -224,7 +392,11 @@ export function fetchImWidgetConfig() {
     `/api/channel/config${toQueryString({
       channelId: getRuntimeImConfig().channelId,
     })}`,
-    createRequestOptions()
+    {
+      skipAuth: true,
+      baseUrl: getRuntimeImConfig().baseUrl,
+      headers: createChannelHeaders(),
+    }
   )
 }
 

web/lib/im-realtime.ts

@@ -1,5 +1,5 @@
 import { createWebSocketBaseUrl } from "@/lib/api/websocket"
-import { getGuestId, type ImMessage } from "@/lib/api/im"
+import { getCustomerSessionToken, type ImMessage } from "@/lib/api/im"
 import { readKefuWidgetConfig } from "@/lib/kefu-widget-config"
 import type {
   RealtimeConversationPatch,
@@ -9,8 +9,16 @@ import type {
 export type ImRealtimeEnvelope = {
   type: string
   topic?: string
-  data?: RealtimeMessageCreatedPayload<ImMessage> & RealtimeConversationPatch
+  data?: RealtimeMessageCreatedPayload<ImMessage> &
-  payload?: RealtimeMessageCreatedPayload<ImMessage> & RealtimeConversationPatch
+    RealtimeConversationPatch & {
+      customerSessionToken?: string
+      expiresAt?: string
+    }
+  payload?: RealtimeMessageCreatedPayload<ImMessage> &
+    RealtimeConversationPatch & {
+      customerSessionToken?: string
+      expiresAt?: string
+    }
 }
 
 export function createImRealtimeConnection() {
@@ -19,22 +27,9 @@ export function createImRealtimeConnection() {
   const baseUrl = apiBaseUrl
     ? apiBaseUrl.replace(/^http/, "ws").replace(/\/$/, "")
     : createWebSocketBaseUrl()
-  const resolvedExternalId = encodeURIComponent(
-    (config.externalId ?? "").trim() || getGuestId()
-  )
   const channelId = encodeURIComponent(config.channelId || "")
-  const userToken = (config.userToken ?? "").trim()
+  const customerSessionToken = getCustomerSessionToken()
-  if (userToken) {
-    return new WebSocket(
-      `${baseUrl}/api/ws/open?channelId=${channelId}&userToken=${encodeURIComponent(userToken)}`
-    )
-  }
-  const externalName = (config.externalName ?? "").trim()
-  const nameQuery =
-    externalName !== ""
-      ? `&externalName=${encodeURIComponent(externalName)}`
-      : ""
   return new WebSocket(
-    `${baseUrl}/api/ws/open?externalId=${resolvedExternalId}&channelId=${channelId}${nameQuery}`
+    `${baseUrl}/api/ws/open?channelId=${channelId}&customerSessionToken=${encodeURIComponent(customerSessionToken)}`
   )
 }

web/lib/kefu-widget-config.ts

@@ -4,9 +4,9 @@ export type KefuWidgetHostConfig = {
   apiBaseUrl?: string
   /** 外部访客稳定标识；未传时使用浏览器本地访客 ID */
   externalId?: string
-  /** 访客展示名，随请求以 X-External-Name / WS query externalName 传给后端 */
+  /** 访客展示名，仅用于首次换取客服会话 token */
   externalName?: string
-  /** 业务系统签发的前台用户 JWT */
+  /** 业务系统签发的前台用户 JWT，仅用于首次换取客服会话 token */
   userToken?: string
   title?: string
   subtitle?: string

web/lib/sdk/cs-ai-agent-sdk.js

@@ -46,6 +46,9 @@
       delete merged.apiBaseUrl;
     }
     merged.channelId = String(merged.channelId || "");
+    if (merged.externalId) {
+      merged.externalId = String(merged.externalId);
+    }
     if (merged.userToken) {
       merged.userToken = String(merged.userToken);
     }
@@ -66,6 +69,7 @@
     frameUrl.searchParams.set("channelId", config.channelId);
     frameUrl.searchParams.set("baseUrl", config.baseUrl);
     if (config.apiBaseUrl) frameUrl.searchParams.set("apiBaseUrl", config.apiBaseUrl);
+    if (config.externalId) frameUrl.searchParams.set("externalId", config.externalId);
     if (config.externalName) frameUrl.searchParams.set("externalName", config.externalName);
     if (config.userToken) frameUrl.searchParams.set("userToken", config.userToken);
     return frameUrl;

web/lib/stores/kefu-chat.ts

@@ -5,12 +5,14 @@ import { create } from "zustand"
 import {
   closeImConversation,
   createOrMatchImConversation,
+  ensureCustomerSession,
   fetchImMessages,
   fetchImWidgetConfig,
   markImMessageRead,
   sendImMessage,
   uploadImAttachment,
   uploadImImage,
+  applyCustomerSessionRefresh,
   type ImAsset,
   type ImConversation,
   type ImMessage,
@@ -159,11 +161,17 @@ export const useKefuChatStore = create<KefuChatStore>((set, get) => {
         return
       }
 
+      const payload = event.data ?? event.payload
+      if (event.type === "customer_session.refresh") {
+        applyCustomerSessionRefresh(payload)
+        return
+      }
+
       const conversationId = get().conversation?.id
       if (!conversationId) {
         return
       }
-      const payload = event.data ?? event.payload
+
       if (event.type === "resyncRequired") {
         void get().refreshMessages()
         return
@@ -281,6 +289,11 @@ export const useKefuChatStore = create<KefuChatStore>((set, get) => {
             themeColor: widgetConfig.themeColor || "#2563eb",
           })
 
+          await ensureCustomerSession()
+          if (bootstrapToken !== token || !get().isOpen) {
+            return
+          }
+
           let currentConversation = get().conversation
           if (!get().initialized || !currentConversation) {
             currentConversation = await createOrMatchImConversation()

web/public/sdk/cs-agent-widget.js

@@ -41,6 +41,9 @@
     merged.baseUrl = String(merged.baseUrl || window.location.origin).replace(/\/$/, "");
     merged.apiBaseUrl = String(merged.apiBaseUrl || merged.baseUrl).replace(/\/$/, "");
     merged.channelId = String(merged.channelId || "");
+    if (merged.externalId) {
+      merged.externalId = String(merged.externalId);
+    }
     if (merged.userToken) {
       merged.userToken = String(merged.userToken);
     }
@@ -66,6 +69,7 @@
     if (config.position) frameUrl.searchParams.set("position", config.position);
     if (config.themeColor) frameUrl.searchParams.set("themeColor", config.themeColor);
     if (config.width) frameUrl.searchParams.set("width", config.width);
+    if (config.externalId) frameUrl.searchParams.set("externalId", config.externalId);
     if (config.externalName) frameUrl.searchParams.set("externalName", config.externalName);
     if (config.userToken) frameUrl.searchParams.set("userToken", config.userToken);
     return frameUrl;