Comment accéder à l'API Chat de ChatLab ?

Définissez window.aichatbotCallback.onSessionActivated avant le chargement de la balise script. À l'intérieur de ce rappel, utilisez window.aichatbotApi.getChatbotApi(apiKey) pour obtenir l'objet API et enregistrer des écouteurs d'événements.

Quels sont les rappels (callbacks) disponibles dans la Chat API ?

Les rappels disponibles incluent onSessionActivated, onUserMessage, onChatbotMessage, onProductClick, onLeadCollectionFormSubmit, onContactFormSubmit et onLiveChatFormSubmit.

Comment utiliser la Chat API avec un déploiement en iframe ?

Utilisez postMessage pour envoyer des commandes à l'iframe et addEventListener('message') pour recevoir des rappels. Les commandes incluent showChat, hideChat, sendMessage et updateClientContext.

Puis-je changer la langue du widget de chat depuis ma page ?

Oui, sur les chatbots multilingues. Appelez setLanguage('de') sur l'objet API, ou définissez window.aichatbotLanguage avant le chargement du script. Sur les bots unilingues, la méthode n'a aucun effet.

À quoi sert updateClientContext ?

updateClientContext vous permet de transmettre des informations sur l'utilisateur (identifiant, nom, e-mail, téléphone) et des paramètres personnalisés au chatbot pendant une session active, qui peuvent ensuite être utilisés dans les appels de fonction API.

Chat API - ChatLab Centre d'aide

Aperçu de l'API Chat

L'API du widget vous permet de contrôler le widget de chat par programmation et d'enregistrer des rappels pour les événements de chat.

Vous recherchez l'API REST ? Cet article traite de l'API JavaScript du widget dans le navigateur (window.aichatbotApi) pour les pages où le widget ChatLab est intégré. Pour l'API REST de serveur à serveur utilisée pour converser avec des bots depuis votre backend ou gérer des bots par programmation, consultez les articles sur la Bot Talk API et la Management API.

Pour commencer

L'API du chatbot n'est pas disponible immédiatement au chargement de votre page - le script doit d'abord se charger et s'initialiser. Vous devez utiliser window.aichatbotCallback.onSessionActivated comme mécanisme d'amorçage pour accéder à l'API en toute sécurité.

Utilisez la clé publique du widget issue de Deploy (Déployer) comme YOUR_API_KEY, jamais une clé secrète ck_ ou mk_. Conservez l'identifiant du fournisseur et l'hôte du script de votre propre extrait Deploy. Placez la configuration du callback avant cette balise script :

<script>
let registeredChatbot;
window.aichatbotCallback = {
    onSessionActivated() {
        var chatbot = window.aichatbotApi.getChatbotApi('YOUR_API_KEY');

        if (registeredChatbot === chatbot) return;
        registeredChatbot = chatbot;

        chatbot.addCallback('onUserMessage', function(message) {
            console.log('User said:', message);
        });

        chatbot.addCallback('onChatbotMessage', function(message) {
            console.log('Bot replied:', message);
        });

        // Send only when your application intends to start a real chat:
        // chatbot.sendMessage('Hello from the API!');
    }
};
</script>
<script>window.aichatbotApiKey="YOUR_API_KEY";</script>
<script src="https://script.chatlab.com/aichatbot.js" defer></script>

onSessionActivated se déclenche lorsqu'une session devient disponible, y compris les sessions restaurées. Selon les paramètres de déploiement et de l'écran d'accueil, ce n'est pas nécessairement lors du premier clic d'ouverture du widget. Cet événement peut se déclencher à nouveau ; enregistrez les callbacks une seule fois par objet d'API pour éviter les gestionnaires en double. À l'intérieur, l'existence de l'objet d'API est garantie et la session est active, vous pouvez donc appeler sendMessage(), updateClientContext() et enregistrer des callbacks d'événements en toute sécurité.

Important : N'appelez pas directement window.aichatbotApi.getChatbotApi() dans le script de votre page sans attendre - l'objet d'API n'existe pas tant que le script ChatLab n'est pas chargé et initialisé.

Conseil : Si vous avez uniquement besoin de contrôler le widget (afficher/masquer/basculer) sans nécessiter de session active, écoutez plutôt l'événement DOM aichatbotReady :

window.addEventListener('aichatbotReady', function(e) {
    var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);
    chatbot.showChat();
});

Méthodes

