Palīdzības centrs
Chat API

Chat API

Pēdējo reizi atjaunināts:

Chat API pārskats

Šī funkcija ir pieejama tikai noteiktos plānos. Tā ļauj programmatiski vadīt tērzēšanas logrīku un reģistrēt atzvanus (callbacks) tērzēšanas notikumiem.

Meklējat REST API? Šajā rakstā ir apskatīts pārlūkprogrammas JavaScript logrīka API (window.aichatbotApi) lapām, kurās ir iegults ChatLab logrīks. Lai uzzinātu par servera-servera REST API, ko izmanto sarunām ar botiem no jūsu aizmugursistēmas vai programmatiskai botu pārvaldībai, skatiet rakstus Bot Talk API un Management API.

Darba sākšana

Tērzēšanas bota API nav pieejams uzreiz pēc lapas ielādes - skriptam vispirms ir jāielādējas un jāinicializējas. Jums obligāti jāizmanto window.aichatbotCallback.onSessionActivated kā sāknēšanas mehānisms, lai droši piekļūtu API.

Ievietojiet šo koda fragmentu pirms ChatLab skripta taga:

<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 nostrādā, kad tiek izveidota tērzēšanas sesija (t.i., lietotājs atver logrīku). Tā iekšienē API objekts garantēti pastāv un sesija ir aktīva, tāpēc varat droši izsaukt sendMessage(), updateClientContext() un reģistrēt notikumu atzvanus.

Svarīgi: Neizsauciet window.aichatbotApi.getChatbotApi() tieši lapas skriptā bez nogaidīšanas - API objekts nepastāv, kamēr ChatLab skripts nav ielādēts un inicializēts.

Padoms: Ja jums ir nepieciešams tikai vadīt logrīku (parādīt/paslēpt/pārslēgt) un nav nepieciešama aktīva sesija, tā vietā klausieties DOM notikumu aichatbotReady:

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

Metodes

Metode Apraksts
showChat() Atvērt tērzēšanas logrīku
hideChat() Aizvērt tērzēšanas logrīku
toggleChat() Pārslēgt logrīka redzamību
sendMessage(text) Sūtīt ziņojumu programmatiski
updateClientContext(data) Atjaunināt lietotāja kontekstu (skatīt zemāk)
setLanguage(code) Pārslēgt logrīku uz konkrētu valodu (tikai daudzvalodu botiem, skatīt zemāk)
getLanguage() Atgriezt valodu, ko logrīks pašlaik izmanto
getAvailableLanguages() Atgriezt bota piedāvāto valodu sarakstu
addCallback(name, fn) Reģistrēt notikuma atzvanu

Piezīme: Metodēm sendMessage un updateClientContext ir nepieciešama aktīva sesija. Izmantojiet inicializācijas modeli onSessionActivated, kas parādīts sadaļā Darba sākšana.

Atzvani (callbacks)

Reģistrējiet notikumu atzvanus savā onSessionActivated apstrādātājā (skatīt sadaļu Darba sākšana):

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

Pieejamie atzvani

Atzvans Dati Apraksts
onSessionActivated - Tērzēšanas sesija ir gatava
onUserMessage string Lietotājs nosūtīja ziņojumu
onChatbotMessage string Bots atbildēja ar ziņojumu
onProductClick string (produkta ID vai saite) Lietotājs noklikšķināja uz produkta (nepieciešams iespējot Offer Cards)
onLeadCollectionFormSubmit {email, phone, name} Tika iesniegta lead iegūšanas veidlapa
onContactFormSubmit {email, message} Tika iesniegta saziņas/atbalsta veidlapa
onLiveChatFormSubmit {name, email} Tika iesniegta Live Chat veidlapa

Novecojušie notikumu atzvani (Deprecated)

Objekts window.aichatbotCallback atbalsta arī onUserMessage un onChatbotMessage kā tiešos rekvizītus. Šis formāts ir novecojis - tā vietā izmantojiet addCallback(), lai piekļūtu visiem atzvanu veidiem:

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

Piezīme: window.aichatbotCallback.onSessionActivated nav novecojis - tas ir ieteicamais sāknēšanas mehānisms Chat API inicializācijai (skatīt sadaļu Darba sākšana).

Izvietošana ar iframe

Izmantojot izvietošanu iframe ietvarā, saziņai ar tērzēšanas botu izmantojiet postMessage:

Komandu nosūtīšana

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'
}, '*');

Atzvanu saņemšana

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

Klienta konteksta atjaunināšana

Funkcija updateClientContext ļauj atjaunināt klienta kontekstu aktīvas sesijas laikā:

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

Parametri:

  • clientId (obligāts): Klienta unikālais identifikators
  • clientName, clientEmail, clientPhone (neobligāti): Klienta dati, kas tiek rādīti sarunās
  • clientSecurityToken (neobligāti): Drošības marķieris (token) API autorizācijai
  • clientHostContext (neobligāti): Papildu konteksta parametri, kas pieejami pielāgotās API darbībās

Lietošana API izsaukumos:

Konteksta atribūtus var izmantot API funkciju izsaukumos, konfigurējot API parametru ar tipu "Context":

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Pielāgoti saimniekdatora konteksta parametri ar priedēkli client, piemēram, clientparam1, clientparam2

Valoda

Šīs metodes darbojas tikai daudzvalodu tērzēšanas botiem. Vienvalodas botam logrīkam nav valodu slāņa, ko pārslēgt, tāpēc setLanguage() neko nedara un getAvailableLanguages() atgriež tikai paša bota valodu. Vispirms ieslēdziet daudzvalodu atbalstu sadaļā Settings > Languages (Iestatījumi > Valodas) - skatiet rakstu Multilingual chatbots (Daudzvalodu tērzēšanas boti).

Izmantojiet setLanguage(), ja jūsu lapa ir pieejama vairākās valodās un vēlaties, lai tērzēšana atvērtos tajā valodā, kuru apmeklētājs lasa, nevis tajā, kas nejauši ir iestatīta viņa pārlūkprogrammā:

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

Lapu valodu var deklarēt arī pirms skripta ielādes, kas ļauj izvairīties no īslaicīgas nepareizās valodas parādīšanās:

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

Kura valoda ņem virsroku. Logrīks nosaka valodu šādā secībā:

  1. Valoda, ko apmeklētājs pats izvēlējies logrīka valodu izvēlnē.
  2. Lapas valoda, kas norādīta ar setLanguage() vai window.aichatbotLanguage.
  3. Apmeklētāja pārlūkprogrammas valoda.
  4. Tērzēšanas bota bāzes valoda.

Apmeklētāja paša izvēle tiek saglabāta nākamajiem apmeklējumiem, taču tā vairs netiek piemērota, tiklīdz mainās lapas valoda - tādējādi jūsu valodu pārslēdzējam vienmēr ir prioritāte pār novecojušu izvēli. Kodu formāts ir ISO 639-1 (en, de, pl); reģionālais kods, piemēram, de-AT, izmanto rezerves variantu de. Valoda, ko bots nepiedāvā, tiek ignorēta.

Valodas pārslēgšana nepārtrauc sarunu un neizdzēš tās tekstu.

Saistītie raksti

Meklēt visus rakstusJautājiet aģentam