Κέντρο βοήθειας
Chat API

Chat API

Τελευταία ενημέρωση:

Επισκόπηση του Chat API

Το API του widget σάς επιτρέπει να ελέγχετε το widget συνομιλίας μέσω κώδικα και να δηλώνετε callbacks για συμβάντα συνομιλίας.

Αναζητάτε το REST API; Αυτό το άρθρο καλύπτει το JavaScript widget API στο πρόγραμμα περιήγησης (window.aichatbotApi) για σελίδες όπου είναι ενσωματωμένο το widget του ChatLab. Για το server-to-server REST API που χρησιμοποιείται για συνομιλία με bots από το backend σας ή για τη διαχείριση bots μέσω κώδικα, δείτε τα άρθρα Bot Talk API και Management API.

Ξεκινώντας

Το API του chatbot δεν είναι άμεσα διαθέσιμο μόλις φορτωθεί η σελίδα σας - το script πρέπει πρώτα να φορτωθεί και να αρχικοποιηθεί. Πρέπει να χρησιμοποιήσετε το window.aichatbotCallback.onSessionActivated ως τον μηχανισμό εκκίνησης (bootstrap) για ασφαλή πρόσβαση στο API.

Χρησιμοποιήστε το δημόσιο κλειδί widget από την ενότητα Deploy (Δημοσίευση) ως YOUR_API_KEY, ποτέ ένα μυστικό κλειδί ck_ ή mk_. Διατηρήστε το αναγνωριστικό παρόχου (provider ID) και τον host του script από το δικό σας απόσπασμα Deploy. Τοποθετήστε τη ρύθμιση του callback πριν από τη συγκεκριμένη ετικέτα 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 ενεργοποιείται όταν μια συνεδρία γίνεται διαθέσιμη, συμπεριλαμβανομένων των συνεδριών που έχουν ανακτηθεί. Ανάλογα με τις ρυθμίσεις δημοσίευσης και της οθόνης υποδοχής, αυτό δεν είναι απαραίτητα το πρώτο κλικ ανοίγματος του widget. Μπορεί να ενεργοποιηθεί ξανά. Καταχωρίστε τα callbacks μία φορά ανά αντικείμενο API για να αποφύγετε διπλότυπους handlers. Μέσα σε αυτό, είναι εγγυημένο ότι το αντικείμενο API υπάρχει και η συνεδρία είναι ενεργή, επομένως μπορείτε να καλείτε με ασφάλεια τις συναρτήσεις sendMessage(), updateClientContext(), καθώς και να καταχωρίζετε callbacks συμβάντων.

Σημαντικό: Μην καλείτε το window.aichatbotApi.getChatbotApi() απευθείας στο script της σελίδας σας χωρίς αναμονή - το αντικείμενο API δεν υπάρχει μέχρι να φορτωθεί και να αρχικοποιηθεί το script του ChatLab.

Συμβουλή: Εάν χρειάζεται μόνο να ελέγξετε το widget (εμφάνιση/απόκρυψη/εναλλαγή) και δεν χρειάζεστε ενεργή συνεδρία, ακούστε εναλλακτικά το DOM συμβάν aichatbotReady:

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

Μέθοδοι

Μέθοδος Περιγραφή
showChat() Άνοιγμα του widget συνομιλίας
hideChat() Κλείσιμο του widget συνομιλίας
toggleChat() Εναλλαγή ορατότητας του widget
sendMessage(text) Αποστολή μηνύματος μέσω κώδικα
updateClientContext(data) Ενημέρωση περιβάλλοντος χρήστη (δείτε παρακάτω)
setLanguage(code) Αλλαγή του widget σε μια γλώσσα (μόνο για πολύγλωσσα bots, δείτε παρακάτω)
getLanguage() Επιστροφή της γλώσσας που χρησιμοποιεί αυτή τη στιγμή το widget
getAvailableLanguages() Επιστροφή της λίστας των γλωσσών που προσφέρει το bot
addCallback(name, fn) Δήλωση ενός event callback

