無頭網頁 SDK API 方法

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

公司和菜單

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

getTrigger

這個方法會偵測目前網頁的主動觸發條件。系統會傳回目前相符的觸發條件或 null。

const trigger = await client.getTrigger()

getCompany

這個方法會擷取公司資訊。

方法簽章

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;
  cobrowse_domain?: string;
}

使用方式範例

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

getMenus

這個方法會列出租戶可用的所有選單項目。

方法簽章

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

傳回值

傳回 MenuResponse 物件。

介面

interface MenuResponse {
  menus: MenuItem[];
  direct: {
    key: boolean;
    user: boolean;
  };
}

interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
}

使用方式範例

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>

傳回值

傳回 WaitTimeResponse 物件。

介面

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

使用方式範例

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

通話

透過 SDK 處理排定呼叫的方法。

createCall

這個方法會建立即時或排定的通話。

方法簽章

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;
  use_advanced_call_scheduling?: boolean;
}

使用範例

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

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

這個方法會取消通話。

方法簽章

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 選項物件呼叫時，這個方法支援下列項目：

  • 進階通話排程： useAdvancedCallScheduling: true

  • 如何重新安排現有通話：rescheduleCallId

系統仍支援已淘汰的 lang 字串簽章，並會將其導向相同端點，但只會填入 lang。

方法簽章

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

傳回值

傳回時間間隔字串的陣列。

介面

interface GetTimeSlotsRequest {
  lang?: string;
  rescheduleCallId?: number;          // ID of an existing call being rescheduled
  useAdvancedCallScheduling?: boolean; // Enable advanced call scheduling behavior
}

使用方式範例

// New options-based signature (recommended)
try {
  const slots = await client.getTimeSlots(123, {
    lang: 'en',
    useAdvancedCallScheduling: true,
  })
} catch (error) {
  // handle error
}

// Deprecated signature (still supported)
try {
  const slots = await client.getTimeSlots(123, 'en')
} catch (error) {
  // handle error
}

fetchTimeSlotAvailability

這個方法會檢查特定菜單是否有可用時段，而不必擷取完整時段清單。您可以使用這個屬性，有條件地從 UI 顯示排程選項。

方法簽章

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
}

即時通訊

使用 SDK 處理即時通訊的方法。

createChat

這個方法會建立新的對話。

方法簽章

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 = client.createChat(123, { lang: 'en' })
} catch (error) {
  // handle error
}

loadChat

這個方法會擷取指定對話 ID 的對話資訊。

方法簽章

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

傳回值

傳回 Chat 例項。

使用範例

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

loadOngoingChat

這個方法用於取得進行中的對話執行個體。

方法簽章

loadOngoingChat(): Promise<Chat | null>

傳回值

如果找到進行中的即時通訊，則傳回 Chat 例項；如果沒有，則傳回空值。如果對話未進行中，則清除儲存空間值。

使用方式範例

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

resumeChat

這個方法會繼續已關閉的對話。

方法簽章

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

傳回值

傳回即時通訊例項。

使用方式範例

client.resumeChat(1234)

finishChat

這個方法會將即時通訊狀態變更為 finished。

方法簽章

finishChat(): Promise<void>

使用方式範例

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

destroyChat

這個方法會終止目前進行中的對話。

方法簽章

destroyChat(): Promise<void>

使用方式範例

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

fetchMessages

這個方法用於取得所有先前的訊息。如果發生失敗，系統會傳回空白陣列。連線後即可使用此方法。

方法簽章

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: string;
  };
  signature: string;
  form?: {
    id: number;
    form_type: string;
    name: string;
    title: string;
    subtitle: string;
    external_form_id: string;
    smart_action_id: number;
    image: string;
  };
}

使用方式範例

const messages = client.fetchMessages()

sendTextMessage

這個方法會傳送簡訊。

方法簽章

sendTextMessage(rawContent: string): Promise<void>

使用方式範例

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

sendFileMessage

這個方法會傳送檔案訊息。

方法簽章

sendFileMessage(file: File): Promise<number>

傳回值

傳回訊息 ID，失敗則傳回 -1。

使用方式範例

const input = document.querySelector('input[type="file"]')
const file = input.files[0]
const id = client.sendFileMessage(file)

sendPreviewMessage

用於將訊息預覽畫面傳送至服務專員介面卡。只有在呼叫 startTyping 方法時，代理程式介面卡才會顯示預覽訊息。預覽訊息只會顯示到傳送最終訊息或呼叫 stopTyping 方法為止。詳情請參閱「代理程式體驗 - 訊息預覽」。