Méthode	Description
`showChat()`	Ouvrir le widget de chat
`hideChat()`	Fermer le widget de chat
`toggleChat()`	Basculer la visibilité du widget
`sendMessage(text)`	Envoyer un message par programmation
`updateClientContext(data)`	Mettre à jour le contexte utilisateur (voir ci-dessous)
`setLanguage(code)`	Basculer le widget vers une langue (bots multilingues uniquement, voir ci-dessous)
`getLanguage()`	Renvoyer la langue actuellement utilisée par le widget
`getAvailableLanguages()`	Renvoyer la liste des langues proposées par le bot
`addCallback(name, fn)`	Enregistrer un callback d'événement

Remarque : sendMessage et updateClientContext nécessitent une session active. Utilisez le modèle d'initialisation onSessionActivated présenté dans la section Pour commencer.

Callbacks

Enregistrez les callbacks d'événements dans votre gestionnaire onSessionActivated (voir Pour commencer) :

chatbot.addCallback('onUserMessage', function(message) {
    console.log('User said:', message);
});

chatbot.addCallback('onChatbotMessage', function(message) {
    console.log('Bot replied:', message);
});

chatbot.addCallback('onProductClick', function(productIdOrLink) {
    console.log('Product clicked:', productIdOrLink);
});

chatbot.addCallback('onLeadCollectionFormSubmit', function(data) {
    console.log('Lead captured:', data.email);
});

chatbot.addCallback('onContactFormSubmit', function(data) {
    console.log('Support request from:', data.email);
});

chatbot.addCallback('onLiveChatFormSubmit', function(data) {
    console.log('Live chat started:', data.name);
});

Callbacks disponibles

Callback	Données	Description
`onSessionActivated`	-	La session de chat est prête
`onUserMessage`	`string`	L'utilisateur a envoyé un message
`onChatbotMessage`	`string`	Le bot a répondu avec un message
`onProductClick`	Charge utile de produit/lien provenant de la carte affichée	L'utilisateur a cliqué sur un lien de produit ; inspectez la charge utile pour votre type de carte
`onLeadCollectionFormSubmit`	`{email, phone, name}`	Le formulaire de capture de leads a été soumis
`onContactFormSubmit`	`{email, message}`	Le formulaire de contact/support a été soumis
`onLiveChatFormSubmit`	`{name, email}`	Le formulaire Live Chat a été soumis, sans certitude qu'un opérateur a rejoint la conversation
`onCustomFormSubmit`	`{formId, values}`	Le formulaire personnalisé a été soumis ; les données des fichiers importés ne sont pas incluses dans ce callback

Les callbacks de formulaires signalent une soumission côté navigateur, et non un enregistrement confirmé ni une remise réussie. Pour un traitement confirmé côté serveur, utilisez les webhooks. Les charges utiles de callback peuvent contenir des données personnelles ; ne les transférez pas intégralement vers vos outils d'analytique ou vos journaux publics.

Anciens callbacks d'événements

L'objet window.aichatbotCallback prend également en charge onUserMessage et onChatbotMessage en tant que propriétés directes. Utilisez addCallback() pour des écouteurs modulaires sans remplacer l'objet global :

window.aichatbotCallback = {
    onUserMessage(message) { ... },
    onChatbotMessage(message) { ... }
};

Remarque : window.aichatbotCallback.onSessionActivated n'est pas obsolète - c'est le mécanisme d'amorçage recommandé pour initialiser l'API Chat (voir Pour commencer).

Déploiement par iframe

Lorsque vous utilisez le déploiement par iframe, utilisez postMessage pour communiquer avec le chatbot :

Envoi de commandes

// Give the ChatLab iframe from Deploy this unique id.
const chatbotIframe = document.getElementById('chatlab-frame');
const chatbotOrigin = new URL(chatbotIframe.src, window.location.href).origin;
// Run show/hide/language commands after the iframe loads.
// Wait for onSessionActivated before sendMessage or updateClientContext.

// Show chat
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'showChat'
}, chatbotOrigin);

// Hide chat
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'hideChat'
}, chatbotOrigin);

// Send message
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'sendMessage',
    payload: 'Hello!'
}, chatbotOrigin);

// Update client context
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'updateClientContext',
    payload: { clientId: 'user123', clientName: 'John' }
}, chatbotOrigin);

// Switch language (multi-language bots only)
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'setLanguage',
    payload: 'de'
}, chatbotOrigin);

