Méthodes de l'API du SDK Web headless

Cette page liste les méthodes d'API disponibles pour le SDK Web sans interface utilisateur.

Entreprise et menus

Méthodes de gestion des valeurs et des menus de l'entreprise.

getTrigger

Cette méthode détecte les déclencheurs proactifs de la page actuelle. Il renvoie le déclencheur correspondant actuel ou null.

const trigger = await client.getTrigger()

getCompany

Cette méthode récupère les informations sur l'entreprise.

Signature de la méthode

getCompany(): Promise<CompanyResponse>

Valeur renvoyée

Renvoie un objet CompanyResponse.

Interfaces

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

Exemple d'utilisation

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

getMenus

Cette méthode liste tous les éléments de menu disponibles pour le locataire.

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet MenuResponse.

Interfaces

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

Exemple d'utilisation

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

getWaitTimes

Cette méthode permet d'obtenir le temps d'attente pour le canal de chat ou d'appel d'un menu.

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet WaitTimeResponse.

Interfaces

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

Exemple d'utilisation

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

Appels

Méthodes de gestion des appels planifiés via le SDK.

createCall

Cette méthode permet de créer un appel instantané ou programmé.

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet CallResponse.

Interfaces

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

Exemple d'utilisation

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

loadCall

Cette méthode récupère les informations d'appel pour un ID d'appel spécifié.

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet CallResponse.

Interfaces

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

Exemple d'utilisation

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

cancelCall

Cette méthode annule un appel.

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet CallResponse.

Interfaces

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

Exemple d'utilisation

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

getTimeSlots

Récupère les créneaux horaires disponibles pour les appels planifiés dans un menu donné.

Lorsqu'elle est appelée avec un objet d'options GetTimeSlotsRequest, cette méthode accepte les éléments suivants :

• Planification avancée des appels : useAdvancedCallScheduling: true

• Reprogrammer un appel existant : rescheduleCallId

L'ancienne signature de chaîne lang est toujours acceptée et redirige vers le même point de terminaison, avec uniquement lang renseigné.

Signature de la méthode

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

Avertissement : La signature précédente, getTimeSlots(menuId, lang?), est obsolète. Google recommande de migrer vers la nouvelle signature basée sur les options, comme indiqué ici. L'ancienne signature continue de fonctionner, mais elle pourra être désactivée dans une version ultérieure.

Valeur renvoyée

Renvoie un tableau de chaînes de créneaux horaires.

Interfaces

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

Exemple d'utilisation

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

Cette méthode vérifie si des créneaux horaires sont disponibles pour un menu donné sans récupérer la liste complète des créneaux horaires. Vous pouvez l'utiliser pour afficher conditionnellement les options de planification dans l'UI.

Signature de la méthode

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

Valeur renvoyée

Renvoie true si des créneaux horaires sont disponibles. Dans le cas contraire, cette valeur est définie sur false.

Exemple d'utilisation

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

Discussions

Méthodes de gestion des discussions avec le SDK.

createChat

Cette méthode permet de créer un chat.

Signature de la méthode

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

Valeur renvoyée

Renvoie une instance Chat.

Interfaces

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

Exemple d'utilisation

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

loadChat

Cette méthode récupère les informations de discussion pour un ID de discussion donné.

Signature de la méthode

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

Valeur renvoyée

Renvoie une instance Chat.

Exemple d'utilisation

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

loadOngoingChat

Cette méthode permet d'obtenir l'instance de chat en cours.

Signature de la méthode

loadOngoingChat(): Promise<Chat | null>

Valeur renvoyée

Renvoie une instance Chat si elle est trouvée, ou null si aucune discussion n'est en cours. Nettoie les valeurs de stockage si le chat n'est pas en cours.

Exemple d'utilisation

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

resumeChat

Cette méthode permet de reprendre une discussion fermée.

Signature de la méthode

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

Valeur renvoyée

Renvoie une instance de chat.

Exemple d'utilisation

client.resumeChat(1234)

finishChat

