Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

无头 Web SDK API 方法

本页面列出了适用于无头 Web SDK 的 API 方法。

用于处理公司价值和菜单的方法。

方法

无头 SDK 提供了可在客户端实例上调用的各种方法。

下面是一些示例：

公司和菜单

方法名称	说明
getCompany	检索已配置的公司信息。
getMenus	列出指定租户的所有可用菜单。
getWaitTimes	在菜单上获取各种渠道的当前等待时间。

getCompany

检索经过身份验证的实例的已配置公司信息，包括公司名称、支持的语言和功能设置。此方法还会设置内部实例标识符 (OPTIONS.tenant) 作为副作用，这就是为什么它通常是在构建 Client 后进行的第一个调用。

方法签名

getCompany(): Promise<CompanyResponse>

返回值

返回一个 CompanyResponse 对象。

接口

interface CompanyResponse {
  name: string;
  subdomain: string;
  support_email: string;
  languages: LanguageOption[];
  action_tracking: boolean;
  email_transcripts: boolean;
  message_preview: boolean;
  email_enhancement: boolean;
  display_history: boolean;
  use_recording: boolean;
  use_web: boolean;
  cobrowse_domain?: string;
}

用法示例

try {
  const company = await client.getCompany()
} catch (error) {
  // handle error
}

getMenus

此方法用于列出实例的所有可用菜单项。MenuResponse.direct 字段会告知调用方结果是来自直接访问键 (direct.key: true) 还是来自用户级直接访问 (direct.user: true) - 这两者都会影响菜单的呈现方式。

方法签名

getMenus(key?: string, lang?: string): Promise<MenuResponse>

返回值

返回一个 MenuResponse 对象。

接口

interface MenuResponse {
  menus: MenuItem[];
  direct: {
    key: boolean;
    user: boolean;
    key_id: number | null;
  };
}
interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
  hidden: boolean;
}

用法示例

try {
  const data: MenuResponse = await client.getMenus("direct_menu_key")
  console.log(data.menus)
  console.log(data.direct)
} catch (error) {
  // handle error
}

getWaitTimes

检索给定菜单的聊天和语音通话渠道的预计等待时间（以秒为单位）。

方法签名

getWaitTimes(menuId: number | string, lang?: string): Promise<WaitTimeResponse | null>

返回值

返回 WaitTimeResponse 对象或 null。

接口

interface WaitTimeResponse {
  chat: number;
  voice_call: number;
}

用法示例

try {
  const data = await client.getWaitTimes(123)
} catch (error) {
  // handle error
}

通话

名称	说明
`createCall`	发起即时通话或安排通话。
`loadCall`	从给定的通话 ID 获取信息。
`cancelCall`	取消具有给定通话 ID 的通话。
`getTimeSlots`	获取给定菜单的预约通话可用时间段。
`fetchTimeSlotAvailability`	检查给定菜单是否有可用的时间段。

createCall

为指定菜单创建新通话。这可以是即时通话或预约通话，具体取决于是否提供了 scheduled_at 字段。调用类型（web_instant_call 与 web_scheduled_call）会根据 scheduled_at 的存在自动确定。reschedule_call_id 在请求的顶层发送，与调用正文分开。响应中的 menu_id 是从 API 的 selected_menu.id 归一化而来的。

方法签名

createCall(menuId: number | string, data: CallRequest): Promise<CallResponse>

返回值

返回一个 CallResponse 对象。

接口

interface CallRequest {
  phone_number: string;
  lang?: string;
  scheduled_at?: string;
  ticket_id?: string;
  email?: string;
  recording_permission?: "recording_permission_not_asked" | "recording_permission_granted" | "recording_permission_denied";
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
  reschedule_call_id?: number;
}

用法示例

try {
 const call = await client.createCall(123, { phone_number: '+12345678' })
} catch (error) {
 // handle error
}

loadCall

loadCall 方法会检索由其 ID 标识的特定通话的相关信息。

方法签名

loadCall(callId: number | string): Promise<CallResponse>

返回值

返回一个 CallResponse 对象。

接口

interface CallResponse {
 id: number;
 lang: string;
 menu_id: number;
 status: string;
 type: string;
 scheduled_at?: string;
 recording_permitted: boolean;
 survey_enabled: boolean;
 created_at: string;
 menus: {
   id: number;
   name: string;
 }[];
}

用法示例

