Metodi dell'API SDK web headless

Questa pagina elenca i metodi API disponibili per l'SDK web headless.

Azienda e menu

Metodi per la gestione dei valori e dei menu dell'azienda.

getTrigger

Questo metodo rileva i trigger proattivi della pagina corrente. Restituisce l'attivatore corrente corrispondente o null.

const trigger = await client.getTrigger()

getCompany

Questo metodo recupera le informazioni sull'azienda.

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;
  cobrowse_domain?: string;
}

Esempio di utilizzo

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

getMenus

Questo metodo elenca tutte le voci di menu disponibili per il tenant.

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

interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
}

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

Questo metodo recupera il tempo di attesa per il canale di chat o di chiamata di un menu.

Firma del metodo

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

Valore restituito

Restituisce un oggetto WaitTimeResponse.

Interfacce

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

Esempio di utilizzo

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

Chiamate

Metodi per gestire le chiamate pianificate tramite l'SDK.

createCall

Questo metodo crea una chiamata istantanea o pianificata.

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;
  use_advanced_call_scheduling?: boolean;
}

Esempio di utilizzo

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

loadCall

Questo metodo recupera le informazioni sulla chiamata per un ID chiamata specificato.

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

Questo metodo annulla una chiamata.

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 di opzioni GetTimeSlotsRequest, questo metodo supporta quanto segue:

• Pianificazione avanzata delle chiamate: useAdvancedCallScheduling: true

• Ripianificazione di una chiamata esistente: rescheduleCallId

La firma della stringa lang ritirata è ancora supportata e indirizza allo stesso endpoint, con solo lang compilato.

Firma del metodo

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

Avviso :la firma precedente, getTimeSlots(menuId, lang?), è stata ritirata. Google consiglia di eseguire la migrazione alla nuova firma basata sulle opzioni, come documentato qui. La vecchia firma continua a funzionare, ma potrebbe essere disattivata in una versione successiva.

Valore restituito

Restituisce un array di stringhe di fasce orarie.

Interfacce

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

Esempio di utilizzo

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

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

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

Metodi per gestire le chat con l'SDK.

createChat

Questo metodo crea una nuova chat.

Firma del metodo

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

Valore restituito

Restituisce un'istanza Chat.

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 = client.createChat(123, { lang: 'en' })
} catch (error) {
  // handle error
}

loadChat

Questo metodo recupera le informazioni sulla chat per un determinato ID chat.

Firma del metodo

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

Valore restituito

Restituisce un'istanza Chat.

Esempio di utilizzo

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

loadOngoingChat

Questo metodo viene utilizzato per ottenere l'istanza di chat in corso.

Firma del metodo

loadOngoingChat(): Promise<Chat | null>

Valore restituito

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

Esempio di utilizzo

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

resumeChat

Questo metodo riprende una chat chiusa.

Firma del metodo

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

Valore restituito

Restituisce un'istanza di chat.

Esempio di utilizzo

client.resumeChat(1234)

finishChat

Questo metodo cambia lo stato della chat in finished.

Firma del metodo

finishChat(): Promise<void>

Esempio di utilizzo

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

destroyChat

Questo metodo interrompe la chat in corso.

Firma del metodo

destroyChat(): Promise<void>

Esempio di utilizzo

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

fetchMessages

Questo metodo viene utilizzato per recuperare tutti i messaggi precedenti. In caso di errore, viene restituito un array vuoto. Utilizzerai questo metodo dopo che la chat è connessa.

Firma del metodo

fetchMessages(): Promise<MessageResponse[]>

Valore restituito

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

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

Esempio di utilizzo

const messages = client.fetchMessages()

sendTextMessage

Questo metodo invia un messaggio.

Firma del metodo

sendTextMessage(rawContent: string): Promise<void>

Esempio di utilizzo

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

sendFileMessage

Questo metodo invia un messaggio di file.

Firma del metodo

sendFileMessage(file: File): Promise<number>

Valore restituito

Restituisce l'ID messaggio o -1 in caso di errore.

Esempio di utilizzo

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

sendPreviewMessage

Utilizzato per inviare un'anteprima del messaggio all'adattatore dell'agente. Il messaggio di anteprima viene visualizzato nell'adattatore dell'agente solo se viene chiamato il metodo startTyping. Il messaggio di anteprima viene visualizzato solo fino all'invio del messaggio finale o alla chiamata del metodo stopTyping. Per ulteriori informazioni, vedi Esperienza dell'agente - Anteprima messaggio.

Firma del metodo

sendPreviewMessage(content: string): Promise<void>

Esempio di utilizzo

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

Firma del metodo