Σημείωση: Οι συναρτήσεις sendMessage και updateClientContext απαιτούν ενεργή συνεδρία. Χρησιμοποιήστε το μοτίβο αρχικοποίησης onSessionActivated που παρουσιάζεται στην ενότητα «Ξεκινώντας».

Callbacks

Δηλώστε callbacks συμβάντων μέσα στον handler onSessionActivated (δείτε την ενότητα «Ξεκινώντας»):

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

Callback Δεδομένα Περιγραφή
onSessionActivated - Η συνεδρία συνομιλίας είναι έτοιμη
onUserMessage string Ο χρήστης έστειλε ένα μήνυμα
onChatbotMessage string Το bot απάντησε με ένα μήνυμα
onProductClick Payload προϊόντος/συνδέσμου από την κάρτα Ο χρήστης έκανε κλικ σε έναν σύνδεσμο προϊόντος. Ελέγξτε το payload για τον τύπο της κάρτας σας
onLeadCollectionFormSubmit {email, phone, name} Υποβλήθηκε η φόρμα συλλογής lead
onContactFormSubmit {email, message} Υποβλήθηκε η φόρμα επικοινωνίας/υποστήριξης
onLiveChatFormSubmit {name, email} Υποβλήθηκε η φόρμα Live Chat, δεν αποτελεί απόδειξη ότι συνδέθηκε εκπρόσωπος
onCustomFormSubmit {formId, values} Υποβλήθηκε προσαρμοσμένη φόρμα. Τα δεδομένα μεταφορτωμένων αρχείων δεν περιλαμβάνονται σε αυτό το callback

Τα callbacks φορμών αναφέρουν υποβολή από την πλευρά του προγράμματος περιήγησης και όχι επιβεβαιωμένη αποθήκευση ή επιτυχή παράδοση. Για επεξεργασία επιβεβαιωμένη από το backend, χρησιμοποιήστε Webhooks. Τα payloads των callbacks ενδέχεται να περιέχουν προσωπικά δεδομένα. Μην τα προωθείτε μαζικά σε εργαλεία αναλυτικών στοιχείων ή δημόσια αρχεία καταγραφής (logs).

Παλαιού τύπου Event Callbacks

Το αντικείμενο window.aichatbotCallback υποστηρίζει επίσης τα onUserMessage και onChatbotMessage ως άμεσες ιδιότητες. Χρησιμοποιήστε το addCallback() για αρθρωτούς listeners χωρίς αντικατάσταση του καθολικού αντικειμένου:

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

Σημείωση: Το window.aichatbotCallback.onSessionActivated δεν έχει καταργηθεί - αποτελεί τον συνιστώμενο μηχανισμό εκκίνησης (bootstrap) για την αρχικοποίηση του Chat API (δείτε την ενότητα «Ξεκινώντας»).

Ενσωμάτωση με Iframe

Όταν χρησιμοποιείτε ενσωμάτωση με iframe, χρησιμοποιήστε το postMessage για να επικοινωνήσετε με το chatbot:

Αποστολή εντολών

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

Λήψη Callbacks

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

Ενημέρωση περιβάλλοντος πελάτη (Update Client Context)

Η συνάρτηση updateClientContext επιτρέπει την ενημέρωση του περιβάλλοντος του πελάτη κατά τη διάρκεια μιας ενεργής συνεδρίας:

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

Παράμετροι:

  • clientId (υποχρεωτικό): Μοναδικό αναγνωριστικό για τον πελάτη
  • clientName, clientEmail, clientPhone (προαιρετικά): Στοιχεία πελάτη που εμφανίζονται στις συνομιλίες
  • clientSecurityToken (προαιρετικό): Ένα διακριτικό (token) που προωθείται ως περιβάλλον για την προσαρμοσμένη ενσωμάτωσή σας. Το δικό σας API πρέπει να επικυρώνει τη γνησιότητα, τη λήξη και την εξουσιοδότησή του.
  • clientHostContext (προαιρετικό): Πρόσθετες παράμετροι περιβάλλοντος προσβάσιμες σε προσαρμοσμένες ενέργειες API