Cette méthode définit l'état du chat sur finished.

Signature de la méthode

finishChat(): Promise<void>

Exemple d'utilisation

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

destroyChat

Cette méthode détruit la discussion en cours.

Signature de la méthode

destroyChat(): Promise<void>

Exemple d'utilisation

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

fetchMessages

Cette méthode permet d'obtenir tous les messages précédents. En cas d'échec, un tableau vide est renvoyé. Vous utiliserez cette méthode une fois le chat connecté.

Signature de la méthode

fetchMessages(): Promise<MessageResponse[]>

Valeur renvoyée

Renvoie un tableau de MessageResponse. Renvoie un tableau vide en cas d'échec.

Interfaces

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

Exemple d'utilisation

const messages = client.fetchMessages()

sendTextMessage

Cette méthode envoie un message texte.

Signature de la méthode

sendTextMessage(rawContent: string): Promise<void>

Exemple d'utilisation

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

sendFileMessage

Cette méthode envoie un message de fichier.

Signature de la méthode

sendFileMessage(file: File): Promise<number>

Valeur renvoyée

Renvoie l'ID du message ou -1 en cas d'échec.

Exemple d'utilisation

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

sendPreviewMessage

Permet d'envoyer un aperçu du message à l'adaptateur d'agent. Le message d'aperçu ne s'affiche dans l'adaptateur d'agent que si la méthode startTyping est appelée. Le message d'aperçu ne s'affiche que jusqu'à ce que le message final soit envoyé ou que la méthode stopTyping soit appelée. Pour en savoir plus, consultez Expérience de l'agent : aperçu des messages.

Signature de la méthode

sendPreviewMessage(content: string): Promise<void>

Exemple d'utilisation

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

Signature de la méthode

startTyping()

Exemple d'utilisation

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

stopTyping

Signature de la méthode

stopTyping()

Exemple d'utilisation

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

getChatDeflection

Cette méthode permet d'obtenir la configuration de la déviation du chat.

Signature de la méthode

getChatDeflection(): Promise<ChatDeflectionResponse>

Valeur renvoyée

Renvoie un objet ChatDeflectionResponse.

Interfaces

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

Exemple d'utilisation

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

sendChatTranscripts

Envoyez les transcriptions de chat actuelles aux adresses e-mail spécifiées.

Signature de la méthode

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

Exemple d'utilisation

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

downloadChatTranscript

Signature de la méthode

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Valeur renvoyée

Renvoie l'objet de transcription.

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

Exemple d'utilisation

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

getPdfStatus

Signature de la méthode

getPdfStatus(id: number): Promise<RequestReturn>

Valeur renvoyée

Renvoie l'objet d'état du PDF.

Interfaces

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

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

Exemple d'utilisation

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

Cette méthode permet d'obtenir les questions de l'enquête par chat.

Signature de la méthode

getChatSurvey(): Promise<ChatSurveyResponse>

Valeur renvoyée

Renvoie un objet ChatSurveyResponse.

Interfaces

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

Exemple d'utilisation

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

sendChatSurvey

Cette méthode envoie une enquête au consommateur.

Signature de la méthode

sendChatSurvey(answers: SurveyAnswers): void

Interfaces

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

Exemple d'utilisation

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

sendChatRate

Cette méthode envoie les commentaires de l'utilisateur final pour la discussion en cours lorsque celle-ci est terminée.

Signature de la méthode

sendChatRate(data: RateRequest): Promise<void>

Interfaces

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

Exemple d'utilisation

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

escalateChat

Signature de la méthode

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

Interfaces

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

Exemple d'utilisation

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

trackChatEscalation

Signature de la méthode

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

Exemple d'utilisation

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

trackChatEndUserEvent

Signature de la méthode

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Valeur renvoyée

Ne renvoie aucune valeur.

Interfaces

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

Exemple d'utilisation

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

getChatHistory

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet ChatHistoryResponse.

Interfaces

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

Exemple d'utilisation

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

E-mails

Méthodes de traitement des e-mails d'assistance.

