Méthodes de l'API du SDK Web headless

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

Entreprise et menus

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

Méthodes

Le SDK headless fournit différentes méthodes pouvant être appelées sur l'instance cliente.

Voici quelques exemples :

Entreprise et menus

Nom de la méthode	Description
getCompany	Récupère les informations configurées sur l'entreprise.
getMenus	Répertoriez tous les menus disponibles pour un locataire donné.
getWaitTimes	Obtenez les temps d'attente actuels pour différents canaux dans un menu.

getCompany

Récupère les informations configurées sur l'entreprise pour l'instance authentifiée, y compris le nom de l'entreprise, les langues acceptées et les paramètres des fonctionnalités. Cette méthode définit également l'identifiant d'instance interne (OPTIONS.tenant) comme effet secondaire. C'est pourquoi il s'agit généralement du premier appel effectué après la construction d'un client.

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

Exemple d'utilisation

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

getMenus

Cette méthode permet de lister tous les éléments de menu disponibles pour l'instance. Le champ MenuResponse.direct indique aux appelants si le résultat provient d'une touche d'accès direct (direct.key: true) ou d'un accès direct au niveau de l'utilisateur (direct.user: true). Ces deux éléments ont une incidence sur la façon dont les menus doivent être présentés.

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

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

Récupère le temps d'attente estimé (en secondes) pour les canaux de chat et d'appel vocal d'un menu donné.

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet WaitTimeResponse ou null.

Interfaces

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

Exemple d'utilisation

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

Appels

Nom	Description
createCall	Créez un appel instantané ou planifié.
loadCall	Obtenez des informations à partir d'un ID d'appel donné.
cancelCall	Annule l'appel avec l'ID d'appel indiqué.
getTimeSlots	Obtenez les créneaux horaires disponibles pour les appels programmés pour un menu donné.
fetchTimeSlotAvailability	Vérifiez si des créneaux horaires sont disponibles pour un menu donné.

createCall

Crée un appel pour le menu donné. Il peut s'agir d'un appel instantané ou planifié, selon que le champ scheduled_at est fourni ou non. Le type d'appel (web_instant_call ou web_scheduled_call) est déterminé automatiquement en fonction de la présence de scheduled_at. reschedule_call_id est envoyé au niveau supérieur de la requête, séparément du corps de l'appel. Le menu_id de la réponse est normalisé à partir du selected_menu.id de l'API.

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

Exemple d'utilisation

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

loadCall

La méthode loadCall récupère des informations sur un appel spécifique, identifié par son ID.

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

Annule un appel existant en fonction de son ID. Généralement utilisé pour annuler un appel planifié qui n'a pas encore été passé.

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 programmés dans un menu donné. Lorsqu'il est appelé avec un objet d'options GetTimeSlotsRequest, il permet de reprogrammer un appel existant à l'aide de rescheduleCallId. La signature de chaîne lang obsolète reste compatible et est acheminée vers le même point de terminaison avec uniquement lang renseigné. Renvoie un tableau de chaînes de créneaux horaires.

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. Migrez vers la nouvelle signature basée sur les options, présentée précédemment. L'ancienne signature continuera de fonctionner, mais pourra être supprimée dans une prochaine version.

Valeur renvoyée

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

Interfaces

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

Exemple d'utilisation

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

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. Il est utile pour afficher de manière conditionnelle les options de planification dans l'UI.

Champ d'application

fetchTimeSlotAvailability ne s'applique qu'aux rendez-vous pour un appel vocal planifié (rappel). Il ne renvoie pas d'informations sur les canaux de chat, d'e-mail ou d'appel instantané. Le menu fourni doit être configuré pour accepter les appels vocaux programmés, avec des horaires d'ouverture définis et au moins un agent en file d'attente pour ce menu.

Cas d'utilisation types :

• Afficher de manière conditionnelle un appel à l'action Planifier un rappel uniquement lorsque des créneaux sont disponibles.

