Headless Web SDK API-Methoden

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

Unternehmen und Menüs

Methoden zum Umgang mit Unternehmenswerten und Menüs.

Methoden

Das monitorlose SDK bietet verschiedene Methoden, die für die Clientinstanz aufgerufen werden können.

Hier sind einige Beispiele:

Unternehmen und Menüs

Methodenname	Beschreibung
getCompany	Ruft konfigurierte Unternehmensinformationen ab.
getMenus	Listet alle verfügbaren Menüs für den angegebenen Mandanten auf.
getWaitTimes	Aktuelle Wartezeiten für verschiedene Kanäle in einem Menü abrufen.

getCompany

Ruft die konfigurierten Unternehmensinformationen für die authentifizierte Instanz ab, einschließlich des Namens des Unternehmens, der unterstützten Sprachen und der Funktionseinstellungen. Diese Methode legt auch die interne Instanz-ID (OPTIONS.tenant) als Nebeneffekt fest. Daher ist sie in der Regel der erste Aufruf, der nach dem Erstellen eines Clients erfolgt.

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;
  display_history: boolean;
  use_recording: boolean;
  use_web: boolean;
  cobrowse_domain?: string;
}

Nutzungsbeispiel

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

getMenus

Mit dieser Methode werden alle für die Instanz verfügbaren Menüpunkte aufgelistet. Das Feld MenuResponse.direct gibt Aufrufern an, ob das Ergebnis von einem Direktschlüssel (direct.key: true) oder von einem Direktzugriff auf Nutzerebene (direct.user: true) stammt. Beides wirkt sich darauf aus, wie die Menüs dargestellt werden sollen.

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;
    key_id: number | null;
  };
}
interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
  hidden: boolean;
}

Nutzungsbeispiel

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

getWaitTimes

Ruft die geschätzte Wartezeit (in Sekunden) für die Chat- und Sprachanrufkanäle eines bestimmten Menüs ab.

Methodensignatur

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

Rückgabewert

Gibt entweder ein WaitTimeResponse-Objekt oder null zurück.

Schnittstellen

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

Nutzungsbeispiel

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

Anrufe

Name	Beschreibung
createCall	Erstellen Sie einen Sofortanruf oder einen geplanten Anruf.
loadCall	Informationen zu einer bestimmten Anruf-ID abrufen.
cancelCall	Bricht den Anruf mit der angegebenen Anruf-ID ab.
getTimeSlots	Verfügbare Zeitfenster für geplante Anrufe für ein bestimmtes Menü abrufen.
fetchTimeSlotAvailability	Prüfen, ob für ein bestimmtes Menü Zeitfenster verfügbar sind.

createCall

Erstellt einen neuen Anruf für das angegebene Menü. Dies kann ein Sofortanruf oder ein geplanter Anruf sein, je nachdem, ob das Feld scheduled_at angegeben ist. Der Aufruftyp (web_instant_call oder web_scheduled_call) wird automatisch anhand des Vorhandenseins von scheduled_at bestimmt. reschedule_call_id wird auf der obersten Ebene der Anfrage gesendet, getrennt vom Aufruftext. Der menu_id in der Antwort wird aus dem selected_menu.id der API normalisiert.

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

Nutzungsbeispiel

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

loadCall

Mit der Methode loadCall werden Informationen zu einem bestimmten Anruf abgerufen, der durch seine ID identifiziert wird.

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

Nutzungsbeispiel

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

cancelCall

Bricht einen vorhandenen Anruf anhand seiner ID ab. Wird normalerweise verwendet, um einen geplanten Anruf abzubrechen, der noch nicht getätigt wurde.

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

Nutzungsbeispiel

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 die Methode mit einem GetTimeSlotsRequest-Optionsobjekt aufgerufen wird, kann ein vorhandener Anruf mit rescheduleCallId neu geplant werden. Die verworfene Stringsignatur lang wird weiterhin unterstützt und leitet an denselben Endpunkt weiter, wobei nur lang ausgefüllt wird. Gibt ein Array von Zeitfenster-Strings zurück.

Methodensignatur

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

Warnung: Die vorherige Signatur getTimeSlots(menuId, lang?) wurde eingestellt. Migrieren Sie zur neuen, optionsbasierten Signatur, die oben gezeigt wurde. Die alte Signatur funktioniert weiterhin, wird aber möglicherweise in einer zukünftigen Version entfernt.

Rückgabewert

Gibt ein Array von Strings (Zeitfenster) zurück.

Schnittstellen

interface GetTimeSlotsRequest {
 lang?: string;
 rescheduleCallId?: number;          // ID of an existing call being rescheduled
}

Nutzungsbeispiel