try {
 const call = await client.loadCall(1234)
} catch (error) {
 // handle error
}

cancelCall

通过 ID 取消现有通话。通常用于取消尚未拨打的预定通话。

方法签名

cancelCall(callId: number | string): Promise<CallResponse>

返回值

返回 CallResponse 对象。

接口

interface CallResponse {
 id: number;
 lang: string;
 menu_id: number;
 status: string;
 type: string;
 scheduled_at?: string;
 recording_permitted: boolean;
 survey_enabled: boolean;
 created_at: string;
 menus: {
   id: number;
   name: string;
 }[];
}

用法示例

try {
 const response = await client.cancelCall(1234)
} catch (error) {
 // handle error
}

getTimeSlots

检索指定菜单中预约通话的可用时间段。使用 GetTimeSlotsRequest 选项对象调用时，支持使用 rescheduleCallId 重新安排现有通话。已弃用的 lang 字符串签名仍受支持，并会路由到仅填充了 lang 的同一端点。返回一个时间段字符串数组。

方法签名

getTimeSlots(menuId: number | string, options?: GetTimeSlotsRequest): Promise<string[]>

返回值

返回一个字符串数组（时间段）。

接口

interface GetTimeSlotsRequest {
 lang?: string;
 rescheduleCallId?: number;          // ID of an existing call being rescheduled
}

用法示例

// New options-based signature (recommended)
try {
 const slots = await client.getTimeSlots(123, {
   lang: 'en',
   rescheduleCallId: 98765, // optional: pass when rescheduling an existing call
 })
} catch (error) {
 // handle error
}
// Deprecated signature (still supported)
try {
 const slots = await client.getTimeSlots(123, 'en')
} catch (error) {
 // handle error
}

fetchTimeSlotAvailability

此方法会检查给定菜单是否有可用的时间段，而无需提取完整的时间段列表。这对于在界面中有条件地显示调度选项非常有用。

范围

fetchTimeSlotAvailability 仅适用于预约的语音通话（回电）预约。它不会返回有关聊天、电子邮件或即时通话渠道的信息。提供的菜单必须配置为支持预约语音通话，并定义了营业时间，且至少有一名客服人员排队等待该菜单。

典型应用场景：

仅在有空闲时段时，才显示“预约回电”号召性用语。
在没有空闲时段时，分支到转移流程（例如电子邮件、非工作时间消息），而无需支付完整 getTimeSlots 调用的费用。
在调用 getTimeSlots 之前，使用 rescheduleCallId 预检重新安排操作。

方法签名

fetchTimeSlotAvailability(menuId: number | string, lang?: string): Promise<boolean>

返回值

如果时间段可用，则返回 true，否则返回 false。

用法示例

try {
 const isAvailable = await client.fetchTimeSlotAvailability(123, 'en')
 if (isAvailable) {
   // Show scheduling UI
 }
} catch (error) {
 // handle error
}

聊天

名称	说明
`createChat`	创建新对话。
`loadChat`	检索具有指定聊天 ID 的聊天。
`loadOngoingChat`	尝试加载正在进行的对话。
`resumeChat`	恢复具有给定聊天 ID 的已关闭聊天。
`finishChat`	将当前对话的状态设为“已结束”。
`destroyChat`	调用 `finishChat` 并销毁当前对话
`fetchMessages`	检索之前的消息 - 失败时返回 `[]`。
`sendTextMessage`	发送短信。
`sendFileMessage`	发送文件消息 - 上传失败时返回 `-1`。
`sendPreviewMessage`	发送预览消息。
`getChatDeflection`	获取聊天偏转配置。
`sendChatTranscripts`	将聊天转写内容发送到指定邮箱。
`downloadChatTranscript`	下载聊天转写文稿。
`getPdfStatus`	获取转写内容的 PDF 状态。
`getChatSurvey`	获取聊天调查问卷问题。
`sendChatSurvey`	发送调查问卷中的用户反馈。
`sendChatRate`	发送有关聊天的用户反馈。
`escalateChat`	将聊天从虚拟客服升级到人工客服。
`trackChatEscalation`	跟踪聊天上报事件。
`trackChatEndUserEvent`	跟踪最终用户事件。
`getChatHistory`	检索给定对话的历史记录。

Chat 签到

