Headless Web SDK API-Methoden

Auf dieser Seite werden die API-Methoden aufgeführt, die für das Headless Web SDK verfügbar sind.

Unternehmen und Speisekarten

Methoden zum Verarbeiten von Unternehmenswerten und Menüs.

getTrigger

Mit dieser Methode werden die proaktiven Trigger der aktuellen Seite erkannt. Es wird entweder der aktuelle übereinstimmende Trigger oder null zurückgegeben.

const trigger = await client.getTrigger()

getCompany

Mit dieser Methode werden die Unternehmensinformationen abgerufen.

Methodensignatur

getCompany(): Promise<CompanyResponse>

Rückgabewert

Gibt ein CompanyResponse-Objekt zurück.

Schnittstellen

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

Beispiel für die Verwendung

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

getMenus

Mit dieser Methode werden alle Menüelemente aufgelistet, die für den Mandanten verfügbar sind.

Methodensignatur

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

Rückgabewert

Gibt ein MenuResponse-Objekt zurück.

Schnittstellen

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

Beispiel für die Verwendung

try {
  const data: MenuResponse = await client.getMenus("direct_menu_key")
  console.log(data.menus)
  console.log(data.direct)
} catch (error) {
  // handle error
}

getWaitTimes

Mit dieser Methode wird die Wartezeit für den Chat- oder Anrufkanal eines Menüs abgerufen.

Methodensignatur

getWaitTimes(menuId: number | string, lang?: string): Promise<WaitTimeResponse>

Rückgabewert

Gibt ein WaitTimeResponse-Objekt zurück.

Schnittstellen

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

Beispiel für die Verwendung

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

Anrufe

Methoden zum Verarbeiten geplanter Anrufe über das SDK.

createCall

Mit dieser Methode wird ein sofortiger oder geplanter Anruf erstellt.

Methodensignatur

createCall(menuId: number | string, data: CallRequest): Promise<CallResponse>

Rückgabewert

Gibt ein CallResponse-Objekt zurück.

Schnittstellen

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

Beispiel für die Verwendung

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

loadCall

Mit dieser Methode werden die Anrufinformationen für eine bestimmte Anruf-ID abgerufen.

Methodensignatur

loadCall(callId: number | string): Promise<CallResponse>

Rückgabewert

Gibt ein CallResponse-Objekt zurück.

Schnittstellen

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

Beispiel für die Verwendung

try {
  const call = await client.loadCall(1234)
} catch (error) {
  // handle error
}

cancelCall

Mit dieser Methode wird ein Anruf abgebrochen.

Methodensignatur

cancelCall(callId: number | string): Promise<CallResponse>

Rückgabewert

Gibt ein CallResponse-Objekt zurück.

Schnittstellen

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

Beispiel für die Verwendung

try {
  const response = await client.cancelCall(1234)
} catch (error) {
  // handle error
}

getTimeSlots

Ruft verfügbare Zeitfenster für geplante Anrufe in einem bestimmten Menü ab.

Wenn diese Methode mit einem GetTimeSlotsRequest-Optionsobjekt aufgerufen wird, unterstützt sie Folgendes:

Die eingestellte Stringsignatur lang wird weiterhin unterstützt und leitet an denselben Endpunkt weiter, wobei nur lang ausgefüllt wird.

Methodensignatur

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

Rückgabewert

Gibt ein Array von Zeitfenster-Strings zurück.

Schnittstellen

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

Beispiel für die Verwendung

// 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

Mit dieser Methode wird geprüft, ob für ein bestimmtes Menü Zeitfenster verfügbar sind, ohne die vollständige Liste der Zeitfenster abzurufen. Damit können Sie Planungsoptionen in der Benutzeroberfläche bedingt einblenden.

Methodensignatur

fetchTimeSlotAvailability(menuId: number | string, lang?: string): Promise<boolean>

Rückgabewert

Gibt true zurück, wenn Zeitblöcke verfügbar sind. Andernfalls false.

Beispiel für die Verwendung

try {
  const isAvailable = await client.fetchTimeSlotAvailability(123, 'en')
  if (isAvailable) {
    // Show scheduling UI
  }
} catch (error) {
  // handle error
}