// New options-based signature (recommended)
try {
 const slots = await client.getTimeSlots(123, {
   lang: 'en',
   rescheduleCallId: 98765, // optional: pass when rescheduling an existing call
 })
} 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. Sie ist nützlich, um Planungsoptionen in der Benutzeroberfläche bedingt anzuzeigen.

Umfang

fetchTimeSlotAvailability gilt nur für geplante Sprachanrufe (Rückrufe). Es werden keine Informationen zu Chat-, E-Mail- oder Sofortanrufkanälen zurückgegeben. Das bereitgestellte Menü muss so konfiguriert sein, dass geplante Sprachanrufe unterstützt werden. Außerdem müssen Betriebszeiten definiert und mindestens ein Agent für dieses Menü in die Warteschlange gestellt sein.

Typische Anwendungsfälle:

• Der Call-to-Action Rückruf vereinbaren wird nur dann angezeigt, wenn Termine verfügbar sind.

• Verzweigung zu einem Umleitungsablauf (z.B. E-Mail, Nachricht außerhalb der Geschäftszeiten), wenn keine Zeitfenster verfügbar sind, ohne die Kosten für einen vollständigen getTimeSlots-Anruf zu zahlen.

• Preflight-Prüfung einer Aktion zum Verschieben, bevor getTimeSlots mit einem rescheduleCallId aufgerufen wird.

Methodensignatur

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

Rückgabewert

Gibt true zurück, wenn Zeitfenster verfügbar sind, andernfalls false.

Nutzungsbeispiel

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

Chats

Name	Beschreibung
createChat	Erstellt einen neuen Chat.
loadChat	Ruft den Chat mit der angegebenen Chat-ID ab.
loadOngoingChat	Versucht, einen laufenden Chat zu laden.
resumeChat	Setzt einen geschlossenen Chat mit der angegebenen Chat-ID fort.
finishChat	Setzt den Status des aktuellen Chats auf „Beendet“.
destroyChat	Ruft finishChat auf und löscht den aktuellen Chat
fetchMessages	Ruft vorherige Nachrichten ab – gibt bei einem Fehler [] zurück.
sendTextMessage	Sendet eine SMS.
sendFileMessage	Sendet eine Dateinachricht. Gibt bei einem Uploadfehler -1 zurück.
sendPreviewMessage	Sendet eine Vorschaunachricht.
getChatDeflection	Ruft die Konfiguration für die Chat-Weiterleitung ab.
sendChatTranscripts	Sendet das Chattranskript an die angegebenen E‑Mail-Adressen.
downloadChatTranscript	Lädt das Chattranskript herunter.
getPdfStatus	Ruft den PDF-Status für ein Transkript ab.
getChatSurvey	Ruft die Fragen der Chat-Umfrage ab.
sendChatSurvey	Nutzerfeedback aus der Umfrage senden.
sendChatRate	Nutzerfeedback zum Chat senden.
escalateChat	Eskaliert einen Chat von einem virtuellen Kundenservicemitarbeiter an einen menschlichen Kundenservicemitarbeiter.
trackChatEscalation	Erfasst das Chat-Eskalationsereignis.
trackChatEndUserEvent	Erfasst ein Endnutzerereignis.
getChatHistory	Ruft die Verläufe eines bestimmten Chats ab.

Chat-Check-in

Bei der Funktion „Check-in“ wird der Nutzer gefragt, ob er bereit ist, bevor er mit einem Kundenservicemitarbeiter verbunden wird. In diesem Abschnitt werden die Headless Web SDK-Methoden zum Implementieren dieser Funktion beschrieben. Informationen dazu, was der Check-in ist, wie er aktiviert und konfiguriert wird (Wartezeit, Zeitüberschreitung, Position in der Warteschlange, Verhalten beim erneuten Beitreten) und wie Berichte erstellt werden, finden Sie unter Check-in für Chat.

Name	Beschreibung
checkIn	Sendet ein Signal an den Server, um die Anwesenheit des Nutzers in der Warteschlange zu bestätigen.
exitCheckIn	Entfernt den Nutzer aus der Check-in-Warteschlange.
notifyCheckInState	Benachrichtigt das Backend über den Sichtbarkeitsstatus des modalen Dialogfelds für den Check-in.
rejoinChat	Der Nutzer wird wieder in die Warteschlange eingereiht, wenn er den Check-in nicht bestätigt.
trackCheckInEvent	Signalisiert dem Backend, wenn Check-in-Ereignisse von der Benutzeroberfläche ausgelöst wurden.

checkIn

Sendet ein Bestätigungssignal an den Server, das angibt, dass der Nutzer anwesend und bereit ist, sich während des Check-in-Zeitfensters mit einem Agenten zu verbinden. Aktualisiert die check_in_status des Chats lokal, nachdem der Server die Bestätigung gesendet hat. Wird als Antwort auf das Ereignis chat.checkInRequested verwendet.

