Metodi dell'API SDK web headless

In questa pagina sono elencati i metodi API disponibili per l'SDK web headless.

Azienda e menu

Metodi per la gestione dei valori e dei menu aziendali.

Metodi

L'SDK headless fornisce vari metodi che possono essere chiamati nell'istanza del client.

Ecco alcuni esempi:

Azienda e menu

Nome metodo	Descrizione
getCompany	Recupera le informazioni sull'azienda configurate.
getMenus	Elenca tutti i menu disponibili per un determinato tenant.
getWaitTimes	Visualizza i tempi di attesa attuali per i vari canali in un menu.

getCompany

Recupera le informazioni sull'azienda configurate per l'istanza autenticata, tra cui il nome dell'azienda, le lingue supportate e le impostazioni delle funzionalità. Questo metodo imposta anche l'identificatore dell'istanza interna (OPTIONS.tenant) come effetto collaterale, motivo per cui in genere è la prima chiamata effettuata dopo la creazione di un client.

Firma del metodo

getCompany(): Promise<CompanyResponse>

Valore restituito

Restituisce un oggetto CompanyResponse.

Interfacce

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

Esempio di utilizzo

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

getMenus

Questo metodo viene utilizzato per elencare tutte le voci di menu disponibili per l'istanza. Il campo MenuResponse.direct indica ai chiamanti se il risultato proviene da un tasto di accesso diretto (direct.key: true) o dall'accesso diretto a livello di utente (direct.user: true). Entrambi influiscono sulla modalità di presentazione dei menu.

Firma del metodo

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

Valore restituito

Restituisce un oggetto MenuResponse.

Interfacce

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

Esempio di utilizzo

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

getWaitTimes

Recupera il tempo di attesa stimato (in secondi) per i canali di chat e chiamata vocale di un determinato menu.

Firma del metodo

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

Valore restituito

Restituisce un oggetto WaitTimeResponse o null.

Interfacce

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

Esempio di utilizzo

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

Chiamate

Nome	Descrizione
createCall	Crea una chiamata istantanea o programmata.
loadCall	Ottieni informazioni da un ID chiamata specifico.
cancelCall	Annulla la chiamata con l'ID chiamata specificato.
getTimeSlots	Ottieni le fasce orarie disponibili per le chiamate programmate per un determinato menu.
fetchTimeSlotAvailability	Controlla se sono disponibili fasce orarie per un determinato menu.

createCall

Crea una nuova chiamata per il menu specificato. Può essere una chiamata istantanea o una chiamata pianificata, a seconda che venga fornito o meno il campo scheduled_at. Il tipo di chiamata (web_instant_call o web_scheduled_call) viene determinato automaticamente in base alla presenza di scheduled_at. reschedule_call_id viene inviato al livello più alto della richiesta, separato dal corpo della chiamata. Il campo menu_id nella risposta viene normalizzato dal campo selected_menu.id dell'API.

Firma del metodo

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

Valore restituito

Restituisce un oggetto CallResponse.

Interfacce

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

Esempio di utilizzo

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

loadCall

Il metodo loadCall recupera le informazioni su una chiamata specifica, identificata dal suo ID.

Firma del metodo

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

Valore restituito

Restituisce un oggetto CallResponse.

Interfacce

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

Esempio di utilizzo

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

cancelCall

Annulla una chiamata esistente in base al relativo ID. In genere viene utilizzato per annullare una chiamata programmata che non è ancora stata effettuata.

Firma del metodo

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

Valore restituito

Restituisce un oggetto CallResponse.

Interfacce

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

Esempio di utilizzo

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

getTimeSlots

Recupera le fasce orarie disponibili per le chiamate programmate in un determinato menu. Se chiamato con un oggetto opzioni GetTimeSlotsRequest, supporta la ripianificazione di una chiamata esistente utilizzando rescheduleCallId. La firma della stringa lang deprecata rimane supportata e indirizza allo stesso endpoint con solo lang compilato. Restituisce un array di stringhe di fasce orarie.

Firma del metodo

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

Avviso: la firma precedente getTimeSlots(menuId, lang?) è stata ritirata. Esegui la migrazione alla nuova firma basata su opzioni mostrata in precedenza. La vecchia firma continuerà a funzionare, ma potrebbe essere rimossa in una release futura.

Valore restituito

Restituisce un array di stringhe (fasce orarie).