createEmails

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet EmailResponse en cas d'échec ou de réussite.

Interfaces

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

Exemple d'utilisation

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

Signature de la méthode

getProhibitedFileTypes(): Promise<FileTypeItem[]>

Valeur renvoyée

Renvoie un tableau de FileTypeItem.

Interfaces

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

Exemple d'utilisation

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

Partage d'écran

Méthodes de gestion de la fonctionnalité de partage d'écran.

createCobrowseCode

Cette méthode crée un code de partage d'écran.

Signature de la méthode

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

Valeur renvoyée

Renvoie une chaîne de code de partage d'écran ou une chaîne vide en cas d'échec.

Exemple d'utilisation

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

startCobrowse

Signature de la méthode

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

Exemple d'utilisation

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

restoreCobrowseSession

Cette méthode tente de restaurer une session de partage d'écran précédemment active après la réouverture de la fenêtre du navigateur ou le rechargement du widget.

Signature de la méthode

restoreCobrowseSession(): Promise<void>

Valeur renvoyée

Cela renvoie Promise<void>. Cette méthode est une opération sans effet (elle renvoie immédiatement sans erreur) si le partage d'écran n'est pas activé pour votre instance ou si aucune session de partage d'écran précédente n'existe dans le stockage.

Remarque : Cette méthode ne génère pas d'erreur. Si une erreur se produit lors de la restauration de la session de partage d'écran, la méthode consigne l'erreur en interne, efface la session de partage d'écran stockée, puis renvoie une réponse propre. Vous n'avez pas besoin de gérer les erreurs avec try et catch.

Exemple d'utilisation

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

getMessageAttachment

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet File s'il est trouvé, ou null si ce n'est pas le cas.

Exemple d'utilisation

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

Agents virtuels post-session

Méthodes de gestion des agents virtuels post-session.

updatePostSession

Met à jour l'état de l'agent virtuel post-session pour le chat en cours. Utilisez-le pour signaler l'état de préparation, la progression ou la fin d'un flux d'agent virtuel post-session. Cette méthode renvoie immédiatement une opération sans effet si postSessionStatus est FINISHED ou WAITING, car ces transitions sont gérées en interne. Cette méthode dispose d'une logique de nouvelle tentative interne spécifique à l'état IN_PROGRESS sur une réponse 400. Les appelants n'ont donc pas besoin d'implémenter leur propre nouvelle tentative pour ce cas.

Signature de la méthode

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

Interfaces

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

Exemple d'utilisation

try {
  // Without opt-in selection
  await client.updatePostSession(PostSessionStatus.READY)

  // With opt-in selection
  await client.updatePostSession(PostSessionStatus.READY, true)
} catch (error) {
  // handle error (e.g., show a notification to the user)
}

Interface associée

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

• post_session_required : post-session requise après un chat.
• post_session_opt_in_required : si l'activation est activée.
• post_session_transfer_status : énumération PostSessionStatus.

Débogage

Méthodes de débogage du SDK.

getLogs

Récupère les journaux de débogage internes collectés par le SDK, y compris les journaux au niveau du pont et au niveau racine. Cela est utile pour résoudre les problèmes d'intégration.

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet contenant deux tableaux de LogHistoryData.

Interfaces

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

Remarque : Le système récupère d'abord les journaux du pont, car la récupération produit une entrée de journal racine. Par conséquent, rootLogs capture intentionnellement ce journal final.

Exemple d'utilisation

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

printLogs

Imprime tous les journaux de débogage internes directement dans la console du navigateur. Il s'agit d'une méthode pratique qui appelle getLogs() en interne et met en forme la sortie.

Signature de la méthode

printLogs(): Promise<void>

Exemple d'utilisation

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

Autres

Méthodes SDK diverses.

runTrigger

Signature de la méthode

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

Exemple d'utilisation

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

getAfterHourMessage

Signature de la méthode

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

Valeur renvoyée

Renvoie une chaîne contenant un message configuré.

Exemple d'utilisation

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