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

Chat API

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

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

Αυτή η λειτουργία είναι διαθέσιμη μόνο σε επιλεγμένα πλάνα. Σας επιτρέπει να ελέγχετε το widget συνομιλίας μέσω κώδικα και να καταχωρίζετε callbacks για συμβάντα συνομιλίας.

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

Ξεκινώντας

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

Τοποθετήστε αυτό πριν από την ετικέτα script του ChatLab:

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

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

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

        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). Μέσα σε αυτό, το αντικείμενο API είναι εγγυημένο ότι υπάρχει και η συνεδρία είναι ενεργή, επομένως μπορείτε να καλείτε με ασφάλεια τις συναρτήσεις sendMessage(), updateClientContext() και να καταχωρίζετε callbacks συμβάντων.

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

Συμβουλή: Εάν χρειάζεται μόνο να ελέγξετε το widget (εμφάνιση/απόκρυψη/εναλλαγή) και δεν χρειάζεστε ενεργή συνεδρία, παρακολουθήστε εναλλακτικά το DOM event 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) Ενημέρωση πλαισίου χρήστη (context - δείτε παρακάτω)
setLanguage(code) Εναλλαγή του widget σε μια γλώσσα (μόνο για πολύγλωσσα bots, δείτε παρακάτω)
getLanguage() Επιστροφή της γλώσσας που χρησιμοποιεί αυτή τη στιγμή το widget
getAvailableLanguages() Επιστροφή της λίστας γλωσσών που προσφέρει το bot
addCallback(name, fn) Καταχώριση ενός 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 string (ID προϊόντος ή σύνδεσμος) Ο χρήστης έκανε κλικ σε ένα προϊόν (απαιτείται ενεργοποίηση του Offer Cards)
onLeadCollectionFormSubmit {email, phone, name} Υποβλήθηκε η φόρμα συλλογής lead
onContactFormSubmit {email, message} Υποβλήθηκε η φόρμα επικοινωνίας/υποστήριξης
onLiveChatFormSubmit {name, email} Υποβλήθηκε η φόρμα Live Chat

Παλαιού τύπου Callbacks συμβάντων (Καταργημένα)

Το αντικείμενο window.aichatbotCallback υποστηρίζει επίσης τα onUserMessage και onChatbotMessage ως άμεσες ιδιότητες. Αυτή η μορφή είναι καταργημένη (deprecated) - χρησιμοποιήστε αντ' αυτού τη συνάρτηση addCallback() για πρόσβαση σε όλους τους τύπους callbacks:

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

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

Ανάπτυξη μέσω Iframe

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

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

const chatbotIframe = document.querySelector('iframe');

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

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

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

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

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

Λήψη Callbacks

window.addEventListener('message', (event) => {
    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;
    }
});

Ενημέρωση πλαισίου πελάτη (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 (προαιρετικό): Διακριτικό ασφαλείας (security token) για εξουσιοδότηση API
  • clientHostContext (προαιρετικό): Πρόσθετες παράμετροι πλαισίου προσβάσιμες σε προσαρμοσμένες ενέργειες API

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

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

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Προσαρμοσμένες παράμετροι host context με πρόθεμα 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 αγνοείται.

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

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

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