Methodensignatur

checkIn(): Promise<CheckInResponse>

Rückgabewert

Gibt ein CheckInResponse-Objekt zurück.

Schnittstellen

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

Nutzungsbeispiel

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

exitCheckIn

Signalisiert dem Server, dass der Kunde die Check-in-Warteschlange verlassen hat. Aktualisiert check_in_status lokal. Nach dem Aufruf dieser Methode erhält der Nutzer für den aktuellen Check-in-Zyklus keine Agentenverbindung.

Methodensignatur

exitCheckIn(): Promise<CheckInResponse>

Rückgabewert

Gibt ein CheckInResponse-Objekt zurück.

Schnittstellen

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

Nutzungsbeispiel

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

notifyCheckInState

Informiert den Server über den aktuellen Sichtbarkeitsstatus des Check-in-Modals, d. h. ob das Widget minimiert oder der Browsertab inaktiv ist. Der Server verwendet diese Informationen, um Entscheidungen über den Zeitpunkt des Eincheckens zu treffen. Sollte immer dann aufgerufen werden, wenn sich die Sichtbarkeit oder der Tab-Fokus des Widgets ändert, während das Ereignis chat.checkInRequested aktiv ist.

Methodensignatur

notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>

Schnittstellen

interface CheckInVisibilityStateRequest {
 widget_minimized?: boolean;
 tab_inactive?: boolean;
}

Nutzungsbeispiel

try {
 const visibilityState = {
   widget_minimized: true,
   tab_inactive: false,
 }
 await client.notifyCheckInState(visibilityState)
} catch (error) {
 // handle error
}

rejoinChat

Der Kunde wird wieder in die Warteschlange eingereiht, nachdem er einen Check-in nicht innerhalb der vorgegebenen Zeit bestätigt hat. Aktualisiert check_in_status lokal. Verwenden Sie diese Methode als Antwort auf das chat.checkInTimedOut-Ereignis, wenn der Nutzer weiterhin eine Verbindung herstellen möchte.

Methodensignatur

rejoinChat(): Promise<CheckInResponse>

Rückgabewert: Gibt ein CheckInResponse-Objekt zurück.

Schnittstellen

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

Nutzungsbeispiel

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

trackCheckInEvent

Benachrichtigt den Server, dass das Check-in-Modal dem Nutzer angezeigt wurde. Rufe diese Methode einmal auf, unmittelbar nachdem die Check-in-Benutzeroberfläche als Antwort auf chat.checkInRequested angezeigt wurde. Der Server verwendet sie für Betriebsanalysen zu den Präsentationsraten beim Check-in. Der Aufruf wird intern erwartet und gibt ein Promise<void> zurück, das abgelehnt werden kann. Verpacken Sie es daher in try/catch (wie im folgenden Beispiel).

Methodensignatur

trackCheckInEvent(): Promise<void>

Nutzungsbeispiel

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

getMessageAttachment

Ruft einen zulässigen Anhang ab, der mit einer bestimmten Chatnachricht verknüpft ist. Wird nur abgerufen, wenn die Nachricht von einem Nicht-Endnutzer ($userType !== 'end_user') gesendet wurde und einen unterstützten Anhangstyp (Foto, Video, Audio, Dokument) hat. Gibt null für alle Nachrichten zurück, die nicht beide Bedingungen erfüllen, nicht nur für Nachrichten ohne media_id. Speichert die abgerufene Datei nach dem Abruf im lokalen Medien-Cache des Chats.

Methodensignatur

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

Rückgabewert

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

Nutzungsbeispiel

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

createChat

Erstellt eine neue Chatsitzung für das angegebene Menü. Optional können Sie die Sprache, eine Begrüßungsnachricht, eine Trigger-ID, eine Ticket-ID und benutzerdefinierte Daten angeben, die mit dem Chat gesendet werden sollen.

Nach dem ersten API-Aufruf fragt die Methode den Server ab, bis ein provider_channel_id verfügbar ist oder der Chat abgebrochen oder beendet wird. Wenn ein Anbieterkanal verfügbar wird, initiiert die Methode die Verbindung zum Echtzeitanbieter. Die Verbindung wird möglicherweise noch hergestellt, wenn das Promise aufgelöst wird. Achten Sie auf das Ereignis chat.connectedMessages, um zu erfahren, wann die Verbindung und der erste Nachrichtenabruf abgeschlossen sind.

Methodensignatur

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

Rückgabewert

Gibt eine Chat-Instanz zurück.

Warnung: Diese Methode löst sofort einen Fehler aus, wenn bereits ein Chat läuft. Prüfe vor dem Anruf, ob bereits eine Sitzung vorhanden ist.

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

Nutzungsbeispiel

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

loadChat