Interfacce

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

Esempio di utilizzo

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

Questo metodo verifica se sono disponibili fasce orarie per un determinato menu, senza recuperare l'elenco completo delle fasce orarie. È utile per mostrare in modo condizionale le opzioni di pianificazione nella UI.

Ambito

fetchTimeSlotAvailability si applica solo agli appuntamenti per chiamate vocali programmate (richiamata). Non restituisce informazioni sui canali di chat, email o chiamata istantanea. Il menu fornito deve essere configurato per supportare le chiamate vocali programmate, con orari di apertura definiti e almeno un agente in coda per quel menu.

Casi d'uso tipici:

• Eseguire il rendering condizionale di un invito all'azione "Prenota un richiamo" solo quando sono disponibili fasce orarie.

• Passaggio a un flusso di deviazione (ad es. email, messaggio fuori orario) quando non sono disponibili slot, senza pagare il costo di una chiamata getTimeSlots completa.

• Pre-flight di un'azione di ripianificazione prima di chiamare getTimeSlots con un rescheduleCallId.

Firma del metodo

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

Valore restituito

Restituisce true se sono disponibili fasce orarie, altrimenti false.

Esempio di utilizzo

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

Chat

Nome	Descrizione
createChat	Crea una nuova chat.
loadChat	Recupera la chat con l'ID chat specificato.
loadOngoingChat	Tenta di caricare una chat in corso.
resumeChat	Riprende una chat ignorata con l'ID chat specificato.
finishChat	Imposta lo stato della chat corrente su "Terminata".
destroyChat	Chiama finishChat e distrugge la chat corrente
fetchMessages	Recupera i messaggi precedenti; restituisce [] in caso di errore.
sendTextMessage	Invia un messaggio.
sendFileMessage	Invia un messaggio con un file e restituisce -1 in caso di errore di caricamento.
sendPreviewMessage	Invia un messaggio di anteprima.
getChatDeflection	Recupera la configurazione della deviazione della chat.
sendChatTranscripts	Invia la trascrizione della chat agli indirizzi email forniti.
downloadChatTranscript	Scarica la trascrizione della chat.
getPdfStatus	Recupera lo stato del PDF di una trascrizione.
getChatSurvey	Recupera le domande del sondaggio della chat.
sendChatSurvey	Invia il feedback degli utenti dal sondaggio.
sendChatRate	Inviare feedback degli utenti sulla chat.
escalateChat	Assegna una chat da un agente virtuale a un agente umano.
trackChatEscalation	Monitora l'evento di escalation della chat.
trackChatEndUserEvent	Monitora un evento dell'utente finale.
getChatHistory	Recupera le cronologie di una determinata chat.

Check-in in chat

Il check-in chiede a un consumatore di confermare di essere pronto prima di connettersi a un agente. Questa sezione documenta i metodi dell'SDK web headless per l'implementazione di questa esperienza. Per informazioni su cos'è il check-in, su come viene attivato e configurato (tempo di attesa, timeout, posizione in coda, comportamento di rientro) e sui report, consulta Check-in per Chat.

Nome	Descrizione
checkIn	Invia un segnale al server per confermare la presenza dell'utente nella coda.
exitCheckIn	Rimuove l'utente dalla coda di check-in.
notifyCheckInState	Notifica al backend lo stato di visibilità della finestra modale di conferma.
rejoinChat	Riposiziona l'utente in coda dopo la mancata conferma del check-in.
trackCheckInEvent	Invia un segnale al backend quando gli eventi di check-in sono stati attivati dalla UI.

checkIn

Invia un segnale di conferma al server per indicare che il consumatore è presente e pronto a connettersi con un agente durante la finestra di conferma. Aggiorna localmente il check_in_status della chat dopo che il server ha confermato. Utilizzalo in risposta all'evento chat.checkInRequested.

Firma del metodo

checkIn(): Promise<CheckInResponse>

Valore restituito

Restituisce un oggetto CheckInResponse.

Interfacce

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',
}

Esempio di utilizzo

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

exitCheckIn

Segnala al server che il consumatore ha scelto di uscire dalla coda di registrazione. Aggiorna check_in_status in locale. Dopo aver chiamato questo metodo, il consumer non riceverà una connessione con l'agente per il ciclo di check-in corrente.

Firma del metodo