“签到”功能会在消费者连接到客服人员之前，要求消费者确认自己已准备就绪。本部分介绍了用于实现该体验的无头 Web SDK 方法。如需了解什么是签到、如何启用和配置签到（等待时间、超时、队列位置、重新加入行为）以及报告，请参阅聊天签到。

名称	说明
`checkIn`	向服务器发送信号，以确认用户在队列中。
`exitCheckIn`	将用户从签到队列中移除。
`notifyCheckInState`	向后端通知签到模态窗口的可见性状态。
`rejoinChat`	在未能确认签到后，将用户放回队列。
`trackCheckInEvent`	当界面触发签到事件时，向后端发出信号。

`checkIn`

向服务器发送确认信号，表明消费者已到场，并准备好在签到时间段内与客服人员联系。在服务器确认后，在本地更新对话的 check_in_status。用于响应 chat.checkInRequested 事件。

方法签名

checkIn(): Promise<CheckInResponse>

返回值

返回一个 CheckInResponse 对象。

接口

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

用法示例

try {
 const response = await client.checkIn()
} catch (error) {
 // handle error
}

`exitCheckIn`

向服务器发出信号，表明消费者已选择离开签到队列。在本地更新 check_in_status。调用此方法后，使用方在当前签入周期内不会收到代理连接。

方法签名

exitCheckIn(): Promise<CheckInResponse>

返回值

返回一个 CheckInResponse 对象。

接口

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

用法示例

try {
 const response = await client.exitCheckIn()
} catch (error) {
 // handle error
}

`notifyCheckInState`

向服务器告知签到模态窗口的当前可见性状态，即微件是否已最小化或浏览器标签页是否处于非活动状态。服务器会使用此信息来决定签到时间。当 chat.checkInRequested 事件处于活动状态时，只要 widget 的可见性或标签页焦点发生变化，就应调用此方法。

方法签名

notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>

接口

interface CheckInVisibilityStateRequest {
 widget_minimized?: boolean;
 tab_inactive?: boolean;
}

用法示例

try {
 const visibilityState = {
   widget_minimized: true,
   tab_inactive: false,
 }
 await client.notifyCheckInState(visibilityState)
} catch (error) {
 // handle error
}

`rejoinChat`

如果消费者未能在规定时间内确认签到，系统会将其重新放入队列中。在本地更新 check_in_status。如果消费者仍想连接，请使用此方法来响应 chat.checkInTimedOut 事件。

方法签名

rejoinChat(): Promise<CheckInResponse>

返回值：返回 CheckInResponse 对象。

接口

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

用法示例

try {
 const response = await client.rejoinChat()
} catch (error) {
 // handle error
}

`trackCheckInEvent`

通知服务器已向消费者显示签到模态窗口。在响应 chat.checkInRequested 而显示签到界面后，立即调用此方法一次。服务器会使用该信息对签到展示率进行运营分析。该调用在内部等待，并返回一个可能被拒绝的 Promise<void>，因此请将其封装在 try/catch 中（如以下示例所示）。

方法签名

trackCheckInEvent(): Promise<void>

用法示例

try {
 await client.trackCheckInEvent()
} catch (error) {
 // handle error
}

getMessageAttachment

提取与特定聊天消息关联的符合条件的附件。仅在消息由非最终用户 ($userType !== 'end_user') 发送且属于受支持的附件类型（照片、视频、音频、文档）时提取。对于不满足这两个条件的任何消息（而不仅仅是没有 media_id 的消息），返回 null。在检索后将提取的文件保存到对话的本地媒体缓存。

方法签名

getMessageAttachment(message: MessageResponse): Promise<File | null>

返回值

如果找到，则返回 File 对象；如果不适用，则返回 null。

用法示例

try {
 const file = await client.getMessageAttachment(message)
} catch (error) {
 // handle error
}

createChat

为指定菜单创建新的对话会话。您可以选择指定语言、问候语、触发器 ID、工单 ID 以及要随聊天发送的自定义数据。

在初始 API 调用之后，该方法会轮询服务器，直到 provider_channel_id 可用或对话被取消或结束。如果提供商渠道可用，该方法会启动与实时提供商的连接。当 promise 解析时，连接可能仍在完成中 - 监听 chat.connectedMessages 事件，以了解连接和初始消息检索何时完成。

方法签名

createChat(menuId: number | string, data: ChatRequest): Promise<Chat>

返回值

返回 Chat 实例。

接口

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
}

用法示例