Ruft eine vorhandene Chatsitzung anhand ihrer ID ab.

Wenn der geladene Chat nicht mehr aktiv ist, werden die gespeicherte Chat-ID und die Cobrowse-Nonce aus dem lokalen Speicher gelöscht. Dies geschieht auch bei Fehlern, sodass Aufrufer nach einem fehlgeschlagenen Ladevorgang den Speicher nicht manuell bereinigen müssen.

Methodensignatur

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

Rückgabewert

Gibt eine Chat-Instanz zurück.

Warnung: Im Falle eines Fehlers löscht diese Methode die gespeicherten Chat- und Cobrowse-Sitzungs-IDs aus dem lokalen Speicher, bevor sie den Fehler erneut auslöst. Alle gespeicherten Sitzungsreferenzen werden nach einem fehlgeschlagenen Aufruf ungültig.

Nutzungsbeispiel

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

loadOngoingChat

Versucht, die aktuelle laufende Chatsitzung zu laden, falls vorhanden. Gibt null zurück, wenn kein laufender Chat gefunden wird.

Methodensignatur

loadOngoingChat(): Promise<Chat | null>

Rückgabewert

Gibt eine Chat-Instanz zurück, falls gefunden, oder null, wenn kein laufender Chat vorhanden ist. Will clean storage values if chat isn't ongoing.

Warnung: Im Falle eines Fehlers löscht diese Methode die gespeicherte Chat-ID aus dem lokalen Speicher, bevor sie den Fehler erneut auslöst. Alle gespeicherten Sitzungsreferenzen werden nach einem fehlgeschlagenen Aufruf ungültig.

Nutzungsbeispiel

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

resumeChat

Setzt eine zuvor geschlossene Chatsitzung anhand ihrer ID fort, sodass der Nutzer die Unterhaltung fortsetzen kann.

Wenn der Client bereits eine Referenz auf einen Chat mit derselben ID hat, wird die Methode abgekürzt: Der Status wird in der vorhandenen Instanz auf queued gepatcht, anstatt eine neue Instanz abzurufen. Wenn die IDs nicht übereinstimmen, wird eine neue Chat-Instanz erstellt und registriert.

Methodensignatur

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

Rückgabewert

Gibt eine Chat-Instanz zurück.

Nutzungsbeispiel

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

finishChat

Setzt den Status der aktuellen Chatsitzung auf „Beendet“. Dadurch wird der Chat von der Seite des Nutzers beendet.

Wenn der Chat sowohl mit dem Echtzeitanbieter verbunden ist als auch nach dem PATCH beendet wurde, wird die Verbindung zum Anbieter ebenfalls getrennt. Anrufer müssen destroyChat nicht aufrufen, wenn sie nur den Chat beenden möchten.

Methodensignatur

finishChat(): Promise<void>

Nutzungsbeispiel

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

destroyChat

Beendet und löscht die aktuelle Chatsitzung und bereinigt den gesamten internen Status. Dadurch wird intern finishChat aufgerufen und die Chatinstanz anschließend beendet. Bevor der Chat beendet wird, wird er von der Methode stummgeschaltet (eingehende Echtzeitereignisse werden unterdrückt), um zu vermeiden, dass Nachrichten während des Beendens verarbeitet werden. Löscht die interne Tracker-ID, nachdem der Chat beendet wurde.

Methodensignatur

destroyChat(): Promise<void>

Nutzungsbeispiel

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

fetchMessages

Ruft den Nachrichtenverlauf für die aktuelle Chatsitzung vom Echtzeitanbieter ab. Sollte aufgerufen werden, nachdem der Chat verbunden wurde. Wenn die Methode aufgerufen wird, bevor der Chat verbunden ist, wird ein leeres Array zurückgegeben, anstatt einen Fehler auszulösen. Ruft automatisch Dokument-URLs für alle Nachrichten vom Typ document ab und fügt sie in die Antwort ein. Ruft für Nachrichten vom Typ server_message den Inhalt der Nachricht des virtuellen Aufgaben-Agenten ab und formatiert ihn inline. Gibt bei einem Fehler ein leeres Array zurück, anstatt einen Fehler auszulösen.

Methodensignatur

fetchMessages(): Promise<MessageResponse[]>

Rückgabewert

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

Warnung: Diese Methode löst bei einem Fehler keine Ausnahme aus. Gibt ein leeres Array ([]) zurück, wenn der Nachrichtenabruf fehlschlägt. Verlassen Sie sich nicht auf try/catch, sondern prüfen Sie stattdessen den Rückgabewert.

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

  // allow extra parameters
  [key: string]: unknown;
}

Nutzungsbeispiel

const messages = await client.fetchMessages()

sendTextMessage

Sendet eine Textnachricht in der aktuellen Chatsitzung.