Chats

Methoden zum Verarbeiten von Chats mit dem SDK.

createChat

Mit dieser Methode wird ein neuer Chat erstellt.

Methodensignatur

createChat(menuId: number | string, data: ChatRequest): Promise<Chat>

Rückgabewert

Gibt eine Chat-Instanz zurück.

Schnittstellen

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
}

Beispiel für die Verwendung

try {
  const chat = client.createChat(123, { lang: 'en' })
} catch (error) {
  // handle error
}

loadChat

Mit dieser Methode werden die Chatinformationen für eine bestimmte Chat-ID abgerufen.

Methodensignatur

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

Rückgabewert

Gibt eine Chat-Instanz zurück.

Beispiel für die Verwendung

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

loadOngoingChat

Mit dieser Methode wird die laufende Chat-Instanz abgerufen.

Methodensignatur

loadOngoingChat(): Promise<Chat | null>

Rückgabewert

Gibt eine Chat-Instanz zurück, falls gefunden, oder „null“, wenn kein laufender Chat vorhanden ist. Löscht Speicherwerte, wenn kein Chat stattfindet.

Beispiel für die Verwendung

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

resumeChat

Mit dieser Methode wird ein geschlossener Chat fortgesetzt.

Methodensignatur

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

Rückgabewert

Gibt eine Chatinstanz zurück.

Beispiel für die Verwendung

client.resumeChat(1234)

finishChat

Mit dieser Methode wird der Chatstatus in finished geändert.

Methodensignatur

finishChat(): Promise<void>

Beispiel für die Verwendung

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

destroyChat

Bei dieser Methode wird der aktuelle Chat beendet.

Methodensignatur

destroyChat(): Promise<void>

Beispiel für die Verwendung

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

fetchMessages

Mit dieser Methode werden alle vorherigen Nachrichten abgerufen. Bei einem Fehler wird ein leeres Array zurückgegeben. Sie verwenden diese Methode, nachdem der Chat verbunden ist.

Methodensignatur

fetchMessages(): Promise<MessageResponse[]>

Rückgabewert

Gibt ein Array von MessageResponse zurück. Gibt bei einem Fehler ein leeres Array zurück.

Schnittstellen

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

Beispiel für die Verwendung

const messages = client.fetchMessages()

sendTextMessage

Mit dieser Methode wird eine SMS gesendet.

Methodensignatur

sendTextMessage(rawContent: string): Promise<void>

Beispiel für die Verwendung

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

sendFileMessage

Mit dieser Methode wird eine Dateinachricht gesendet.

Methodensignatur

sendFileMessage(file: File): Promise<number>

Rückgabewert

Gibt die Nachrichten-ID zurück oder -1 bei einem Fehler.

Beispiel für die Verwendung

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

sendPreviewMessage

Wird verwendet, um eine Nachrichtenvorschau an den Agent-Adapter zu senden. Die Vorschau-Nachricht wird nur im Agent-Adapter angezeigt, wenn die Methode startTyping aufgerufen wird. Die Vorschau wird nur angezeigt, bis die endgültige Nachricht gesendet oder die Methode stopTyping aufgerufen wird. Weitere Informationen finden Sie unter Agent Experience – Message Preview.

Methodensignatur

sendPreviewMessage(content: string): Promise<void>

Beispiel für die Verwendung

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

Methodensignatur

startTyping()

Beispiel für die Verwendung

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

stopTyping

Methodensignatur

stopTyping()

Beispiel für die Verwendung

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

getChatDeflection

Mit dieser Methode wird die Konfiguration für die Chat-Ablenkung abgerufen.

Methodensignatur

getChatDeflection(): Promise<ChatDeflectionResponse>

Rückgabewert

Gibt ein ChatDeflectionResponse-Objekt zurück.

Schnittstellen

interface ChatDeflectionResponse {
  enabled: boolean;
  threshold: number;
  email: boolean;
  keep_waiting: boolean;
  external_deflection_links: {
    enabled: boolean;
    ids: number[];
  };
}

Beispiel für die Verwendung