try {
 const chat = await client.createChat(123, { lang: 'en' })
} catch (error) {
 // handle error
}

loadChat

通过 ID 检索现有对话会话。

如果加载的对话不再进行，该方法会从本地存储空间中清除存储的对话 ID 和共同浏览 Nonce。在发生错误时，它也会执行此操作，因此调用方无需在加载失败后手动清理存储空间。

方法签名

loadChat(chatId: number | string): Promise<Chat>

返回值

返回 Chat 实例。

用法示例

try {
 const chat = await client.loadChat(1234)
} catch (error) {
 // handle error
}

loadOngoingChat

尝试加载当前正在进行的聊天会话（如果存在）。如果未找到正在进行的对话，则返回 null。

方法签名

loadOngoingChat(): Promise<Chat | null>

返回值

如果找到，则返回 Chat 实例；如果不存在正在进行的对话，则返回 null。如果对话未在进行中，则会清除存储值。

用法示例

try {
 const chat = await client.loadOngoingChat()
} catch (error) {
 // handle error
}

resumeChat

根据 ID 恢复之前关闭的对话，以便消费者继续对话。

如果客户端已持有对具有相同 ID 的对话的引用，则该方法会短路：它会将现有实例的状态修补为 queued，而不是提取新实例。如果 ID 不匹配，系统会创建并注册一个新的 Chat 实例。

方法签名

resumeChat(chatId: number | string): Promise<Chat>

返回值

返回 Chat 实例。

用法示例

try {
 const chat = await client.resumeChat(1234)
} catch (error) {
 // handle error
}

finishChat

将当前对话会话的状态设置为“已结束”。这将从消费者的角度结束对话。

如果聊天在 PATCH 后既连接到实时提供商，又处于结束状态，该方法还会与提供商断开连接。如果只是为了得体地结束对话，调用方无需调用 destroyChat。

方法签名

finishChat(): Promise<void>

用法示例

try {
 await client.finishChat()
} catch (error) {
 // handle error
}

destroyChat

完成并销毁当前聊天会话，清理所有内部状态。这会在内部调用 finishChat，然后销毁对话实例。在结束对话之前，该方法会将其静音（抑制传入的实时事件），以避免在拆解过程中处理消息。在聊天销毁后清除内部跟踪 ID。

方法签名

destroyChat(): Promise<void>

用法示例

try {
 await client.destroyChat()
} catch (error) {
 // handle error
}

fetchMessages

从实时提供程序中检索当前聊天会话的消息记录。应在聊天连接后调用；如果在聊天连接之前调用，则会返回空数组，而不是抛出异常。自动提取任何 document 类型消息的文档网址，并将其合并到响应中。对于 server_message 类型的消息，提取任务虚拟客服消息内容并以内嵌方式设置其格式。失败时返回空数组，而不是抛出异常。

方法签名

fetchMessages(): Promise<MessageResponse[]>

返回值

返回 MessageResponse 数组。失败时返回空数组。

接口

interface MessageResponse {
  $index: number;
  $sid: string;
  $timestamp: Date;
  $userType: string;
  $userId: number;
  type: string;
  content?: string;
  event?: string;
  file?: File;
  media_id?: number;
  groupMessageId?: number;
  document?: {
    url: string;
  };
  unredacted?: string;
  buttons?: {
    title: string;
  }[];
  message?: { messages: string[], type };
  signature?: string,
  form?: {
    id: number,
    form_type: string,
    name: string,
    title: string,
    subtitle: string,
    external_form_id: string,
    smart_action_id: number,
    image: string
  }

  // allow extra parameters
  [key: string]: unknown;
}

用法示例

const messages = await client.fetchMessages()

sendTextMessage

在当前对话中发送短信。

该方法会在发送前对原始内容进行清理，如果结果为空，则会提前返回（不执行任何操作）。如果聊天处于任务虚拟客服流程 (inTask) 中，则消息会通过任务虚拟客服端点（而非普通渠道）进行路由。如果启用了服务器端隐去功能，系统会使用服务器端点发送消息，而不是直接通过实时提供商发送。

方法签名

sendTextMessage(rawContent: string): Promise<void>

用法示例

try {
 await client.sendTextMessage("hello world")
} catch (error) {
 // handle error
}

sendFileMessage