Die Methode bereinigt den Rohinhalt vor dem Senden und gibt frühzeitig ein Ergebnis zurück (No-Op), wenn das Ergebnis leer ist. Wenn sich der Chat in einem Aufgaben-Ablauf für virtuelle Agenten (inTask) befindet, wird die Nachricht über den Endpunkt des virtuellen Agenten für Aufgaben und nicht über den regulären Kanal weitergeleitet. Wenn die serverseitige Entfernung aktiviert ist, wird die Nachricht über einen Serverendpunkt und nicht direkt über den Echtzeitanbieter gesendet.

Methodensignatur

sendTextMessage(rawContent: string): Promise<void>

Nutzungsbeispiel

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

sendFileMessage

Lädt eine Datei in die aktuelle Chatsitzung hoch. Dieser Vorgang besteht aus drei Schritten: Abrufen einer vorsignierten Cloud Storage-URL vom Server, Hochladen der Datei direkt zu dieser URL und Bestätigen des Uploads an den Server. Die Uploadroute wird automatisch anhand des MIME-Typs der Datei bestimmt: Bilder werden als Fotonachrichten und Videos als Videonachrichten gesendet. Andere Dateitypen werden anhand ihres MIME-Typs weitergeleitet. Gibt bei Erfolg die Nachrichten-ID oder bei Fehlschlag -1 zurück.

Methodensignatur

sendFileMessage(file: File): Promise<number>

Rückgabewert

Gibt die Nachrichten-ID oder -1 zurück, wenn der Upload fehlgeschlagen ist. Das anschließende Senden der Nachricht kann jedoch trotzdem abgelehnt werden (z. B. ChatEndedError). Verpacken Sie den Aufruf daher zusätzlich zur Prüfung auf -1 in try/catch.

Nutzungsbeispiel

const input = document.querySelector('input[type="file"]')
const file = input.files[0]
try {
  const id = await client.sendFileMessage(file)
  if (id === -1) {
    // handle upload failure
  }
} catch (error) {
  // handle message-send failure
}

sendPreviewMessage

Sendet eine Vorschaunachricht in der aktuellen Chatsitzung. Vorschaunachrichten werden in der Regel verwendet, um dem Kundenservicemitarbeiter zu zeigen, was der Nutzer eingibt, bevor die Nachricht gesendet wird. Wenn sowohl redaction_enabled als auch agent_incoming_ha_enabled im Chatstatus „true“ sind, wird die Vorschau über einen Serverendpunkt (POST /chats/{id}/redact_messages) und nicht über den Echtzeitanbieterkanal gesendet.

Methodensignatur

sendPreviewMessage(content: string): Promise<void>

Nutzungsbeispiel

try {
 await client.sendPreviewMessage('preview content')
} catch (error) {
 // handle error
}

getChatDeflection

Ruft die Konfiguration für die Chat-Umleitung für die aktuelle Chatsitzung ab, einschließlich der Information, ob die Umleitung aktiviert ist, des Schwellenwerts für die Wartezeit und der verfügbaren Umleitungsoptionen.

Gibt null zurück, wenn die Ablenkung für den Chat nicht aktiviert ist (das Feld enabled der Serverantwort ist „falsy“). Aufrufer sollten vor dem Lesen der Antwort eine Nullprüfung durchführen.

Methodensignatur

getChatDeflection(): Promise<ChatDeflectionResponse | null>

Rückgabewert

Gibt entweder ein ChatDeflectionResponse-Objekt oder null zurück, wenn die Ablenkung für den Chat nicht aktiviert ist.

Schnittstellen

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

Nutzungsbeispiel

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

sendChatTranscripts

Sendet das aktuelle Chatprotokoll an die angegebenen E-Mail-Adressen.

Methodensignatur

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

Nutzungsbeispiel

try {
 await client.sendChatTranscripts([
   "[e-mail]",
   "[e-mail]",
 ])
} catch (error) {
 // handle error
}

downloadChatTranscript

Startet einen Download des aktuellen Chatprotokolls als PDF. Gibt ein Transkriptobjekt zurück, das mit getPdfStatus verwendet werden kann, um den Fortschritt der Generierung zu verfolgen.

Methodensignatur

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Rückgabewert

Gibt das Transkriptobjekt zurück.

Schnittstellen

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

Nutzungsbeispiel

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

getPdfStatus

Prüft den Generierungsstatus eines zuvor angeforderten Chatprotokoll-PDFs. Verwenden Sie den von downloadChatTranscript zurückgegebenen chat_transcript_id, um den Abschluss abzufragen.

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

Nutzungsbeispiel

const response = await client.getPdfStatus(pdfId)
// check header for status
const status = response.headers['x-transcript-status'];
// otherwise use status on data
const data = response.data
console.log(data.status)

getChatSurvey