try {
  const deflection = await client.getChatDeflection()
} catch (error) {
  // handle error
}

sendChatTranscripts

Senden Sie aktuelle Chat-Transkripte an die angegebenen E‑Mail-Adressen.

Methodensignatur

sendChatTranscripts (emails: string[]): Promise<void>

Beispiel für die Verwendung

try {
  client.sendChatTranscripts([
    "name1@example.com",
    "name2@example.com",
  ])
} catch (error) {
  // handle error
}

downloadChatTranscript

Methodensignatur

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Rückgabewert

Gibt das Transkriptobjekt zurück.

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

Beispiel für die Verwendung

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

getPdfStatus

Methodensignatur

getPdfStatus(id: number): Promise<RequestReturn>

Rückgabewert

Gibt das PDF-Statusobjekt zurück.

Schnittstellen

 interface RequestReturn {
    //...
    headers,
    data: PdfStatusResponse,
  }

  interface PdfStatusResponse {
    status: string;
    body?: File;
    failed_reason?: string;
  }

Beispiel für die Verwendung

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

Mit dieser Methode werden die Fragen für die Chat-Umfrage abgerufen.

Methodensignatur

getChatSurvey(): Promise<ChatSurveyResponse>

Rückgabewert

Gibt ein ChatSurveyResponse-Objekt zurück.

Schnittstellen

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

Beispiel für die Verwendung

try {
  const data = await client.getChatSurvey()
  console.log(data.questions)
} catch (error) {
  // handle error
}

sendChatSurvey

Mit dieser Methode wird eine Umfrage an den Verbraucher gesendet.

Methodensignatur

sendChatSurvey(answers: SurveyAnswers): void

Schnittstellen

interface SurveyAnswers {
  [question_id: string]: number | string;
}

Beispiel für die Verwendung

try {
  await client.sendChatSurvey({
    123: "a",
    231: "b",
  })
} catch (error) {
  // handle error
}

sendChatRate

Mit dieser Methode wird das Feedback des Endnutzers für den aktuellen Chat gesendet, wenn der Chat beendet ist.

Methodensignatur

sendChatRate(data: RateRequest): Promise<void>

Schnittstellen

interface RateRequest {
  rating: number;
  feedback?: string;
}

Beispiel für die Verwendung

try {
  await client.sendChatRate({
    rating: 5,
    feedback: "Very good service",
  })
} catch (error) {
  // handle error
}

escalateChat

Methodensignatur

escalateChat(data?: EscalateRequest): Promise<void>

Schnittstellen

interface EscalateRequest {
  reason?: string;
  // ...other escalation fields
}

Beispiel für die Verwendung

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

trackChatEscalation

Methodensignatur

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

Beispiel für die Verwendung

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

trackChatEndUserEvent

Methodensignatur

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Rückgabewert

Gibt „void“ zurück.

Schnittstellen

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

Beispiel für die Verwendung

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

getChatHistory

Methodensignatur

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

Rückgabewert

Gibt ein ChatHistoryResponse-Objekt zurück.

Schnittstellen

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

Beispiel für die Verwendung

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

E-Mails

Methoden für die Bearbeitung von Support-E‑Mails.

createEmails

Methodensignatur

createEmail(menuId: number | string, data: EmailRequest): Promise<EmailResponse>

Rückgabewert

Gibt bei Fehler oder Erfolg ein EmailResponse-Objekt zurück.

Schnittstellen

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

Beispiel für die Verwendung

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

Methodensignatur

getProhibitedFileTypes(): Promise<FileTypeItem[]>

Rückgabewert

Gibt ein Array von FileTypeItem zurück.

Schnittstellen

interface FileTypeItem {
  extension: string;
  description: string;
}

Beispiel für die Verwendung

try {
  const types = await client.getProhibitedFileTypes()
} catch (error) {
  // handle error
}

Bildschirmfreigabe

Methoden zum Verarbeiten der Bildschirmfreigabe.

createCobrowseCode

Mit dieser Methode wird ein Bildschirmfreigabe-Code erstellt.

Methodensignatur

createCobrowseCode(lang?: string, customData?: Record<string, string>): Promise<string>

Rückgabewert