通过三步流程将文件上传到当前对话会话：从服务器获取预签名的 Cloud Storage 网址，将文件直接上传到该网址，然后向服务器确认上传。上传路径会根据文件的 MIME 类型自动确定：图片会作为照片消息发送，视频会作为视频消息发送；其他文件类型会根据其 MIME 类型进行路由。成功时返回消息 ID，失败时返回 -1。

方法签名

sendFileMessage(file: File): Promise<number>

返回值

返回消息 ID，如果上传失败，则返回 -1。不过，后续的消息发送仍可能会被拒绝（例如 ChatEndedError），因此除了检查 -1 之外，还要将调用封装在 try/catch 中。

用法示例

const input = document.querySelector('input[type="file"]')
const file = input.files[0]
try {
  const id = await client.sendFileMessage(file)
  if (id === -1) {
    // handle upload failure
  }
} catch (error) {
  // handle message-send failure
}

sendPreviewMessage

在当前对话中发送预览消息。预览消息通常用于在消息提交之前向代理显示消费者正在输入的内容。如果聊天状态中的 redaction_enabled 和 agent_incoming_ha_enabled 均为 true，则预览会通过服务器端点 (POST /chats/{id}/redact_messages) 而不是实时提供商渠道发送。

方法签名

sendPreviewMessage(content: string): Promise<void>

用法示例

try {
 await client.sendPreviewMessage('preview content')
} catch (error) {
 // handle error
}

getChatDeflection

检索当前聊天会话的聊天转移配置，包括是否启用转移、等待时间阈值以及可用的转移选项。

如果未为对话启用偏转（服务器响应的 enabled 字段为 false），则返回 null。调用方应在读取响应之前进行 null 检查。

方法签名

getChatDeflection(): Promise<ChatDeflectionResponse | null>

返回值

如果未为聊天启用偏转，则返回 ChatDeflectionResponse 对象或 null。

接口

interface ChatDeflectionResponse {
 enabled: boolean;
 threshold: number;
 email: boolean;
 keep_waiting: boolean;
 external_deflection_links: {
   enabled: boolean;
   ids: number[];
 };
}

用法示例

try {
 const deflection = await client.getChatDeflection()
} catch (error) {
 // handle error
}

sendChatTranscripts

将当前聊天记录发送到指定的邮箱。

方法签名

sendChatTranscripts(emails: string[]): Promise<void>

用法示例

try {
 await client.sendChatTranscripts([
   "name1@example.com",
   "name2@example.com",
 ])
} catch (error) {
 // handle error
}

downloadChatTranscript

以 PDF 格式下载当前对话记录。返回一个转写对象，该对象可与 getPdfStatus 搭配使用，以跟踪生成进度。

方法签名

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

返回值

返回转写内容对象。

接口

interface GenerateTranscriptResponse {
 status: string;
 chat_transcript_id: number;
}

用法示例

try {
 const resp = await client.downloadChatTranscript()
} catch (error) {
 // handle error
}

getPdfStatus

检查之前请求的聊天记录 PDF 的生成状态。使用 downloadChatTranscript 返回的 chat_transcript_id 轮询完成情况。

方法签名

getPdfStatus(id: number): Promise<RequestReturn>

返回值

返回 PDF 状态对象。

接口

interface RequestReturn {
   //...
   headers,
   data: PdfStatusResponse,
 }


 interface PdfStatusResponse {
   status: string;
   body?: File;
   failed_reason?: string;
 }

用法示例

const response = await client.getPdfStatus(pdfId)
// check header for status
const status = response.headers['x-transcript-status'];
// otherwise use status on data
const data = response.data
console.log(data.status)

getChatSurvey

检索为当前聊天会话配置的聊天后调查问卷问题。调查问卷会在对话结束后向消费者显示。

方法签名

getChatSurvey(): Promise<ChatSurveyResponse | null>

返回值

返回 ChatSurveyResponse 对象或 null。

接口

interface QuestionItem {
 id: number;
 type: "csat" | "star" | "free-form" | "scale" | "enumeration";
 display_text: string;
 name?: string;
 is_csat?: boolean;
 position?: number;
 valid_answers?: {
   key: string;
   value: string;
 }[]
}
interface ChatSurveyResponse {
 id?: number;
 lang?: string;
 sign_off_display_text: string;
 questions: QuestionItem[];
}

用法示例

try {
 const data = await client.getChatSurvey()
 if (data) {
   console.log(data.questions)
 }
} catch (error) {
 // handle error
}