Τα αναγνωριστικά και το περιβάλλον που παρέχονται από το πρόγραμμα περιήγησης δεν αποτελούν απόδειξη ταυτότητας. Μην τοποθετείτε μυστικά κλειδιά λογαριασμού στον κώδικα JavaScript της σελίδας και μην παραχωρείτε πρόσβαση αποκλειστικά επειδή ένα παρεχόμενο clientId ή email ταιριάζει με μια εγγραφή.

Χρήση σε κλήσεις API:

Τα χαρακτηριστικά περιβάλλοντος μπορούν να χρησιμοποιηθούν σε κλήσεις συναρτήσεων API ρυθμίζοντας την παράμετρο του API ως τύπο «Context»:

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Προσαρμοσμένες παράμετροι περιβάλλοντος κεντρικού υπολογιστή με πρόθεμα client, π.χ. clientparam1, clientparam2

Γλώσσα

Αυτές οι μέθοδοι λειτουργούν μόνο σε πολύγλωσσα chatbots. Σε ένα μονόγλωσσο bot, το widget δεν διαθέτει επίπεδο γλώσσας προς εναλλαγή, επομένως το setLanguage() δεν κάνει τίποτα και το getAvailableLanguages() επιστρέφει μόνο τη βασική γλώσσα του bot. Ενεργοποιήστε πρώτα την υποστήριξη πολλών γλωσσών στο Settings > Languages (Ρυθμίσεις > Γλώσσες) - δείτε το άρθρο Πολύγλωσσα chatbots.

Χρησιμοποιήστε το setLanguage() όταν η σελίδα σας υπάρχει σε πολλές γλώσσες και θέλετε η συνομιλία να ανοίγει στη γλώσσα που διαβάζει ο επισκέπτης, αντί για εκείνη στην οποία τυχαίνει να είναι ρυθμισμένο το πρόγραμμα περιήγησής του:

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", ...]
});

Μπορείτε επίσης να δηλώσετε τη γλώσσα της σελίδας πριν φορτωθεί το script, αποτρέποντας έτσι μια σύντομη εμφάνιση λανθασμένης γλώσσας:

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

Ποια γλώσσα υπερισχύει. Το widget επιλέγει τη γλώσσα με την ακόλουθη σειρά προτεραιότητας:

  1. Μια γλώσσα που επέλεξε ο ίδιος ο επισκέπτης στο μενού γλωσσών του widget.
  2. Η γλώσσα της σελίδας, από το setLanguage() ή το window.aichatbotLanguage.
  3. Η γλώσσα του προγράμματος περιήγησης του επισκέπτη.
  4. Η βασική γλώσσα του chatbot.

Η επιλογή του ίδιου του επισκέπτη απομνημονεύεται για επόμενες επισκέψεις, αλλά παύει να ισχύει μόλις αλλάξει η γλώσσα της σελίδας - επομένως ο επιλογέας γλώσσας του ιστότοπού σας υπερισχύει πάντα μιας παλαιότερης επιλογής. Οι κωδικοί ακολουθούν το πρότυπο ISO 639-1 (en, de, pl). Ένας περιφερειακός κωδικός όπως το de-AT μεταπίπτει στο de. Μια γλώσσα που δεν προσφέρει το bot αγνοείται.

Η αλλαγή της γλώσσας δεν τερματίζει τη συνομιλία ούτε διαγράφει το ιστορικό της.

Σχετικά άρθρα

Αναζήτηση σε όλα τα άρθραΡωτήστε τον ψηφιακό βοηθό