startTyping()

Esempio di utilizzo

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

stopTyping

Firma del metodo

stopTyping()

Esempio di utilizzo

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

getChatDeflection

Questo metodo recupera la configurazione della deviazione della chat.

Firma del metodo

getChatDeflection(): Promise<ChatDeflectionResponse>

Valore restituito

Restituisce un oggetto ChatDeflectionResponse.

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 le trascrizioni della chat corrente alle email specificate.

Firma del metodo

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

Esempio di utilizzo

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

downloadChatTranscript

Firma del metodo

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Valore restituito

Restituisce l'oggetto della trascrizione.

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

Esempio di utilizzo

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

getPdfStatus

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 = resp.headers['x-transcript-status'];

// otherwise use status on data
const data: PdfStatusResponse = resp.data
console.log(data.status)

getChatSurvey

Questo metodo viene utilizzato per ottenere le domande del sondaggio sulla chat.

Firma del metodo

getChatSurvey(): Promise<ChatSurveyResponse>

Valore restituito

Restituisce un oggetto ChatSurveyResponse.

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()
  console.log(data.questions)
} catch (error) {
  // handle error
}

sendChatSurvey

Questo metodo invia un sondaggio al consumatore.

Firma del metodo

sendChatSurvey(answers: SurveyAnswers): void

Interfacce

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

Esempio di utilizzo

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

sendChatRate

Questo metodo invia il feedback dell'utente finale per la chat corrente al termine della chat.

Firma del metodo

sendChatRate(data: RateRequest): Promise<void>

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

Firma del metodo

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

Interfacce

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

Esempio di utilizzo

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

trackChatEscalation

Firma del metodo

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

Esempio di utilizzo

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

trackChatEndUserEvent

Firma del metodo

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Valore restituito

Restituisce void.

Interfacce

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

Esempio di utilizzo

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

getChatHistory

Firma del metodo

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

Valore restituito

Restituisce un oggetto ChatHistoryResponse.

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 = client.getChatHistory(page: number)
  console.log(data)
} catch (error) {
  console.log(error)
}

Email

Metodi per la gestione delle email di assistenza.

createEmails

Firma del metodo

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

Valore restituito

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

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

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

Metodi per gestire la funzionalità di condivisione schermo.

createCobrowseCode

Questo metodo crea un codice di condivisione dello schermo.

Firma del metodo

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

Valore restituito

Restituisce una stringa di codice di condivisione schermo o una stringa vuota in caso di errore.

Esempio di utilizzo

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

startCobrowse

Firma del metodo

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

Esempio di utilizzo

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

restoreCobrowseSession

Questo metodo tenta di ripristinare una sessione di condivisione schermo attiva in precedenza dopo la riapertura della finestra del browser o il ricaricamento del widget.

Firma del metodo

restoreCobrowseSession(): Promise<void>

Valore restituito

Resi Promise<void>. Questo metodo è un'operazione no-op (restituisce immediatamente senza errori) se la condivisione dello schermo non è abilitata per la tua istanza o se non esiste una sessione di condivisione dello schermo precedente nello spazio di archiviazione.

Nota: questo metodo non genera un errore. Se si verifica un errore durante il ripristino della sessione di condivisione schermo, il metodo registra l'errore internamente, cancella la sessione di condivisione schermo memorizzata e poi viene restituito in modo pulito. Non devi gestire gli errori con try e 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()

getMessageAttachment

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
}

Agenti virtuali post-sessione

Metodi per la gestione degli agenti virtuali post-sessione.

updatePostSession

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 dell'agente virtuale post-sessione. Questo metodo viene restituito immediatamente come no-op se postSessionStatus è FINISHED o WAITING perché queste transizioni vengono gestite internamente. Questo metodo ha una logica di ripetizione interna specifica per lo stato IN_PROGRESS in una risposta 400, quindi i chiamanti non devono 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: se l'attivazione è abilitata.
• post_session_transfer_status: un'PostSessionStatusenumerazione.

Debug

Metodi per il debug dell'SDK.

getLogs

Recupera i log di debug interni raccolti dall'SDK, inclusi i log a livello di bridge e di root. Ciò è 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: il sistema recupera prima i log del bridge perché il recupero produce una voce di log radice. Di conseguenza, rootLogs acquisisce intenzionalmente questo log finale.

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. Si tratta di un metodo pratico che chiama internamente getLogs() e formatta l'output.

Firma del metodo

printLogs(): Promise<void>

Esempio di utilizzo

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

Vari

Metodi SDK vari.

runTrigger

Firma del metodo

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

Esempio di utilizzo

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

getAfterHourMessage

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
}