sendChatSurvey

提交消费者对聊天后调查问卷的回答。每个答案都由问题 ID 键控。

方法签名

sendChatSurvey(answers: SurveyAnswers): Promise<void>

接口

interface SurveyAnswers {
 [question_id: string]: number | string;
}

用法示例

try {
 await client.sendChatSurvey({
   123: "a",
   231: "b",
 })
} catch (error) {
 // handle error
}

sendChatRate

提交消费者对聊天会话的评分和可选反馈。在聊天后反馈类型为评分而非完整调查问卷时使用。

方法签名

sendChatRate(data: RateRequest): Promise<void>

接口

interface RateRequest {
 rating: number;
 feedback?: string;
}

用法示例

try {
 await client.sendChatRate({
   rating: 5,
   feedback: "Very good service",
 })
} catch (error) {
 // handle error
}

escalateChat

将当前对话从虚拟客服升级为人工客服。

方法签名

escalateChat(data?: EscalateRequest): Promise<void>

接口

interface EscalateRequest {
 force_escalate: boolean;
 menu_id: number;
 lang: string;
}

用法示例

try {
 // Escalate to a specific menu in a given language
 await client.escalateChat({
   force_escalate: true,
   menu_id: 123,
   lang: 'en',
 })
} catch (error) {
 // handle error
}
// Or, escalate without arguments to use defaults
try {
 await client.escalateChat()
} catch (error) {
 // handle error
}

trackChatEscalation

跟踪聊天上报事件，记录上报 ID 和上报到的渠道。

方法签名

trackChatEscalation(escalationId: number, channel: string): Promise<void>

用法示例

try {
 await client.trackChatEscalation(escalationId, channel)
} catch (error) {
 // handle error
}

trackChatEndUserEvent

在对话期间跟踪自定义最终用户事件，该事件可用于分析或触发后端工作流。如果 data 对象不包含 end_user_name，并且经过身份验证的用户个人资料中包含姓名，则系统会在发送请求之前自动填充该姓名。

方法签名

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

返回值

返回 void。

接口

interface ChatEndUserEventRequest {
  event: {
    name: string;
    payload: Record<string, string>;
  };
  end_user_name?: string;
}

用法示例

try {
 await client.trackChatEndUserEvent({
   event: {
     name: 'add_to_cart',
     payload: {
       product_id: 'sku-1234',
       quantity: '2',
     },
   },
   // end_user_name is auto-populated from the authenticated user
   // profile if omitted
 })
} catch (error) {
 // handle error
}

getChatHistory

检索消费者过去的聊天记录，包括消息内容和元数据。结果已分页。第 1 页最多返回 2 个对话；后续页面各返回 1 个对话。这种不对称分页是特意设计的，可让首次调用预加载相邻的历史记录上下文。

方法签名

getChatHistory(page?: number): Promise<ChatHistoryResponse | null>

返回值

返回 ChatHistoryResponse 对象或 null。

接口

interface ChatHistoryItem {
 comm_id: number;
 assigned_at: string;
 comm_type: string;
 timezone: string;
 entries: MessageResponse[];
 [key: string]: unknown;
}
interface ChatHistoryResponse {
 chats: ChatHistoryItem[];
 missing_chat_ids: number[];
 pagination: {
   next_page: number;
   per_page: number;
 }
}

用法示例

try {
 const data = await client.getChatHistory(1) // page defaults to 1 if omitted
 console.log(data)
} catch (error) {
 console.log(error)
}

电子邮件

名称	说明
`createEmail`	向给定菜单 ID 的电子邮件渠道发送电子邮件。
`getProhibitedFileTypes`	获取电子邮件附件的禁止文件类型。

createEmail

向与给定菜单关联的电子邮件渠道发送电子邮件。消费者可以添加姓名、电子邮件地址、邮件正文和可选的文件附件。

方法签名

createEmail(menuId: number | string, data: EmailRequest): Promise<EmailResponse>

返回值

无论失败还是成功，都会返回一个 EmailResponse 对象。

接口

interface EmailRequest {
 name?: string;
 email: string;
 content: string;
 lang?: string;
 files?: File[];
 recaptcha?: string;
}
interface EmailResponse {
 id: number;
 type: string;
 status: string;
 fail_reason: string;
 attachment_count: number;
}

用法示例