Ruft die Fragen der Umfrage nach dem Chat ab, die für die aktuelle Chatsitzung konfiguriert sind. Die Umfrage wird Nutzern nach Beendigung eines Chats angezeigt.

Methodensignatur

getChatSurvey(): Promise<ChatSurveyResponse | null>

Rückgabewert

Gibt entweder ein ChatSurveyResponse-Objekt oder null 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[];
}

Nutzungsbeispiel

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

sendChatSurvey

Sendet die Antworten des Nutzers auf die Umfrage nach dem Chat. Jede Antwort wird durch die Frage-ID verschlüsselt.

Methodensignatur

sendChatSurvey(answers: SurveyAnswers): Promise<void>

Warnung: Diese Methode löst sofort einen Fehler aus, wenn der Feedbacktyp des Chats nicht 'survey' ist. Aufrufer sollten vor dem Aufruf chat.feedbackType === 'survey' prüfen oder den Fehler beheben.

Schnittstellen

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

Nutzungsbeispiel

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

sendChatRate

Sendet die Bewertung und das optionale Feedback des Nutzers für die Chatsitzung. Wird verwendet, wenn der Feedbacktyp nach dem Chat eine Bewertung und keine vollständige Umfrage ist.

Methodensignatur

sendChatRate(data: RateRequest): Promise<void>

Warnung: Diese Methode löst sofort einen Fehler aus, wenn der Feedbacktyp des Chats nicht 'rate' ist. Aufrufende sollten vor dem Aufruf chat.feedbackType === 'rate' prüfen oder den Fehler beheben.

Schnittstellen

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

Nutzungsbeispiel

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

escalateChat

Eskaliert den aktuellen Chat von einem virtuellen Kundenservicemitarbeiter an einen menschlichen Kundenservicemitarbeiter.

Methodensignatur

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

Schnittstellen

interface EscalateRequest {
 force_escalate: boolean;
 menu_id: number;
 lang: string;
}

Nutzungsbeispiel

try {
 // Escalate to a specific menu in a given language
 await client.escalateChat({
   force_escalate: true,
   menu_id: 123,
   lang: 'en',
 })
} catch (error) {
 // handle error
}
// Or, escalate without arguments to use defaults
try {
 await client.escalateChat()
} catch (error) {
 // handle error
}

trackChatEscalation

Verfolgt ein Chateskalationsereignis und zeichnet die Eskalations-ID und den Kanal auf, an den es eskaliert wurde.

Methodensignatur

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

Nutzungsbeispiel

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

trackChatEndUserEvent

Erfasst ein benutzerdefiniertes Endnutzerereignis während der Chatsitzung, das für Analysen oder zum Auslösen von Back-End-Workflows verwendet werden kann. Wenn das Objekt data nicht end_user_name enthält und im Nutzerprofil des authentifizierten Nutzers ein Name verfügbar ist, wird dieser automatisch eingefügt, bevor die Anfrage gesendet wird.

Methodensignatur

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Rückgabewert

Gibt „void“ zurück.

Schnittstellen

interface ChatEndUserEventRequest {
  event: {
    name: string;
    payload: Record<string, string>;
  };
  end_user_name?: string;
}

Nutzungsbeispiel

try {
 await client.trackChatEndUserEvent({
   event: {
     name: 'add_to_cart',
     payload: {
       product_id: 'sku-1234',
       quantity: '2',
     },
   },
   // end_user_name is auto-populated from the authenticated user
   // profile if omitted
 })
} catch (error) {
 // handle error
}

getChatHistory

Ruft den bisherigen Chatverlauf des Nutzers ab, einschließlich Nachrichteninhalten und Metadaten. Die Ergebnisse sind paginiert. Auf Seite 1 werden bis zu 2 Chats zurückgegeben, auf den folgenden Seiten jeweils 1 Chat. Diese asymmetrische Paginierung ist beabsichtigt und ermöglicht es, beim ersten Aufruf den angrenzenden Verlaufskontext vorab zu laden.

Methodensignatur

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

Rückgabewert

Gibt entweder ein ChatHistoryResponse-Objekt oder null 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;
 }
}

Nutzungsbeispiel

try {
 const data = await client.getChatHistory(1) // page defaults to 1 if omitted
 console.log(data)
} catch (error) {
 console.log(error)
}

E-Mails

Name	Beschreibung
createEmail	E-Mail an den E-Mail-Kanal einer bestimmten Menü-ID senden.
getProhibitedFileTypes	Rufen Sie die unzulässigen Dateitypen für E-Mail-Anhänge ab.

createEmail

Sendet eine E‑Mail-Nachricht an den E‑Mail-Kanal, der mit dem angegebenen Menü verknüpft ist. Der Nutzer kann einen Namen, eine E-Mail-Adresse, den Inhalt der Nachricht und optionale Dateianhänge angeben.

