Palīdzības centrs
Chat API

Chat API

Pēdējo reizi atjaunināts:

Chat API pārskats

Logrīka API ļ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 aprakstīts pārlūkprogrammas JavaScript logrīka API (window.aichatbotApi) lapām, kurās ir iegults ChatLab logrīks. Lai uzzinātu par serveris-serveris REST API, ko izmanto sarunām ar botiem no jūsu aizmugursistēmas vai botu programmatiskai 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. Lai droši piekļūtu API, kā sākotnējās ielādes mehānisms ir jāizmanto window.aichatbotCallback.onSessionActivated.

Kā YOUR_API_KEY izmantojiet publisko logrīka atslēgu no sadaļas Deploy (Izvietot), nekad neizmantojiet slepeno ck_ vai mk_ atslēgu. Saglabājiet pakalpojumu sniedzēja ID un skripta resursdatoru no sava Deploy koda fragmenta. Ievietojiet atzvana iestatījumu pirms šī skripta taga:

<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 nostrādā, kad sesija kļūst pieejama, tostarp atjaunotām sesijām. Atkarībā no izvietošanas un sagaidīšanas ekrāna iestatījumiem tas ne vienmēr ir pirmais klikšķis, kas atver logrīku. Tas var nostrādāt atkārtoti; reģistrējiet atzvanus vienreiz katram API objektam, lai izvairītos no apstrādātāju dublēšanās. Tā iekšienē tiek garantēts, ka API objekts eksistē 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 savas lapas skriptā bez nogaidīšanas - API objekts neeksistē, 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 aichatbotReady DOM notikumu:

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) Nosūtīt ziņojumu programmatiski
updateClientContext(data) Atjaunināt lietotāja kontekstu (skatīt zemāk)
setLanguage(code) Pārslēgt logrīku uz noteiktu valodu (tikai daudzvalodu botiem, skatīt zemāk)
getLanguage() Atgriezt valodu, kuru logrīks pašlaik izmanto
getAvailableLanguages() Atgriezt bota piedāvāto valodu sarakstu
addCallback(name, fn) Reģistrēt notikuma atzvanu

Piezīme: Funkcijām sendMessage un updateClientContext ir nepieciešama aktīva sesija. Izmantojiet sadaļā "Darba sākšana" parādīto onSessionActivated inicializācijas shēmu.

Atzvani

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 Produkta/saites dati no renderētās kartītes Lietotājs noklikšķināja uz produkta saites; pārbaudiet datus savam kartītes veidam
onLeadCollectionFormSubmit {email, phone, name} Iesniegta interesentu piesaistes (lead collection) veidlapa
onContactFormSubmit {email, message} Iesniegta saziņas/atbalsta veidlapa
onLiveChatFormSubmit {name, email} Iesniegta Live Chat veidlapa; tas nepierāda, ka operators ir pievienojies
onCustomFormSubmit {formId, values} Iesniegta pielāgota veidlapa; augšupielādēto failu dati šajā atzvanā netiek iekļauti

Veidlapu atzvani ziņo par iesniegšanu pārlūkprogrammas pusē, nevis par apstiprinātu saglabāšanu vai veiksmīgu piegādi. Lai nodrošinātu aizmugursistēmas apstiprinātu apstrādi, izmantojiet sadaļu Webhooks. Atzvanu dati var saturēt personas datus; nepārsūtiet tos pilnībā analītikai vai publiskiem žurnāliem.

Mantotie notikumu atzvani

Objekts window.aichatbotCallback atbalsta arī onUserMessage un onChatbotMessage kā tiešos rekvizītus. Izmantojiet addCallback() modulāriem klausītājiem, neaizstājot globālo objektu:

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

Piezīme: window.aichatbotCallback.onSessionActivated nav novecojis - tas ir ieteicamais sākotnējās ielādes mehānisms Chat API inicializēšanai (skatīt sadaļu "Darba sākšana").

Izvietošana ar Iframe

Izmantojot iframe izvietošanu, izmantojiet postMessage, lai sazinātos ar tērzēšanas botu:

Komandu sūtīšana

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

Atzvanu saņemšana

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

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 informācija, kas tiek parādīta sarunās
  • clientSecurityToken (neobligāts): Pilnvara (token), kas tiek pārsūtīta kā konteksts jūsu pielāgotajai integrācijai. Jūsu pašu API ir jāpārbauda tās autentiskums, derīguma termiņš un autorizācija.
  • clientHostContext (neobligāts): Papildu konteksta parametri, kas pieejami pielāgotās API darbībās

Pārlūkprogrammas sniegtie ID un konteksts nav identitātes apliecinājums. Neievietojiet visa konta noslēpumus lapas JavaScript kodā un nepiešķiriet piekļuvi tikai tāpēc, ka norādītais clientId vai e-pasta adrese atbilst ierakstam sistēmā.

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 resursdatora konteksta parametri ar prefiksu client, piemēram, clientparam1, clientparam2

Valoda

Šīs metodes darbojas tikai daudzvalodu tērzēšanas botiem. Vienas valodas 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.

Izmantojiet setLanguage(), ja jūsu lapa ir pieejama vairākās valodās un vēlaties, lai tērzēšana tiktu atvērta tajā valodā, kuru apmeklētājs lasa, nevis tajā, kāda 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", ...]
});

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

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

Kurai valodai ir prioritāte. Logrīks nosaka valodu šādā secībā:

  1. Valoda, kuru apmeklētājs pats izvēlējies logrīka valodu izvēlnē.
  2. Lapas valoda no setLanguage() vai window.aichatbotLanguage.
  3. Apmeklētāja pārlūkprogrammas valoda.
  4. Tērzēšanas bota pamata valoda.

Apmeklētāja paša veiktā izvēle tiek saglabāta turpmākajiem 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ējs vienmēr ņem virsroku pār iepriekšējo izvēli. Kodu formāts ir ISO 639-1 (en, de, pl); reģionālais kods, piemēram, de-AT, tiek aizstāts ar pamata kodu de. Valoda, kuru bots nepiedāvā, tiek ignorēta.

Valodas pārslēgšana nepārtrauc sarunu un neizdzēš tās teksta atšifrējumu.

Saistītie raksti

Meklēt visus rakstusJautājiet aģentam