exitCheckIn(): Promise<CheckInResponse>

Valore restituito

Restituisce un oggetto CheckInResponse.

Interfacce

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',
}

Esempio di utilizzo

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

notifyCheckInState

Informa il server dello stato di visibilità corrente della finestra modale di conferma, ovvero se il widget è ridotto a icona o se la scheda del browser non è attiva. Il server utilizza queste informazioni per prendere decisioni sui tempi di sincronizzazione. Deve essere chiamato ogni volta che la visibilità o lo stato attivo della scheda del widget cambiano mentre l'evento chat.checkInRequested è attivo.

Firma del metodo

notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>

Interfacce

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

Esempio di utilizzo

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

rejoinChat

Riposiziona il consumatore nella coda dopo che non ha confermato un check-in entro il tempo assegnato. Aggiorna check_in_status in locale. Utilizzalo in risposta all'evento chat.checkInTimedOut se il consumatore vuole ancora connettersi.

Firma del metodo

rejoinChat(): Promise<CheckInResponse>

Valore restituito: restituisce un oggetto CheckInResponse.

Interfacce

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',
}

Esempio di utilizzo

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

trackCheckInEvent

Informa il server che la finestra modale di conferma è stata mostrata al consumatore. Chiama questo metodo una volta, subito dopo aver presentato l'interfaccia utente di check-in in risposta a chat.checkInRequested. Il server lo utilizza per l'analisi operativa dei tassi di presentazione dei check-in. La chiamata è attesa internamente e restituisce un Promise<void> che può rifiutare, quindi inseriscila in try/catch (come nell'esempio seguente).

Firma del metodo

trackCheckInEvent(): Promise<void>

Esempio di utilizzo

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

getMessageAttachment

Recupera un allegato idoneo associato a un messaggio chat specifico. Recupera solo se il messaggio è stato inviato da un utente non finale ($userType !== 'end_user') ed è di un tipo di allegato supportato (foto, video, audio, documento). Restituisce null per qualsiasi messaggio che non soddisfa entrambe le condizioni, non solo per i messaggi senza media_id. Salva il file recuperato nella cache multimediale locale della chat dopo il recupero.

Firma del metodo

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

Valore restituito

Restituisce un oggetto File se trovato o null se non applicabile.

Esempio di utilizzo

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

createChat

Crea una nuova sessione di chat per il menu specificato. Se vuoi, puoi specificare la lingua, un messaggio di saluto, un ID trigger, un ID ticket e dati personalizzati da inviare con la chat.

Dopo la chiamata API iniziale, il metodo esegue il polling del server finché non diventa disponibile un provider_channel_id o la chat non viene annullata o terminata. Se un canale del provider diventa disponibile, il metodo avvia la connessione al provider in tempo reale. La connessione potrebbe essere ancora in fase di completamento quando la promise viene risolta. Ascolta l'evento chat.connectedMessages per sapere quando la connessione e il recupero iniziale dei messaggi sono stati completati.

Firma del metodo

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

Valore restituito

Restituisce un'istanza Chat.

Avviso: questo metodo genera immediatamente un errore se è già in corso una chat. Controlla se esiste una sessione prima di chiamare.

Interfacce

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

Esempio di utilizzo

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

loadChat

Recupera una sessione di chat esistente in base al suo ID.

Se la chat caricata non è più in corso, il metodo cancella l'ID chat memorizzato e il nonce di co-browsing dallo spazio di archiviazione locale. Questo avviene anche in caso di errore, quindi i chiamanti non devono gestire manualmente la pulizia dello spazio di archiviazione dopo un caricamento non riuscito.

Firma del metodo

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

Valore restituito

Restituisce un'istanza Chat.

Avviso: in caso di errore, questo metodo cancella gli ID sessione di chat e navigazione condivisa archiviati dallo spazio di archiviazione locale prima di eseguire nuovamente il lancio. Qualsiasi riferimento alla sessione memorizzato viene invalidato dopo una chiamata non riuscita.

Esempio di utilizzo

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

loadOngoingChat

Tenta di caricare la sessione di chat in corso, se esistente. Restituisce null se non viene trovata alcuna chat in corso.

Firma del metodo

loadOngoingChat(): Promise<Chat | null>

Valore restituito

Restituisce un'istanza Chat se trovata o null se non esiste una chat in corso. Pulirà i valori di archiviazione se la chat non è in corso.

Avviso: in caso di errore, questo metodo cancella l'ID chat archiviato dallo spazio di archiviazione locale prima di eseguire nuovamente il rethrow. Qualsiasi riferimento alla sessione archiviato viene invalidato dopo una chiamata non riuscita.

Esempio di utilizzo

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

resumeChat

Riprende una sessione di chat ignorata in precedenza in base al suo ID, consentendo al consumatore di continuare la conversazione.

Se il client ha già un riferimento a una chat con lo stesso ID, il metodo esegue un cortocircuito: applica la patch allo stato queued nell'istanza esistente anziché recuperarne una nuova. Se gli ID non corrispondono, viene creata e registrata una nuova istanza Chat.

Firma del metodo

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

Valore restituito

Restituisce un'istanza Chat.

Esempio di utilizzo

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

finishChat

Imposta lo stato della sessione di chat corrente su "terminata". In questo modo, la chat viene terminata dal lato del consumatore.

Se la chat è connessa al provider in tempo reale e si trova in uno stato terminato dopo la richiesta PATCH, il metodo si disconnette anche dal provider. I chiamanti non devono chiamare il numero destroyChat se l'unico obiettivo è terminare la chat in modo educato.

Firma del metodo

finishChat(): Promise<void>

Esempio di utilizzo

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

destroyChat

Termina e distrugge la sessione di chat corrente, cancellando tutto lo stato interno. Questo metodo chiama finishChat internamente, quindi chiude l'istanza della chat. Prima di terminare la chat, il metodo la disattiva (sopprime gli eventi in tempo reale in arrivo) per evitare di elaborare i messaggi durante la chiusura. Cancella l'ID monitoraggio interno dopo l'eliminazione della chat.

Firma del metodo

destroyChat(): Promise<void>

Esempio di utilizzo

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

fetchMessages

Recupera la cronologia dei messaggi per la sessione di chat corrente dal provider in tempo reale. Deve essere chiamato dopo la connessione alla chat. Se viene chiamato prima della connessione alla chat, restituisce un array vuoto anziché generare un errore. Recupera automaticamente gli URL dei documenti per tutti i messaggi di tipo document e li unisce nella risposta. Per i messaggi di tipo server_message, recupera i contenuti dei messaggi dell'agente virtuale delle attività e li formatta in linea. Restituisce un array vuoto in caso di errore anziché generare un'eccezione.

Firma del metodo

fetchMessages(): Promise<MessageResponse[]>

Valore restituito

Restituisce un array di MessageResponse. Restituisce un array vuoto in caso di errore.

Avviso: questo metodo non genera un'eccezione in caso di errore. Restituisce un array vuoto ([]) se il recupero dei messaggi non va a buon fine. Non fare affidamento su try/catch; controlla invece il valore restituito.

Interfacce

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

Esempio di utilizzo

const messages = await client.fetchMessages()

sendTextMessage

Invia un messaggio nella sessione di chat corrente.

Il metodo sanitizza i contenuti non elaborati prima dell'invio e restituisce un risultato anticipato (no-op) se il risultato è vuoto. Se la chat si trova in un flusso di un agente virtuale per le attività (inTask), il messaggio viene instradato tramite l'endpoint dell'agente virtuale per le attività anziché tramite il canale normale. Se l'oscuramento lato server è attivo, il messaggio viene inviato utilizzando un endpoint del server anziché direttamente tramite il provider in tempo reale.

Firma del metodo

sendTextMessage(rawContent: string): Promise<void>

Esempio di utilizzo

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

sendFileMessage

Carica un file nella sessione di chat corrente tramite un processo in tre passaggi: ottenere un URL di spazio di archiviazione sul cloud pre-firmato dal server, caricare il file direttamente su quell'URL, quindi confermare il caricamento al server. Il percorso di caricamento viene determinato automaticamente dal tipo MIME del file: le immagini vengono inviate come messaggi con foto e i video come videomessaggi; gli altri tipi di file vengono indirizzati in base al loro tipo MIME. Restituisce l'ID messaggio in caso di esito positivo o -1 in caso di errore.

Firma del metodo

sendFileMessage(file: File): Promise<number>

Valore restituito

Restituisce l'ID messaggio o -1 se il caricamento non è riuscito. Tuttavia, l'invio del messaggio successivo può comunque essere rifiutato (ad esempio, ChatEndedError), quindi racchiudi la chiamata in try/catch oltre a verificare la presenza di -1.

Esempio di utilizzo

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

Invia un messaggio di anteprima nella sessione di chat corrente. I messaggi di anteprima vengono in genere utilizzati per mostrare all'agente ciò che il consumatore sta digitando prima che il messaggio venga inviato. Se sia redaction_enabled che agent_incoming_ha_enabled sono true nello stato della chat, l'anteprima viene inviata tramite un endpoint del server (POST /chats/{id}/redact_messages) anziché tramite il canale del provider in tempo reale.

Firma del metodo

sendPreviewMessage(content: string): Promise<void>

Esempio di utilizzo

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

getChatDeflection

Recupera la configurazione della deviazione della chat per la sessione di chat corrente, incluso se la deviazione è abilitata, la soglia del tempo di attesa e le opzioni di deviazione disponibili.

Restituisce null se la deviazione non è abilitata per la chat (il campo enabled della risposta del server è falso). I chiamanti devono eseguire un controllo null prima di leggere la risposta.

Firma del metodo

getChatDeflection(): Promise<ChatDeflectionResponse | null>

Valore restituito

Restituisce un oggetto ChatDeflectionResponse o null se la deviazione non è abilitata per la chat.

Interfacce

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

Esempio di utilizzo

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

sendChatTranscripts

Invia la trascrizione della chat corrente agli indirizzi email specificati.

Firma del metodo

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

Esempio di utilizzo

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

downloadChatTranscript

Avvia il download della trascrizione della chat corrente in formato PDF. Restituisce un oggetto di trascrizione che può essere utilizzato con getPdfStatus per monitorare l'avanzamento della generazione.

Firma del metodo

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Valore restituito

Restituisce l'oggetto della trascrizione.

Interfacce

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

Esempio di utilizzo

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

getPdfStatus

Controlla lo stato di generazione di un PDF della trascrizione della chat richiesto in precedenza. Utilizza l'chat_transcript_id restituito da downloadChatTranscript per eseguire il polling del completamento.

Firma del metodo

getPdfStatus(id: number): Promise<RequestReturn>

Valore restituito

Restituisce l'oggetto di stato del PDF.

Interfacce

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


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

Esempio di utilizzo

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

Recupera le domande del sondaggio post-chat configurate per la sessione di chat corrente. Il sondaggio viene presentato ai consumatori al termine di una chat.

Firma del metodo

getChatSurvey(): Promise<ChatSurveyResponse | null>

Valore restituito

Restituisce un oggetto ChatSurveyResponse o null.

Interfacce

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

Esempio di utilizzo

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

sendChatSurvey

Invia le risposte del consumatore al sondaggio post-chat. Ogni risposta è associata all'ID della domanda.

Firma del metodo

sendChatSurvey(answers: SurveyAnswers): Promise<void>

Avviso: questo metodo genera immediatamente un'eccezione se il tipo di feedback della chat non è 'survey'. I chiamanti devono controllare chat.feedbackType === 'survey' prima di chiamare o gestire l'errore.

Interfacce

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

Esempio di utilizzo

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

sendChatRate

Invia la valutazione del consumatore e il feedback facoltativo per la sessione di chat. Utilizzato quando il tipo di feedback post-chat è una valutazione anziché un sondaggio completo.

Firma del metodo

sendChatRate(data: RateRequest): Promise<void>

Avviso: questo metodo genera immediatamente un errore se il tipo di feedback della chat non è 'rate'. I chiamanti devono controllare chat.feedbackType === 'rate' prima di chiamare o gestire l'errore.

Interfacce

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

Esempio di utilizzo

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

escalateChat

Assegna la chat corrente da un agente virtuale a un agente umano.

Firma del metodo

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

Interfacce

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

Esempio di utilizzo

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

Monitora un evento di escalation della chat, registrando l'ID escalation e il canale a cui è stata eseguita l'escalation.

Firma del metodo

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

Esempio di utilizzo

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

trackChatEndUserEvent

Monitora un evento utente finale personalizzato durante la sessione di chat, che può essere utilizzato per l'analisi o per attivare flussi di lavoro di backend. Se l'oggetto data non include end_user_name e un nome è disponibile nel profilo utente autenticato, viene compilato automaticamente prima dell'invio della richiesta.

Firma del metodo

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Valore restituito

Restituisce void.

Interfacce

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

Esempio di utilizzo

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

Recupera la cronologia chat precedente del consumatore, inclusi i contenuti e i metadati dei messaggi. I risultati sono impaginati. La pagina 1 restituisce fino a 2 chat; le pagine successive restituiscono 1 chat ciascuna. Questa impaginazione asimmetrica è intenzionale e consente alla prima chiamata di precaricare il contesto della cronologia adiacente.

Firma del metodo

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

Valore restituito

Restituisce un oggetto ChatHistoryResponse o null.

Interfacce

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

Esempio di utilizzo

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

Email

Nome	Descrizione
createEmail	Invia un'email al canale email di un determinato ID menu.
getProhibitedFileTypes	Scopri i tipi di file vietati per gli allegati email.

createEmail

Invia un'email al canale email associato al menu specificato. Il consumatore può includere un nome, un indirizzo email, il corpo del messaggio e allegati facoltativi.

Firma del metodo

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

Valore restituito

Restituisce un oggetto EmailResponse in caso di esito positivo o negativo.

Interfacce

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

Esempio di utilizzo

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

Recupera l'elenco dei tipi di file non consentiti come allegati email, come configurato dall'amministratore.

Firma del metodo

getProhibitedFileTypes(): Promise<FileTypeItem[]>

Valore restituito

Restituisce un array di FileTypeItem.

Interfacce

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

Esempio di utilizzo

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

Condivisione schermo

Nome	Descrizione
createCobrowseCode	Genera un codice di co-browsing.
startCobrowse	Richiedi una sessione di co-browsing.
restoreCobrowseSession	Ripristina una sessione di co-browsing dopo la riapertura della finestra del browser.

createCobrowseCode

Genera un codice di sessione di co-browsing (condivisione schermo) univoco che può essere condiviso con un agente per avviare una sessione. Inizializza il client di co-browsing se non è ancora stato inizializzato. Riutilizza qualsiasi nonce esistente dallo spazio di archiviazione anziché generarne uno nuovo a ogni chiamata, in modo che lo stesso codice di sessione possa essere recuperato tra i caricamenti pagina.

Firma del metodo

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

Valore restituito

Restituisce una stringa di codice di co-browsing o una stringa vuota ('') in caso di errore.

Avviso: questo metodo non genera un'eccezione in caso di errore. Non fare affidamento su try/catch; controlla invece il valore restituito.

Esempio di utilizzo

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

startCobrowse

Richiede l'avvio di una sessione di navigazione condivisa (condivisione schermo) dal lato dell'utente finale durante una chat attiva.

Firma del metodo

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

Avviso: questo metodo genera un errore se la chat corrente non è stata creata con cobrowsable: true. I chiamanti possono controllare chat.cobrowsable prima di chiamare per evitare l'eccezione.

Esempio di utilizzo

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

restoreCobrowseSession

Tenta di ripristinare una sessione di navigazione condivisa precedentemente attiva dopo la riapertura della finestra del browser o il ricaricamento del widget.

Firma del metodo

restoreCobrowseSession(): Promise<void>

Valore restituito

Restituisce Promise<void>. Questo metodo è un'operazione no-op (restituisce immediatamente un risultato senza errori) se la navigazione condivisa non è attivata nelle opzioni del client o se non esiste una sessione di navigazione condivisa precedente nello spazio di archiviazione.

Avviso: questo metodo non genera errori. Se si verifica un errore durante il ripristino, il metodo registra l'errore internamente, cancella la sessione di co-browsing memorizzata e restituisce un risultato pulito. I chiamanti non hanno bisogno di try/catch.

Esempio di utilizzo

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

Agente virtuale post-sessione

Nome	Descrizione
updatePostSession	Imposta lo stato post-sessione della chat in corso.

updatePostSession

Questo metodo viene utilizzato per aggiornare lo stato dell'agente virtuale post-sessione per la chat in corso.

• Aggiorna lo stato dell'agente virtuale post-sessione per la chat in corso. Utilizzalo per segnalare l'idoneità, l'avanzamento o il completamento di un flusso di un agente virtuale post-sessione.

• Restituisce immediatamente un no-op se postSessionStatus è FINISHED o WAITING, poiché queste transizioni vengono gestite internamente.

• Dispone di una logica di ripetizione interna specifica per lo stato IN_PROGRESS in una risposta 400, in modo che i chiamanti non debbano implementare la propria ripetizione per questo caso.

Firma del metodo

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

Interfacce

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

Esempio di utilizzo

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

Interfaccia correlata

interface ChatResponse {
 //...
 post_session_required?: boolean;
 post_session_opt_in_required?: boolean;
 post_session_transfer_status?: string;
}

• post_session_required - post session required after a chat.

• post_session_opt_in_required: l'attivazione è abilitata.

• post_session_transfer_status: uno degli enum PostSessionStatus.

Debug

Nome	Descrizione
getLogs	Recupera i log di debug interni dall'SDK.
printLogs	Stampa i log di debug interni sulla console del browser.

getLogs

Recupera i log di debug interni raccolti dall'SDK, inclusi i log a livello di bridge e di root. Utile per la risoluzione dei problemi di integrazione.

Firma del metodo

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

Valore restituito

Restituisce un oggetto contenente due array di LogHistoryData.

Interfacce

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

Nota: i log del bridge vengono recuperati prima internamente, perché il recupero stesso produce una voce di log principale. Di conseguenza, rootLogs acquisisce intenzionalmente quel log finale.

Granularità

Ogni voce LogHistoryData acquisisce un singolo evento di log:

• date: timestamp ISO 8601 dell'evento.

• channel: il modulo SDK che lo ha emesso (ad es. client di primo livello, livello di chat, livello di co-browsing, provider in tempo reale).

• level: gravità dei log: debug, info, warn o error.

• args: gli argomenti non elaborati acquisiti dalla chiamata di log.

Voce di esempio:

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

L'insieme esatto di canali e contenuti dei messaggi potrebbe cambiare tra le release dell'SDK. Considera i log come un aiuto per il debug, non come un target di analisi stabile. Non creare una logica di produzione che dipenda da nomi dei canali o stringhe di messaggi specifici.

Ambito e uso consigliato

getLogs restituisce record interni all'SDK destinati a facilitare la diagnosi dei problemi di integrazione con l'SDK web headless stesso. Il caso d'uso principale è la diagnostica di assistenza: quando un utente finale segnala un problema, la tua applicazione può acquisire il risultato di getLogs e allegarlo al ticket di assistenza inviato alla piattaforma CCAI.

I log restituiti non includono:

• La telemetria dell'applicazione, gli eventi aziendali o la navigazione degli utenti della pagina host.

• Errori di rete che il browser non mostra all'SDK (ad es. errori CORS, di contenuti misti o di certificati).

• Tracce delle richieste lato server o dettagli del backend oltre allo stato HTTP restituito all'SDK.

getLogs non sostituisce i tuoi strumenti di osservabilità. Ti consigliamo di accoppiare l'SDK con:

• Un tracker di errori/RUM lato browser (Sentry, Datadog Browser RUM, New Relic Browser o equivalente).

• Logging lato server sull'endpoint di autenticazione (il callback authenticate chiamato dall'SDK).

