無頭網頁 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
}

getAfterHourMessage

這個方法會擷取非營業時間的轉接訊息。

要求參數：

(lang?: string)

範例：

const message: string = await client.getAfterHourMessage()

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
}

通話

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

使用範例

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

這個方法用於取得可預約的時段。

方法簽章

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

傳回值

傳回字串陣列 (時段)。

使用方式範例

try {
  const slots = await client.getTimeSlots(123)
} catch (error) {
  // handle error
}

即時通訊

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

方法簽章

sendPreviewMessage(content: string): Promise<void>

使用方式範例

try {
  await client.sendPreviewMessage('preview content')
} 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
}

getMessageAttachment

方法簽章

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

傳回值

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

使用方式範例

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

會後虛擬服務專員

updatePostSession

方法簽章

updatePostSession(postSessionStatus: PostSessionStatus): Promise<void>

介面

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

使用方式範例

try {
  await client.updatePostSession(PostSessionStatus.READY)
} 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 列舉

其他

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
}