• Redirection vers un flux de déviation (par exemple, e-mail, message en dehors des heures d'ouverture) lorsqu'aucun créneau n'est disponible, sans payer le coût d'un appel getTimeSlots complet.

• Effectuer un contrôle préliminaire d'une action de reprogrammation avant d'appeler getTimeSlots avec un rescheduleCallId.

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, ou false si ce n'est pas le cas.

Exemple d'utilisation

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

Discussions

Nom	Description
createChat	Crée une discussion.
loadChat	Récupère le chat avec l'ID de chat donné.
loadOngoingChat	Tente de charger une discussion en cours.
resumeChat	Reprend une discussion ignorée avec l'ID de discussion donné.
finishChat	Définissez l'état du chat actuel sur "terminé".
destroyChat	Appelle finishChat et détruit le chat actuel
fetchMessages	Récupère les messages précédents. Renvoie [] en cas d'échec.
sendTextMessage	Envoie un message.
sendFileMessage	Envoie un message de fichier. Renvoie -1 en cas d'échec de l'importation.
sendPreviewMessage	Envoie un message d'aperçu.
getChatDeflection	Récupère la configuration de déviation du chat.
sendChatTranscripts	Envoie la transcription du chat aux adresses e-mail indiquées.
downloadChatTranscript	Télécharge la transcription du chat.
getPdfStatus	Récupère l'état du PDF d'une transcription.
getChatSurvey	Récupère les questions de l'enquête par chat.
sendChatSurvey	Envoyer les commentaires des utilisateurs issus de l'enquête.
sendChatRate	Envoyer des commentaires d'utilisateurs sur le chat.
escalateChat	Transfère un chat d'un agent virtuel à un agent humain.
trackChatEscalation	Effectue le suivi de l'événement d'escalade de chat.
trackChatEndUserEvent	Effectue le suivi d'un événement d'utilisateur final.
getChatHistory	Récupère l'historique d'un chat donné.

Point de contact par chat

La fonctionnalité d'enregistrement demande à un client de confirmer qu'il est prêt avant de le mettre en relation avec un agent. Cette section décrit les méthodes du SDK Web sans interface graphique permettant de mettre en œuvre cette expérience. Pour savoir ce qu'est l'enregistrement, comment l'activer et le configurer (temps d'attente, délai avant expiration, position dans la file d'attente, comportement de réintégration) et comment créer des rapports, consultez Enregistrement pour le chat.

Nom	Description
checkIn	Envoie un signal au serveur pour confirmer la présence de l'utilisateur dans la file d'attente.
exitCheckIn	Supprime l'utilisateur de la file d'attente d'enregistrement.
notifyCheckInState	Informe le backend de l'état de visibilité de la fenêtre modale d'enregistrement.
rejoinChat	Replace l'utilisateur dans la file d'attente s'il ne confirme pas l'enregistrement.
trackCheckInEvent	Signale au backend quand des événements d'enregistrement ont été déclenchés par l'UI.

checkIn

Envoie un signal de confirmation au serveur indiquant que le client est présent et prêt à être mis en relation avec un agent pendant la période d'enregistrement. Met à jour le check_in_status du chat localement après que le serveur a confirmé la réception. Utilisez-le en réponse à l'événement chat.checkInRequested.

Signature de la méthode

checkIn(): Promise<CheckInResponse>

Valeur renvoyée

Renvoie un objet CheckInResponse.

Interfaces

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

Exemple d'utilisation

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

exitCheckIn

Indique au serveur que le client a choisi de quitter la file d'attente d'enregistrement. Met à jour check_in_status localement. Après avoir appelé cette méthode, le client ne recevra pas de connexion d'agent pour le cycle d'enregistrement en cours.

Signature de la méthode

exitCheckIn(): Promise<CheckInResponse>

Valeur renvoyée

Renvoie un objet CheckInResponse.

Interfaces

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

Exemple d'utilisation

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

notifyCheckInState

Informe le serveur de l'état de visibilité actuel de la fenêtre modale d'enregistrement (si le widget est réduit ou si l'onglet du navigateur est inactif). Le serveur l'utilise pour prendre des décisions concernant le moment de l'enregistrement. Doit être appelée chaque fois que la visibilité du widget ou le focus de l'onglet change alors que l'événement chat.checkInRequested est actif.

Signature de la méthode

notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>

Interfaces

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

Exemple d'utilisation

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

rejoinChat

Remet le client dans la file d'attente s'il n'a pas confirmé son enregistrement dans le délai imparti. Met à jour check_in_status localement. Utilisez-le en réponse à l'événement chat.checkInTimedOut si le client souhaite toujours se connecter.

Signature de la méthode

rejoinChat(): Promise<CheckInResponse>

Valeur de retour : renvoie un objet CheckInResponse.

Interfaces

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

Exemple d'utilisation

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

trackCheckInEvent

Indique au serveur que la fenêtre modale d'enregistrement a été présentée au client. Appelez cette méthode une fois, immédiatement après avoir présenté l'interface utilisateur d'enregistrement en réponse à chat.checkInRequested. Le serveur l'utilise pour l'analyse opérationnelle des taux de présentation des enregistrements. L'appel est attendu en interne et renvoie un Promise<void> qui peut être rejeté. Encapsulez-le donc dans try/catch (comme dans l'exemple suivant).

Signature de la méthode

trackCheckInEvent(): Promise<void>

Exemple d'utilisation

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

getMessageAttachment

Récupère une pièce jointe éligible associée à un message de chat spécifique. Ne récupère que si le message a été envoyé par un utilisateur non final ($userType !== 'end_user') et qu'il s'agit d'un type de pièce jointe compatible (photo, vidéo, audio, document). Renvoie null pour tout message qui ne remplit pas les deux conditions, et pas seulement pour les messages sans media_id. Enregistre le fichier récupéré dans le cache multimédia local du chat après la récupération.

Signature de la méthode

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

Valeur renvoyée

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

Exemple d'utilisation

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

createChat

Crée une session de chat pour le menu donné. Vous pouvez éventuellement spécifier la langue, un message d'accueil, un ID de déclencheur, un ID de ticket et des données personnalisées à envoyer avec le chat.

Après l'appel d'API initial, la méthode interroge le serveur jusqu'à ce qu'un provider_channel_id soit disponible, ou que la discussion soit annulée ou terminée. Si un canal de fournisseur devient disponible, la méthode lance la connexion au fournisseur en temps réel. La connexion peut encore être en cours d'établissement lorsque la promesse est résolue. Écoutez l'événement chat.connectedMessages pour savoir quand la connexion et la récupération initiale des messages sont terminées.

Signature de la méthode

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

Valeur renvoyée

Renvoie une instance Chat.

Avertissement : Cette méthode génère immédiatement une exception si une discussion est déjà en cours. Vérifiez si une session existe déjà avant d'appeler.

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

loadChat

Récupère une session de chat existante à l'aide de son ID.

Si le chat chargé n'est plus en cours, la méthode efface l'ID de chat stocké et le nonce de co-navigation de l'espace de stockage local. Il effectue également cette opération en cas d'erreur, de sorte que les appelants n'ont pas besoin de gérer manuellement le nettoyage de l'espace de stockage après un échec de chargement.

Signature de la méthode

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

Valeur renvoyée

Renvoie une instance Chat.

Avertissement : En cas d'erreur, cette méthode efface les ID de session de chat et de co-navigation stockés dans l'espace de stockage local avant de les relancer. Toute référence de session stockée est invalidée après un échec d'appel.

Exemple d'utilisation

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

loadOngoingChat

Tente de charger la session de chat en cours, le cas échéant. Renvoie null si aucune discussion en cours n'est trouvée.

Signature de la méthode

loadOngoingChat(): Promise<Chat | null>

Valeur renvoyée

Renvoie une instance Chat si elle est trouvée, ou une valeur nulle si aucune discussion n'est en cours. Les valeurs de stockage seront effacées si la discussion n'est pas en cours.

Avertissement : En cas d'erreur, cette méthode efface l'ID de chat stocké dans l'espace de stockage local avant de relancer l'opération. Toute référence de session stockée est invalidée après un échec d'appel.

Exemple d'utilisation

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

resumeChat

Reprend une session de chat précédemment fermée à l'aide de son ID, ce qui permet au client de poursuivre la conversation.

Si le client contient déjà une référence à une discussion avec le même ID, la méthode court-circuite : elle corrige l'état sur queued sur l'instance existante au lieu d'en récupérer une nouvelle. Si les ID ne correspondent pas, une nouvelle instance Chat est créée et enregistrée.

Signature de la méthode

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

Valeur renvoyée

Renvoie une instance Chat.

Exemple d'utilisation

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

finishChat

Définit l'état de la session de chat actuelle sur "terminée". Cela met fin au chat du côté du client.

Si le chat est à la fois connecté au fournisseur en temps réel et à l'état "terminé" après l'appel PATCH, la méthode se déconnecte également du fournisseur. Les appelants n'ont pas besoin d'appeler destroyChat si l'objectif est simplement de mettre fin au chat de manière appropriée.

Signature de la méthode

finishChat(): Promise<void>

Exemple d'utilisation

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

destroyChat

Termine et détruit la session de chat actuelle, en nettoyant tout l'état interne. Cette méthode appelle finishChat en interne, puis supprime l'instance de chat. Avant de terminer la discussion, la méthode la désactive (supprime les événements entrants en temps réel) pour éviter de traiter les messages pendant la suppression. Efface l'ID du traceur interne une fois le chat détruit.

Signature de la méthode

destroyChat(): Promise<void>

Exemple d'utilisation

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

fetchMessages

Récupère l'historique des messages de la session de chat actuelle auprès du fournisseur en temps réel. Doit être appelée une fois que le chat est connecté. Si elle est appelée avant que le chat ne se connecte, elle renvoie un tableau vide au lieu de générer une exception. Récupère automatiquement les URL des documents pour tous les messages de type document et les fusionne dans la réponse. Pour les messages de type server_message, récupère le contenu du message de l'agent virtuel de la tâche et le met en forme de manière intégrée. Renvoie un tableau vide en cas d'échec au lieu de générer une erreur.

Signature de la méthode

fetchMessages(): Promise<MessageResponse[]>

Valeur renvoyée

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

Avertissement : Cette méthode ne génère pas d'erreur en cas d'échec. Renvoie un tableau vide ([]) si la récupération du message échoue. Ne vous fiez pas à try/catch. Vérifiez plutôt la valeur renvoyée.

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

Exemple d'utilisation

const messages = await client.fetchMessages()

sendTextMessage

Envoie un message dans la session de chat actuelle.

La méthode nettoie le contenu brut avant de l'envoyer et renvoie un résultat anticipé (sans opération) si le résultat est vide. Si le chat se trouve dans un flux d'agent virtuel de tâche (inTask), le message est acheminé via le point de terminaison de l'agent virtuel de tâche au lieu du canal standard. Si la suppression côté serveur est activée, le message est envoyé à l'aide d'un point de terminaison de serveur plutôt que directement par le biais du fournisseur en temps réel.

Signature de la méthode

sendTextMessage(rawContent: string): Promise<void>

Exemple d'utilisation

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

sendFileMessage

Importe un fichier dans la session de chat actuelle via un processus en trois étapes : obtention d'une URL Cloud Storage présignée auprès du serveur, importation du fichier directement vers cette URL, puis confirmation de l'importation auprès du serveur. La route d'importation est déterminée automatiquement à partir du type MIME du fichier : les images sont envoyées en tant que messages photo et les vidéos en tant que messages vidéo. Les autres types de fichiers sont acheminés en fonction de leur type MIME. Renvoie l'ID du message en cas de réussite, ou -1 en cas d'échec.

Signature de la méthode

sendFileMessage(file: File): Promise<number>

Valeur renvoyée

Renvoie l'ID du message ou -1 si l'importation a échoué. Toutefois, l'envoi de message suivant peut toujours être rejeté (par exemple, ChatEndedError). Par conséquent, encapsulez l'appel dans try/catch en plus de vérifier -1.

Exemple d'utilisation

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

Envoie un message d'aperçu dans la session de chat actuelle. Les messages d'aperçu sont généralement utilisés pour montrer à l'agent ce que le client est en train de saisir avant l'envoi du message. Si redaction_enabled et agent_incoming_ha_enabled sont tous deux définis sur "true" dans l'état du chat, l'aperçu est envoyé via un point de terminaison de serveur (POST /chats/{id}/redact_messages) plutôt que via le canal du fournisseur en temps réel.

Signature de la méthode

sendPreviewMessage(content: string): Promise<void>

Exemple d'utilisation

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

getChatDeflection

Récupère la configuration de déviation de chat pour la session de chat actuelle, y compris si la déviation est activée, le seuil de temps d'attente et les options de déviation disponibles.

Renvoie null si la déviation n'est pas activée pour le chat (le champ enabled de la réponse du serveur est faux). Les appelants doivent effectuer une vérification de valeur nulle avant de lire la réponse.

Signature de la méthode

getChatDeflection(): Promise<ChatDeflectionResponse | null>

Valeur renvoyée

Renvoie un objet ChatDeflectionResponse ou null si la déviation n'est pas activée pour le chat.

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

Envoie la transcription du chat actuel aux adresses e-mail spécifiées.

Signature de la méthode

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

Exemple d'utilisation

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

downloadChatTranscript

Lance le téléchargement de la transcription de la discussion en cours au format PDF. Renvoie un objet de transcription qui peut être utilisé avec getPdfStatus pour suivre la progression de la génération.

Signature de la méthode

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Valeur renvoyée

Renvoie l'objet de transcription.

Interfaces

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

Exemple d'utilisation

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

getPdfStatus

Vérifie l'état de génération d'un PDF de transcription de chat précédemment demandé. Utilisez l'objet chat_transcript_id renvoyé par downloadChatTranscript pour interroger l'état d'avancement.

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 = response.headers['x-transcript-status'];
// otherwise use status on data
const data = response.data
console.log(data.status)

getChatSurvey

Récupère les questions de l'enquête post-chat configurées pour la session de chat actuelle. L'enquête est présentée aux clients à la fin d'un chat.

Signature de la méthode

getChatSurvey(): Promise<ChatSurveyResponse | null>

Valeur renvoyée

Renvoie un objet ChatSurveyResponse ou une valeur nulle.

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

sendChatSurvey

Envoie les réponses du client à l'enquête post-chat. Chaque réponse est associée à l'ID de la question.

Signature de la méthode

sendChatSurvey(answers: SurveyAnswers): Promise<void>

Avertissement : Cette méthode génère immédiatement une exception si le type de feedback du chat n'est pas 'survey'. Les appelants doivent vérifier chat.feedbackType === 'survey' avant d'appeler ou de gérer l'erreur.

Interfaces

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

Exemple d'utilisation

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

sendChatRate

Envoie la note et les commentaires facultatifs du client pour la session de chat. Utilisé lorsque le type de commentaires post-chat est une note plutôt qu'une enquête complète.

Signature de la méthode

sendChatRate(data: RateRequest): Promise<void>

Avertissement : Cette méthode génère immédiatement une exception si le type de feedback du chat n'est pas 'rate'. Les appelants doivent vérifier chat.feedbackType === 'rate' avant d'appeler ou de gérer l'erreur.

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

Transfère le chat en cours d'un agent virtuel à un agent humain.

Signature de la méthode

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

Interfaces

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

Exemple d'utilisation

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

Effectue le suivi d'un événement d'escalade de chat, en enregistrant l'ID d'escalade et le canal vers lequel il a été escaladé.

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

Effectue le suivi d'un événement d'utilisateur final personnalisé pendant la session de chat, qui peut être utilisé pour l'analyse ou pour déclencher des workflows de backend. Si l'objet data n'inclut pas end_user_name et qu'un nom est disponible dans le profil utilisateur authentifié, il est renseigné automatiquement avant l'envoi de la requête.

Signature de la méthode

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Valeur renvoyée

Renvoie void.

Interfaces

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

Exemple d'utilisation

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

Récupère l'historique des discussions du client, y compris le contenu des messages et les métadonnées. Les résultats sont paginés. La page 1 renvoie jusqu'à deux chats, et les pages suivantes renvoient un chat chacune. Cette pagination asymétrique est intentionnelle et permet au premier appel de précharger le contexte de l'historique adjacent.

Signature de la méthode

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

Valeur renvoyée

Renvoie un objet ChatHistoryResponse ou null.

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 = await client.getChatHistory(1) // page defaults to 1 if omitted
 console.log(data)
} catch (error) {
 console.log(error)
}

E-mails

Nom	Description
createEmail	Envoyer un e-mail au canal de messagerie d'un ID de menu donné.
getProhibitedFileTypes	Obtenez les types de fichiers interdits pour les pièces jointes d'e-mails.

createEmail

Envoie un e-mail au canal de messagerie associé au menu donné. Le consommateur peut inclure un nom, une adresse e-mail, un corps du message et des pièces jointes facultatives.

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

Récupère la liste des types de fichiers qui ne sont pas autorisés en tant que pièces jointes d'e-mails, telle que configurée par l'administrateur.

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

Nom	Description
createCobrowseCode	Génère un code de co-navigation.
startCobrowse	Demandez une session de co-navigation.
restoreCobrowseSession	Restaure une session de co-navigation après la réouverture de la fenêtre du navigateur.

createCobrowseCode

Génère un code de session de co-navigation (partage d'écran) unique qui peut être partagé avec un agent pour lancer une session. Initialise le client de co-navigation s'il ne l'a pas encore été. Réutilise tout nonce existant du stockage plutôt que d'en générer un nouveau à chaque appel, de sorte que le même code de session puisse être récupéré lors des chargements de page.

Signature de la méthode

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

Valeur renvoyée

Renvoie une chaîne de code de co-navigation ou une chaîne vide ('') en cas d'échec.

Avertissement : Cette méthode ne génère pas d'erreur en cas d'échec. Ne vous fiez pas à try/catch. Vérifiez plutôt la valeur renvoyée.

Exemple d'utilisation

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

startCobrowse

Demande le démarrage d'une session de co-navigation (partage d'écran) du côté de l'utilisateur final pendant une discussion active.

Signature de la méthode

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

Avertissement : Cette méthode génère une exception si la discussion actuelle n'a pas été créée avec cobrowsable: true. Les appelants peuvent vérifier chat.cobrowsable avant d'appeler pour éviter l'exception.

Exemple d'utilisation

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

restoreCobrowseSession

Tente de restaurer une session de co-navigation précédemment active après la réouverture de la fenêtre du navigateur ou l'actualisation 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 la co-navigation n'est pas activée dans les options du client ou si aucune session de co-navigation précédente n'existe dans l'espace de stockage.

Avertissement : Cette méthode ne génère pas d'erreur. Si une erreur se produit lors de la restauration, la méthode consigne l'erreur en interne, efface la session de co-navigation stockée, puis renvoie un résultat propre. Les appelants n'ont pas besoin de try/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()

Agent virtuel post-session

Nom	Description
updatePostSession	Définissez l'état de la session de chat en cours après la session.

updatePostSession

Cette méthode permet de mettre à jour l'état de l'agent virtuel après la session pour le chat en cours.

• Met à jour l'état de l'agent virtuel après la session pour le chat en cours. Utilisez-le pour signaler l'état de préparation, la progression ou l'achèvement d'un flux d'agent virtuel post-session.

• Renvoie immédiatement une opération sans effet si postSessionStatus est FINISHED ou WAITING (ces transitions sont gérées en interne).

• Il dispose d'une logique de nouvelle tentative interne spécifiquement pour l'état IN_PROGRESS d'une réponse 400. Les appelants n'ont donc pas besoin d'implémenter leur propre logique de nouvelle tentative dans 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 : indique si l'activation est activée.

• post_session_transfer_status : l'une des énumérations PostSessionStatus.

Débogage

Nom	Description
getLogs	Récupère les journaux de débogage internes du SDK.
printLogs	Envoie des journaux de débogage internes vers la console du navigateur.

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. 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 : Les journaux de pont sont d'abord récupérés en interne, car la récupération elle-même produit une entrée de journal racine. Par conséquent, rootLogs capture intentionnellement ce journal final.

Précision

Chaque entrée LogHistoryData capture un seul événement de journal :

• date : code temporel ISO 8601 de l'événement.

• channel : module du SDK qui l'a émis (par exemple, client de premier niveau, couche de chat, couche de co-navigation, fournisseur en temps réel).

• level : niveau de gravité du journal (debug, info, warn ou error).

• args : arguments bruts capturés par l'appel de journal.

Exemple d'entrée :

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

L'ensemble exact des canaux et du contenu des messages peut évoluer entre les versions du SDK. Traitez les journaux comme une aide au débogage, et non comme une cible d'analyse stable. Ne créez pas de logique de production qui dépend de noms de canaux ou de chaînes de message spécifiques.

Champ d'application et recommandations d'utilisation

getLogs renvoie des enregistrements internes au SDK destinés à aider à diagnostiquer les problèmes d'intégration avec le SDK Web headless lui-même. Son principal cas d'utilisation est le diagnostic d'assistance : lorsqu'un utilisateur final signale un problème, votre application peut capturer le résultat de getLogs et l'associer à la demande d'assistance envoyée à CCAI Platform.

Les journaux renvoyés n'incluent pas :

• La télémétrie de l'application, les événements d'entreprise ou la navigation des utilisateurs de votre page hôte.

• Défaillances du réseau que le navigateur ne transmet pas au SDK (par exemple, erreurs CORS, de contenu mixte ou de certificat).

• Traces de requêtes côté serveur ou détails du backend au-delà de l'état HTTP renvoyé au SDK.

getLogs ne remplace pas vos propres outils d'observabilité. Nous vous recommandons d'associer le SDK aux éléments suivants :

• Un outil de suivi des erreurs/RUM côté navigateur (Sentry, Datadog Browser RUM, New Relic Browser ou équivalent).

• La journalisation côté serveur sur votre point de terminaison d'authentification (le rappel authenticate que le SDK appelle).

• Écouteurs au niveau de l'application sur chat.disconnected, chat.timeout et chat.ended si vous devez transférer les signaux du cycle de vie du chat vers votre propre pipeline de télémétrie.

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

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

Signature de la méthode

printLogs(): Promise<void>

Exemple d'utilisation

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

Autres

Nom	Description
runTrigger	Vérifie si des déclencheurs proactifs doivent être activés.
getAfterHourMessage	Obtenez le message pour la déviation en dehors des heures de travail.

runTrigger

Effectue une itération sur les déclencheurs proactifs configurés et appelle le rappel fourni pour tous ceux dont les conditions sont remplies (mots clés d'URL, nombre de visites de la page, durée de séjour, type de visiteur).

Signature de la méthode

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

Interfaces

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

Exemple d'utilisation

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

getAfterHourMessage

Renvoie le message de redirection configuré à afficher lorsque le canal demandé est en dehors des horaires d'ouverture.

Signature de la méthode

La signature de la méthode est la suivante :

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
}