Methodensignatur

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

Rückgabewert

Gibt bei einem 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;
}

Nutzungsbeispiel

try {
 await client.createEmail(123, {
   lang: "en",
   name: "User name",
   email: "[e-mail]",
   content: "description of the question",
   files: input.files,
 })
} catch (error) {
 console.log(error.message)
}

getProhibitedFileTypes

Ruft die Liste der Dateitypen ab, die gemäß der Konfiguration durch den Administrator nicht als E-Mail-Anhänge zulässig sind.

Methodensignatur

getProhibitedFileTypes(): Promise<FileTypeItem[]>

Rückgabewert

Gibt ein Array von FileTypeItem zurück.

Schnittstellen

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

Nutzungsbeispiel

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

Bildschirmfreigabe

Name	Beschreibung
createCobrowseCode	Generiert einen Cobrowsing-Code.
startCobrowse	Fordern Sie eine Cobrowsing-Sitzung an.
restoreCobrowseSession	Stellt eine Cobrowsing-Sitzung wieder her, nachdem das Browserfenster wieder geöffnet wurde.

createCobrowseCode

Generiert einen eindeutigen Sitzungscode für die gemeinsame Nutzung (Bildschirmfreigabe), der mit einem Kundenservicemitarbeiter geteilt werden kann, um eine Sitzung zu starten. Initialisiert den Cobrowse-Client, falls er noch nicht initialisiert wurde. Verwendet eine vorhandene Nonce aus dem Speicher, anstatt bei jedem Aufruf eine neue zu generieren. So kann derselbe Sitzungscode über mehrere Seitenaufrufe hinweg abgerufen werden.

Methodensignatur

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

Rückgabewert

Gibt einen Cobrowsing-Codestring oder einen leeren String ('') zurück, wenn ein Fehler auftritt.

Warnung: Diese Methode löst bei einem Fehler keine Ausnahme aus. Verlassen Sie sich nicht auf try/catch, sondern prüfen Sie stattdessen den Rückgabewert.

Nutzungsbeispiel

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

startCobrowse

Fordert während eines aktiven Chats den Start einer Cobrowsing-Sitzung (Bildschirmfreigabe) von der Seite des Endnutzers an.

Methodensignatur

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

Warnung: Diese Methode löst einen Fehler aus, wenn der aktuelle Chat nicht mit cobrowsable: true erstellt wurde. Aufrufer können chat.cobrowsable vor dem Aufruf prüfen, um die Ausnahme zu vermeiden.

Nutzungsbeispiel

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

restoreCobrowseSession

Versucht, eine zuvor aktive Cobrowsing-Sitzung 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 (wird sofort ohne Fehler zurückgegeben), wenn Cobrowsing in den Clientoptionen nicht aktiviert ist oder keine vorherige Cobrowsing-Sitzung im Speicher vorhanden ist.

Warnung: Diese Methode löst keine Ausnahme aus. Wenn während der Wiederherstellung ein Fehler auftritt, wird er intern protokolliert und die gespeicherte Cobrowsing-Sitzung wird gelöscht. Anschließend wird die Methode ordnungsgemäß beendet. Anrufer benötigen kein try/catch.

Nutzungsbeispiel

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

Virtueller Kundenservicemitarbeiter nach der Sitzung

Name	Beschreibung
updatePostSession	Legen Sie den Status nach der Sitzung für den laufenden Chat fest.

updatePostSession

Diese Methode wird verwendet, um den Status des virtuellen Agenten nach der Sitzung für den laufenden Chat zu aktualisieren.

• Aktualisiert den Status des virtuellen Kundenservicemitarbeiters nach der Sitzung für den laufenden Chat. Verwenden Sie dies, um die Bereitschaft, den Fortschritt oder den Abschluss eines virtuellen Agentenablaufs nach der Sitzung zu signalisieren.

• Wird sofort als No-Op zurückgegeben, wenn postSessionStatus den Wert FINISHED oder WAITING hat. Diese Übergänge werden intern verarbeitet.

• Verfügt über eine interne Wiederholungslogik speziell für den Status IN_PROGRESS bei einer 400-Antwort, sodass Aufrufer in diesem Fall keine eigene Wiederholung implementieren müssen.

Methodensignatur

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

Schnittstellen

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

Nutzungsbeispiel

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 einem Chat ist eine Nachbereitung erforderlich.

• post_session_opt_in_required: Gibt an, ob die Option aktiviert ist.

• post_session_transfer_status: Dies ist einer der PostSessionStatus-Enums.

Debugging

Name	Beschreibung
getLogs	Ruft interne Debugging-Logs aus dem SDK ab.
printLogs	Gibt interne Debugging-Logs in der Browserkonsole aus.

