Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

无头 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
}

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 options 对象调用此方法，则该方法支持以下功能：

高级通话安排： 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

此方法用于检查指定菜单是否有可用的时间段，而无需提取完整的时间段列表。您可以使用它来有条件地显示界面中的安排选项。

方法签名

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 实例；如果没有正在进行的对话，则返回 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

用于向代理适配器发送消息预览。仅当调用 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

此方法尝试在浏览器窗口重新打开或 widget 重新加载后恢复之前处于活动状态的屏幕共享会话。

方法签名

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
}

printLogs

直接将所有内部调试日志输出到浏览器控制台。这是一个便捷方法，可在内部调用 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
}

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

公司和菜单

getTrigger

getCompany

getMenus

getWaitTimes

通话

createCall

loadCall

cancelCall

getTimeSlots

fetchTimeSlotAvailability

聊天

createChat

loadChat

loadOngoingChat

resumeChat

finishChat

destroyChat

fetchMessages

sendTextMessage

sendFileMessage

sendPreviewMessage

startTyping

stopTyping

getChatDeflection

sendChatTranscripts

downloadChatTranscript

getPdfStatus

getChatSurvey

sendChatSurvey

sendChatRate

escalateChat

trackChatEscalation

trackChatEndUserEvent

getChatHistory

电子邮件

createEmails

getProhibitedFileTypes

屏幕共享

createCobrowseCode

startCobrowse

restoreCobrowseSession

getMessageAttachment

会话后虚拟代理

updatePostSession

调试

getLogs

printLogs

其他

runTrigger

getAfterHourMessage

无头 Web SDK API 方法