Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

無頭網頁 SDK API 方法

本頁列出無頭網頁 SDK 適用的 API 方法。

處理公司價值和選單的方法。

方法

Headless SDK 提供多種方法，可在用戶端執行個體上呼叫。

例如：

公司和選單

方法名稱	說明
getCompany	擷取已設定的公司資訊。
getMenus	列出指定租戶的所有可用選單。
getWaitTimes	取得選單上各個管道目前的等待時間。

getCompany

擷取已驗證執行個體的設定公司資訊，包括公司名稱、支援的語言和功能設定。這個方法也會將內部執行個體 ID (OPTIONS.tenant) 設為副作用，因此通常是在建構用戶端後進行的第一個呼叫。

方法簽章

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 欄位。系統會根據 scheduled_at 是否存在，自動判斷呼叫類型 (web_instant_call 或 web_scheduled_call)。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

這個方法會檢查指定選單是否有可用時段，不會擷取完整的時段清單。這項功能可用於在 UI 中有條件地顯示排程選項。

範圍

fetchTimeSlotAvailability僅適用於預約語音通話 (回電) 預約。不會傳回即時通訊、電子郵件或即時通話管道的資訊。提供的選單必須設定為支援排定的語音通話，並定義營業時間，且至少有一名服務專員排入該選單的佇列。

常見用途：

只有在有空檔時，才顯示「安排回電」行動號召。
在沒有空檔時，分支至偏轉流程 (例如電子郵件、非營業時間訊息)，而不必支付完整 getTimeSlots 通話的費用。
使用 rescheduleCallId 呼叫 getTimeSlots 之前，先預檢重新排程動作。

方法簽章

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 簽到

「確認」功能會要求消費者確認已準備就緒，再與服務專員聯絡。本節說明如何使用無頭網頁 SDK 方法，實作這項體驗。如要瞭解什麼是簽到、如何啟用和設定 (等待時間、逾時、佇列位置、重新加入行為) 以及報表，請參閱「Chat 簽到」。

名稱	說明
`checkIn`	向伺服器傳送信號，確認使用者在等候室中。
`exitCheckIn`	將使用者從報到佇列中移除。
`notifyCheckInState`	通知後端報到互動視窗的顯示狀態。
`rejoinChat`	如果使用者未確認報到，系統會將他們重新加入等候清單。
`trackCheckInEvent`	當 UI 觸發簽到事件時，向後端發出信號。

`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 事件有效時，只要小工具的可見度或分頁焦點變更，就應呼叫此方法。

方法簽章

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`

通知伺服器，系統已向消費者顯示報到互動視窗。在顯示報到 UI 以回應 chat.checkInRequested 後，請立即呼叫此方法一次。伺服器會使用這項資訊，對報到出示率進行作業分析。呼叫會在內部等待，並傳回可能拒絕的 Promise<void>，因此請將其包裝在 try/catch 中 (如以下範例所示)。

方法簽章

trackCheckInEvent(): Promise<void>

應用實例

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

getMessageAttachment

擷取與特定即時通訊訊息相關聯的合格附件。只有在訊息是由非使用者 ($userType !== 'end_user') 傳送，且屬於支援的附件類型 (相片、影片、音訊、文件) 時，才會擷取。如果郵件不符合這兩項條件，系統會傳回 null，不只是沒有 media_id 的郵件。擷取後，將擷取的檔案儲存至即時通訊的本機媒體快取。

方法簽章

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

傳回值

如果找到，則傳回 File 物件；如果不適用，則傳回空值。

應用實例

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 例項；如果沒有進行中的即時通訊，則傳回空值。如果沒有進行中的對話，則會清除儲存空間值。

應用實例

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 欄位為 falsy)，則傳回 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 物件或空值。

介面

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>

傳回值

傳回無效值。

介面

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

產生專屬的共同瀏覽 (分享螢幕畫面) 工作階段代碼，可與服務專員分享，以便發起工作階段。如果尚未初始化，則初始化共同瀏覽用戶端。重複使用儲存空間中的現有 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 內部記錄，協助診斷無頭網頁 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
}

無頭網頁 SDK API 方法 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

公司和選單

方法

公司和選單

getCompany

方法簽章

傳回值

介面

應用實例

getMenus

方法簽章

傳回值

介面

應用實例

getWaitTimes

方法簽章

傳回值

介面

應用實例

通話

createCall

方法簽章

傳回值

介面

應用實例

loadCall

方法簽章

傳回值

介面

應用實例

cancelCall

方法簽章

傳回值

介面

應用實例

getTimeSlots

方法簽章

傳回值

介面

應用實例

fetchTimeSlotAvailability

範圍

方法簽章

傳回值

應用實例

即時通訊

Chat 簽到

checkIn

方法簽章

傳回值

介面

應用實例

exitCheckIn

方法簽章

傳回值

介面

應用實例

notifyCheckInState

方法簽章

介面

應用實例

rejoinChat

方法簽章

介面

應用實例

trackCheckInEvent

方法簽章

應用實例

getMessageAttachment

方法簽章

傳回值

應用實例

createChat

方法簽章

傳回值

介面

應用實例

loadChat

方法簽章

傳回值

無頭網頁 SDK API 方法

`checkIn`

`exitCheckIn`

`notifyCheckInState`

`rejoinChat`

`trackCheckInEvent`