getLogs

Ruft die vom SDK erfassten internen Debugging-Logs ab, einschließlich Logs auf Bridge- und Root-Ebene. Nützlich für die Fehlerbehebung bei Integrationsproblemen.

Methodensignatur

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

Rückgabewert

Gibt ein Objekt mit zwei Arrays vom Typ LogHistoryData zurück.

Schnittstellen

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

Hinweis: Bridge-Logs werden zuerst intern abgerufen, da der Abruf selbst einen Root-Logeintrag erzeugt. Daher erfasst rootLogs dieses letzte Protokoll absichtlich.

Detaillierungsgrad

Jeder LogHistoryData-Eintrag erfasst ein einzelnes Logereignis:

• date: ISO 8601-Zeitstempel des Ereignisses.

• channel: das SDK-Modul, das die Nachricht ausgegeben hat (z.B. Client auf oberster Ebene, Chatebene, Cobrowse-Ebene, Echtzeitanbieter).

• level: Logschweregrad: debug, info, warn oder error.

• args: die Rohargumente, die vom Logaufruf erfasst wurden.

Beispieleintrag:

{
 "date": "2026-05-08T14:02:13.412Z",
 "channel": "Provider",
 "level": "info",
 "args": ["chat connected", { "chatId": 4421 }]
}

Die genaue Auswahl der Kanäle und Nachrichteninhalte kann sich zwischen SDK-Releases ändern. Betrachten Sie die Logs als Debugging-Hilfe, nicht als stabiles Parsing-Ziel. Erstellen Sie keine Produktionslogik, die von bestimmten Kanalnamen oder Nachrichtenstrings abhängt.

Umfang und empfohlene Verwendung

getLogs gibt SDK-interne Datensätze zurück, die bei der Diagnose von Integrationsproblemen mit dem Headless Web SDK selbst helfen sollen. Der primäre Anwendungsfall ist die Supportdiagnose: Wenn ein Endnutzer ein Problem meldet, kann Ihre Anwendung das Ergebnis von getLogs erfassen und an das Support-Ticket anhängen, das an die CCAI Platform gesendet wird.

Die zurückgegebenen Logs enthalten nicht:

• Anwendungstelemetrie, Geschäftsereignisse oder Nutzeraktionen auf der Hostseite.

• Netzwerkfehler, die der Browser nicht an das SDK weitergibt (z.B. CORS-, Mixed-Content- oder Zertifikatsfehler).

• Serverseitige Anfrage-Traces oder Backend-Details, die über den an das SDK zurückgegebenen HTTP-Status hinausgehen.

getLogs ist kein Ersatz für Ihre eigenen Beobachtbarkeitstools. Wir empfehlen, das SDK mit Folgendem zu kombinieren:

• Ein browserseitiger Fehler-/RUM-Tracker (Sentry, Datadog Browser RUM, New Relic Browser oder Ähnliches).

• Serverseitiges Logging auf Ihrem Authentifizierungsendpunkt (der authenticate-Callback, den das SDK aufruft).

• Listener auf Anwendungsebene für chat.disconnected, chat.timeout und chat.ended, wenn Sie Signale zum Chat-Lebenszyklus an Ihre eigene Telemetrie-Pipeline weiterleiten müssen.

Nutzungsbeispiel

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

printLogs

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

Methodensignatur

printLogs(): Promise<void>

Nutzungsbeispiel

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

Sonstiges

Name	Beschreibung
runTrigger	Prüft proaktive Trigger, die ausgelöst werden sollten.
getAfterHourMessage	Nachricht für die Weiterleitung außerhalb der Geschäftszeiten abrufen.

runTrigger

Iteriert über konfigurierte proaktive Trigger und ruft den bereitgestellten Callback für alle Trigger auf, deren Bedingungen erfüllt sind (URL-Keywords, Anzahl der Seitenbesuche, Verweildauer, Besuchertyp).

Methodensignatur

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

Schnittstellen

interface TriggerItem {
 id: number;
 menu_id: number;
 messages: TriggerMessage[];
 keywords_included?: string[];
 keywords_included_or?: string[][];
 keywords_excluded?: string[];
 keywords_excluded_or?: string[][];
 lang?: string;
 page_visit_count: number;
 stay_time: number;
 visitor_type: string;
}
interface TriggerMessage {
 lang: string;
 text: string;
}

Nutzungsbeispiel

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

getAfterHourMessage

Gibt die konfigurierte Umleitungsnachricht zurück, die angezeigt werden soll, wenn der angeforderte Kanal außerhalb der Öffnungszeiten liegt.

Methodensignatur

Die Methodensignatur lautet:

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

Rückgabewert

Gibt einen String mit einer konfigurierten Nachricht zurück.

Nutzungsbeispiel

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