try {
 await client.createEmail(123, {
   lang: "en",
   name: "User name",
   email: "name@example.com",
   content: "description of the question",
   files: input.files,
 })
} catch (error) {
 console.log(error.message)
}

getProhibitedFileTypes

检索管理员配置的不允许作为电子邮件附件的文件类型列表。

方法签名

getProhibitedFileTypes(): Promise<FileTypeItem[]>

返回值

返回 FileTypeItem 数组。

接口

interface FileTypeItem {
 extension: string;
 description: string;
}

用法示例

try {
 const types = await client.getProhibitedFileTypes()
} catch (error) {
 // handle error
}

屏幕共享

名称	说明
`createCobrowseCode`	生成共同浏览代码。
`startCobrowse`	请求共同浏览会话。
`restoreCobrowseSession`	在浏览器窗口重新打开后恢复共同浏览会话。

createCobrowseCode

生成一个唯一的共同浏览（屏幕共享）会话代码，该代码可与客服人员共享，以发起会话。初始化 cobrowse 客户端（如果尚未初始化）。重复使用存储空间中的任何现有 Nonce，而不是在每次调用时生成新的 Nonce，以便在网页加载时检索相同的会话代码。

方法签名

createCobrowseCode(lang?: string, customData?: Record<string, string>): Promise<string>

返回值

返回共同浏览代码字符串，如果失败，则返回空字符串 ('')。

用法示例

const code = await client.createCobrowseCode()
// 123456

startCobrowse

在活跃聊天期间，从最终用户端请求启动共同浏览（屏幕共享）会话。

方法签名

startCobrowse(from?: string): Promise<void>

用法示例

try {
 await client.startCobrowse()
} catch (error) {
 // handle error
}

restoreCobrowseSession

尝试在浏览器窗口重新打开或微件重新加载后恢复之前处于活动状态的共同浏览会话。

方法签名

restoreCobrowseSession(): Promise<void>

返回值

返回 Promise<void>。如果未在客户端选项中启用共同浏览，或者存储空间中不存在之前的共同浏览会话，则此方法为无操作（立即返回，不报错）。

用法示例

// Safe to call unconditionally - will no-op if cobrowse is not enabled
// or if no previous session exists
await client.restoreCobrowseSession()

会话后虚拟客服

名称	说明
`updatePostSession`	设置正在进行的对话的会话后状态。

updatePostSession

此方法用于更新正在进行的对话的会话后虚拟客服状态。

更新当前对话的会话后虚拟客服状态。使用此属性可指示会话后虚拟客服流程的就绪情况、进度或完成情况。
如果 postSessionStatus 为 FINISHED 或 WAITING，则立即返回，不执行任何操作，因为这些转换会在内部处理。
具有专门针对 400 响应中的 IN_PROGRESS 状态的内部重试逻辑，因此调用方无需针对这种情况实现自己的重试。

方法签名

updatePostSession(postSessionStatus: PostSessionStatus, optInSelection?: boolean): Promise<void>

接口

enum PostSessionStatus {
 READY = 'ready',
 IN_PROGRESS = 'in_progress',
 WAITING = 'waiting',
 FINISHED = 'finished',
}

用法示例

try {
 // Without opt-in selection
 await client.updatePostSession(PostSessionStatus.READY)
 // With opt-in selection
 await client.updatePostSession(PostSessionStatus.READY, true)
} catch (error) {
 // handle error (e.g., show a notification to the user)
}

调试

名称	说明
`getLogs`	从 SDK 检索内部调试日志。
`printLogs`	将内部调试日志输出到浏览器控制台。

getLogs

检索 SDK 收集的内部调试日志，包括桥接级和根级日志。有助于排查集成问题。

方法签名

getLogs(): Promise<{ bridgeLogs: LogHistoryData[], rootLogs: LogHistoryData[] }>

返回值

返回一个包含两个 LogHistoryData 数组的对象。

接口

interface LogHistoryData {
 date: string;
 channel: string;
 level: string;
 args: any[];
}

细化程度

每个 LogHistoryData 条目都会捕获一个日志事件：

date - 事件的 ISO 8601 时间戳。
channel - 发出该事件的 SDK 模块（例如，顶级客户端、聊天层、共同浏览层、实时提供商）。
level - 日志严重级别：debug、info、warn 或 error。
args - 日志调用捕获的原始参数。

示例条目：