Gibt einen Bildschirmfreigabe-Code-String oder bei einem Fehler einen leeren String zurück.

Beispiel für die Verwendung

const code = await client.createCobrowseCode()
// 123456

startCobrowse

Methodensignatur

startCobrowse(from?: string): Promise<void>

Beispiel für die Verwendung

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

restoreCobrowseSession

Mit dieser Methode wird versucht, eine zuvor aktive Bildschirmfreigabesitzung wiederherzustellen, nachdem das Browserfenster wieder geöffnet oder das Widget neu geladen wurde.

Methodensignatur

restoreCobrowseSession(): Promise<void>

Rückgabewert

Gibt Promise<void> zurück. Diese Methode ist ein No-Op (sie wird sofort ohne Fehler zurückgegeben), wenn die Bildschirmfreigabe für Ihre Instanz nicht aktiviert ist oder keine vorherige Bildschirmfreigabesitzung im Speicher vorhanden ist.

Beispiel für die Verwendung

// Safe to call unconditionally. Will no-op if cobrowse is not enabled
// or if no previous session exists
await client.restoreCobrowseSession()

getMessageAttachment

Methodensignatur

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

Rückgabewert

Gibt ein File-Objekt zurück, falls gefunden, oder „null“, falls nicht zutreffend.

Beispiel für die Verwendung

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

Virtuelle Kundenservicemitarbeiter nach der Sitzung

Methoden für den Umgang mit virtuellen Kundenservicemitarbeitern nach der Sitzung.

updatePostSession

Aktualisiert den Status des virtuellen Kundenservicemitarbeiters nach der Sitzung für den laufenden Chat. Damit können Sie signalisieren, dass ein virtueller Kundenservicemitarbeiter nach der Sitzung bereit ist, Fortschritte macht oder einen Vorgang abgeschlossen hat. Diese Methode wird sofort als No-Op zurückgegeben, wenn postSessionStatus FINISHED oder WAITING ist, da diese Übergänge intern verarbeitet werden. Diese Methode enthält eine interne Wiederholungslogik speziell für den Status IN_PROGRESS bei einer 400-Antwort. Aufrufer müssen daher keine eigene Wiederholung für diesen Fall implementieren.

Methodensignatur

updatePostSession(postSessionStatus: PostSessionStatus, optInSelection?: boolean): Promise<void>

Schnittstellen

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

Beispiel für die Verwendung

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

Zugehörige Schnittstelle

interface ChatResponse {
  //...
  post_session_required?: boolean;
  post_session_opt_in_required?: boolean;
  post_session_transfer_status?: string;
}
  • post_session_required: Nach einer Chat-Sitzung ist eine Nachbereitung erforderlich.
  • post_session_opt_in_required: Wenn die Einwilligung aktiviert ist.
  • post_session_transfer_status: Eine PostSessionStatus-Aufzählung.

Debugging

Methoden zum Debuggen des SDK.

getLogs

Ruft die internen Debug-Logs ab, die vom SDK erfasst wurden, einschließlich Logs auf Bridge- und Stammebene. Das ist hilfreich bei der Behebung von Integrationsproblemen.

Methodensignatur

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

Rückgabewert

Gibt ein Objekt mit zwei Arrays von LogHistoryData zurück.

Schnittstellen

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

Beispiel für die Verwendung

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

Gibt alle internen Debugging-Logs direkt in der Browserkonsole aus. Dies ist eine Hilfsmethode, die intern getLogs() aufruft und die Ausgabe formatiert.

Methodensignatur

printLogs(): Promise<void>

Beispiel für die Verwendung

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

Sonstiges

Verschiedene SDK-Methoden.

runTrigger

Methodensignatur

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

Beispiel für die Verwendung

client.runTrigger((trigger: TriggerItem) => {
  // code to run for given trigger
})

getAfterHourMessage

Methodensignatur

getAfterHourMessage(lang?: string): Promise<string>

Rückgabewert

Gibt einen String mit einer konfigurierten Nachricht zurück.

Beispiel für die Verwendung

try {
  const message: string = await client.getAfterHourMessage()
} catch (error) {
  // handle error
}