无头 Web SDK API 方法

本页列出了适用于无头 Web 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 实例；如果没有正在进行的对话，则返回 null。如果聊天未在进行中，则清理存储值。

使用示例

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
}