{
 "date": "2026-05-08T14:02:13.412Z",
 "channel": "Provider",
 "level": "info",
 "args": ["chat connected", { "chatId": 4421 }]
}

确切的渠道和消息内容集可能会在 SDK 版本之间发生变化。将日志视为调试辅助工具，而不是稳定的解析目标 - 不要构建依赖于特定频道名称或消息字符串的生产逻辑。

范围和推荐用途

getLogs 会返回 SDK 内部记录，旨在帮助诊断无头 Web SDK 本身的集成问题。其主要用例是支持诊断：当最终用户报告问题时，您的应用可以捕获 getLogs 的结果，并将其附加到发送给 CCAI Platform 的支持服务工单。

返回的日志不包括：

宿主页面的应用遥测、业务事件或用户导航。
浏览器未向 SDK 显示的网络故障（例如 CORS、混合内容或证书错误）。
服务器端请求跟踪记录或后端详细信息（不限于返回给 SDK 的 HTTP 状态）。

getLogs不能替代您自己的可观测性工具。我们建议将该 SDK 与以下各项搭配使用：

浏览器端错误/RUM 跟踪器（Sentry、Datadog Browser RUM、New Relic Browser 或同等工具）。
身份验证端点（SDK 调用的 authenticate 回调）上的服务器端日志记录。
chat.disconnected、chat.timeout 和 chat.ended 上的应用级监听器（如果您需要将聊天生命周期信号转发到自己的遥测流水线）。

用法示例

try {
 const { bridgeLogs, rootLogs } = await client.getLogs()
 console.log('Bridge logs:', bridgeLogs)
 console.log('Root logs:', rootLogs)
} catch (error) {
 // handle error
}

printLogs

将所有内部调试日志直接输出到浏览器控制台。这是一种便捷方法，可在内部调用 getLogs() 并设置输出格式。

方法签名

printLogs(): Promise<void>

用法示例

try {
 await client.printLogs()
} catch (error) {
 // handle error
}

其他

名称	说明
`runTrigger`	检查主动触发器，看看是否有任何触发器应该触发。
`getAfterHourMessage`	获取非营业时间转移消息。

runTrigger

遍历已配置的主动触发器，并针对满足条件（网址关键字、网页访问次数、停留时间、访问者类型）的触发器调用提供的回调。

方法签名

runTrigger(cb: (trigger: TriggerItem) => void): Promise<void>

接口

interface TriggerItem {
 id: number;
 menu_id: number;
 messages: TriggerMessage[];
 keywords_included?: string[];
 keywords_included_or?: string[][];
 keywords_excluded?: string[];
 keywords_excluded_or?: string[][];
 lang?: string;
 page_visit_count: number;
 stay_time: number;
 visitor_type: string;
}
interface TriggerMessage {
 lang: string;
 text: string;
}

用法示例

await client.runTrigger((trigger: TriggerItem) => {
 // code to run for given trigger
})

getAfterHourMessage

返回配置的转移消息，以便在请求的渠道处于营业时间之外时显示。

方法签名

方法签名为：

getAfterHourMessage(lang?: string): Promise<string>

返回值

返回包含已配置消息的字符串。

用法示例

try {
 const message: string = await client.getAfterHourMessage()
} catch (error) {
 // handle error
}

无头 Web SDK API 方法 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

公司和菜单

方法

公司和菜单

getCompany

方法签名

返回值

接口

用法示例

getMenus

方法签名

返回值

接口

用法示例

getWaitTimes

方法签名

返回值

接口

用法示例

通话

createCall

方法签名

返回值

接口

用法示例

loadCall

方法签名

返回值

接口

用法示例

cancelCall

方法签名

返回值

接口

用法示例

getTimeSlots

方法签名

返回值

接口

用法示例

fetchTimeSlotAvailability

范围

方法签名

返回值

用法示例

聊天

Chat 签到

checkIn

方法签名

返回值

接口

用法示例

exitCheckIn

方法签名

返回值

接口

用法示例

notifyCheckInState

方法签名

接口

用法示例

rejoinChat

方法签名

接口

用法示例

trackCheckInEvent

方法签名

用法示例

getMessageAttachment

方法签名

返回值

用法示例

createChat

方法签名

返回值

接口

用法示例

loadChat

方法签名

返回值

无头 Web SDK API 方法

`checkIn`

`exitCheckIn`

`notifyCheckInState`

`rejoinChat`

`trackCheckInEvent`