方法簽章

sendPreviewMessage(content: string): Promise<void>

使用方式範例

client.chat.startTyping();
clearTimeout(stopTimer);
stopTimer = setTimeout(() => {
    if (client.chat) {
        client.chat.stopTyping();
    }
}, 5000);

clearTimeout(previewTimer);
const currentTime = Date.now();

if (currentTime - lastPreviewTime >= 2000) {
    lastPreviewTime = currentTime;
    try {
        const response = await client.sendPreviewMessage("chat message");
    } catch (error) {
        console.error("Error sending preview message:", error);
    }
} else {
    previewTimer = setTimeout(async () => {
        lastPreviewTime = Date.now();
        try {
            const response = await client.sendPreviewMessage("chat message");
        } catch (error) {
            console.error("Error sending debounced preview message:", error);
        }
    }, 1000);
}

startTyping

方法簽章

startTyping()

使用方式範例

try {
  client.startTyping()
} catch (error) {
  // handle error
}

stopTyping

方法簽章

stopTyping()

使用方式範例

try {
  client.stopTyping()
} catch (error) {
  // handle error
}

getChatDeflection

這個方法會取得即時通訊轉移設定。

方法簽章

getChatDeflection(): Promise<ChatDeflectionResponse>

傳回值

傳回 ChatDeflectionResponse 物件。

介面

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 {
  client.sendChatTranscripts([
    "name1@example.com",
    "name2@example.com",
  ])
} catch (error) {
  // handle error
}

downloadChatTranscript

方法簽章

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

傳回值

傳回轉錄稿物件。

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

使用方式範例

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

getPdfStatus

方法簽章

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 = resp.headers['x-transcript-status'];

// otherwise use status on data
const data: PdfStatusResponse = resp.data
console.log(data.status)

getChatSurvey

這個方法用於取得即時通訊問卷調查問題。

方法簽章

getChatSurvey(): Promise<ChatSurveyResponse>

傳回值

傳回 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()
  console.log(data.questions)
} catch (error) {
  // handle error
}

sendChatSurvey

這個方法會傳送問卷調查給消費者。

方法簽章

sendChatSurvey(answers: SurveyAnswers): 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 {
  reason?: string;
  // ...other escalation fields
}

使用方式範例

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

trackChatEscalation

方法簽章

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

使用方式範例

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

trackChatEndUserEvent

方法簽章

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

傳回值

傳回 void。

介面

interface ChatEndUserEventRequest {
  end_user_name?: string;
  // ...other event fields
}

使用方式範例

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

getChatHistory

方法簽章

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

傳回值

傳回 ChatHistoryResponse 物件。

介面

interface ChatHistoryItem {
  comm_id: number;
  assigned_at: string;
  comm_type: string;
  timezone: string;
  entries: MessageResponse[];

}
interface ChatHistoryResponse {
  chats: ChatHistoryItem[];
  missing_chat_ids: number[];
  pagination: {
    next_page: number;
    per_page: number;
  }
}

使用方式範例

try {
  const data = client.getChatHistory(page: number)
  console.log(data)
} catch (error) {
  console.log(error)
}

電子郵件

處理支援電子郵件的方法。

createEmails

方法簽章

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

這個方法會建立螢幕分享代碼。

方法簽章

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()

getMessageAttachment

方法簽章

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

傳回值

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

使用方式範例

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

會後虛擬服務專員

處理會後虛擬代理的方法。

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)
}

相關介面

interface ChatResponse {
  //...
  post_session_required?: boolean;
  post_session_opt_in_required?: boolean;
  post_session_transfer_status?: string;
}
  • post_session_required：對話後必須進行會後作業。
  • post_session_opt_in_required：如果啟用選擇加入功能。
  • post_session_transfer_status：PostSessionStatus 列舉。

偵錯

用於偵錯 SDK 的方法。

getLogs

擷取 SDK 收集的內部偵錯記錄，包括橋接器層級和根層級記錄。有助於排解整合問題。

方法簽章

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

傳回值

傳回包含兩個 LogHistoryData 陣列的物件。

介面

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

使用方式範例

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

直接在瀏覽器控制台列印所有內部偵錯記錄。這項便利方法會在內部呼叫 getLogs()，並格式化輸出內容。

方法簽章

printLogs(): Promise<void>

使用方式範例

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

其他

其他 SDK 方法。

runTrigger

方法簽章

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

使用方式範例

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
}