Réception de rappels

window.addEventListener('message', (event) => {
    if (event.origin !== chatbotOrigin || event.source !== chatbotIframe.contentWindow) return;
    if (event.data?.type !== 'aichatbot-callback') return;

    const { apiKey, callback, data } = event.data;

    switch (callback) {
        case 'onSessionActivated':
            console.log('Session ready');
            break;
        case 'onUserMessage':
            console.log('User said:', data);
            break;
        case 'onChatbotMessage':
            console.log('Bot replied:', data);
            break;
        case 'onProductClick':
            console.log('Product clicked:', data);
            break;
        case 'onLeadCollectionFormSubmit':
            console.log('Lead captured:', data);
            break;
        case 'onContactFormSubmit':
            console.log('Contact form:', data);
            break;
        case 'onLiveChatFormSubmit':
            console.log('Live chat started:', data);
            break;
    }
});

Mettre à jour le contexte client

La fonction updateClientContext permet de mettre à jour le contexte client au cours d'une session active :

chatbot.updateClientContext({
    clientId: "unique-client-identifier",     // Required
    clientName: "John",                       // Optional
    clientEmail: "john@doe.com",              // Optional
    clientPhone: "555-444-333",               // Optional
    clientSecurityToken: "your-token",        // Optional
    clientHostContext: {                      // Optional
        param1: "value1",
        param2: "value2"
    }
});

Paramètres :

clientId (obligatoire) : identifiant unique du client
clientName, clientEmail, clientPhone (facultatif) : coordonnées du client affichées dans les conversations
clientSecurityToken (facultatif) : token transmis comme contexte pour votre intégration personnalisée. Votre propre API doit valider son authenticité, son expiration et ses autorisations.
clientHostContext (facultatif) : paramètres de contexte supplémentaires accessibles dans les actions d'API personnalisées

Les identifiants et le contexte fournis par le navigateur ne constituent pas une preuve d'identité. Ne placez aucun secret d'accès à l'ensemble du compte dans le code JavaScript de la page, et n'accordez pas d'accès uniquement parce qu'un identifiant clientId ou un e-mail fourni correspond à un enregistrement.

Utilisation dans les appels d'API :

Les attributs de contexte peuvent être utilisés dans les appels de fonction d'API en configurant le type du paramètre d'API sur « Context » :

clientName, clientEmail, clientPhone, clientSecurityToken
Paramètres de contexte hôte personnalisés préfixés par client, par ex. clientparam1, clientparam2

Langue

Ces méthodes fonctionnent uniquement sur les chatbots multilingues. Sur un bot unilingue, le widget ne dispose d'aucune couche linguistique à changer, donc setLanguage() ne fait rien et getAvailableLanguages() renvoie simplement la langue propre au bot. Activez d'abord le support multilingue dans Settings > Languages (Paramètres > Langues) - voir Chatbots multilingues.

Utilisez setLanguage() lorsque votre page existe en plusieurs langues et que vous souhaitez que le chat s'ouvre dans celle que le visiteur est en train de lire, plutôt que dans celle configurée par défaut dans son navigateur :

window.addEventListener('aichatbotReady', function(e) {
    var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);

    chatbot.setLanguage(document.documentElement.lang);  // e.g. "de"

    console.log(chatbot.getLanguage());            // "de"
    console.log(chatbot.getAvailableLanguages());   // ["en", "de", "fr", ...]
});

Vous pouvez également déclarer la langue de la page avant le chargement du script, ce qui évite un bref clignotement de la mauvaise langue :

<script>window.aichatbotLanguage = "de";</script>

Quelle langue prévaut. Le widget détermine la langue dans l'ordre suivant :

Une langue que le visiteur a choisie lui-même dans le menu des langues du widget.
La langue de la page, définie par setLanguage() ou window.aichatbotLanguage.
La langue du navigateur du visiteur.
La langue de base du chatbot.

Le choix personnel du visiteur est mémorisé pour ses visites ultérieures, mais il cesse de s'appliquer dès que la langue de la page change - ainsi, votre sélecteur de langue prévaut toujours sur un ancien choix. Les codes respectent la norme ISO 639-1 (en, de, pl) ; un code régional tel que de-AT bascule sur de. Une langue non proposée par le bot est ignorée.

Changer de langue n'interrompt pas la conversation et n'efface pas l'historique des échanges.

Chat API