• Listener a livello di applicazione su chat.disconnected, chat.timeout e chat.ended se devi inoltrare gli indicatori del ciclo di vita della chat alla tua pipeline di telemetria.

Esempio di utilizzo

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

printLogs

Stampa tutti i log di debug interni direttamente nella console del browser. Questo è un metodo pratico che chiama getLogs() internamente e formatta l'output.

Firma del metodo

printLogs(): Promise<void>

Esempio di utilizzo

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

Vari

Nome	Descrizione
runTrigger	Controlla se sono presenti trigger proattivi che dovrebbero essere attivati.
getAfterHourMessage	Ricevi il messaggio per la deviazione fuori orario.

runTrigger

Esegue l'iterazione dei trigger proattivi configurati e richiama il callback fornito per tutti quelli le cui condizioni sono soddisfatte (parole chiave dell'URL, numero di visite alla pagina, tempo di permanenza, tipo di visitatore).

Firma del metodo

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

Interfacce

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

Esempio di utilizzo

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

getAfterHourMessage

Restituisce il messaggio di deviazione configurato da visualizzare quando il canale richiesto è fuori dall'orario di apertura.

Firma del metodo

La firma del metodo è:

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

Valore restituito

Restituisce una stringa contenente un messaggio configurato.

Esempio di utilizzo

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