Chat API apžvalga
Valdiklio API leidžia programiškai valdyti pokalbių valdiklį ir registruoti atgalinius iškvietimus (angl. callbacks) pokalbių įvykiams.
Ieškote REST API? Šiame straipsnyje aptariama naršyklės „JavaScript“ valdiklio API (window.aichatbotApi), skirta puslapiams, kuriuose integruotas „ChatLab“ valdiklis. Informacijos apie tiesioginę serverių REST API, naudojamą bendrauti su robotais iš jūsų vidinės sistemos (angl. backend) arba valdyti juos programiškai, ieškokite straipsniuose apie Bot Talk API ir Management API.
Darbo pradžia
Pokalbių roboto API nėra pasiekiamas iš karto, kai tik užsikrauna Jūsų puslapis - pirmiausia scenarijus turi būti įkeltas ir inicializuotas. Norėdami saugiai pasiekti API, kaip paleidimo mechanizmą privalote naudoti window.aichatbotCallback.onSessionActivated.
Naudokite viešąjį valdiklio raktą iš skilties „Test & Deploy“ (testavimas ir diegimas) kaip YOUR_API_KEY, bet niekada nenaudokite slapto ck_ ar mk_ rakto. Teikėjo ID ir scenarijaus pagrindinį kompiuterį (host) paimkite iš to paties įterpimo kodo fragmento. Atgalinio iškvietimo (callback) sąranką įdėkite prieš šią scenarijaus žymą:
<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 suveikia tada, kai sesija tampa pasiekiama, įskaitant atkurtas sesijas. Priklausomai nuo diegimo ir pasveikinimo ekrano nustatymų, tai nebūtinai yra pats pirmas valdiklio atidarymo paspaudimas. Įvykis gali suveikti pakartotinai; užregistruokite atgalinius iškvietimus vieną kartą vienam API objektui, kad išvengtumėte pasikartojančių doroklių. Šio iškvietimo viduje garantuojama, kad API objektas egzistuoja, o sesija yra aktyvi, todėl galite saugiai iškviesti sendMessage(), updateClientContext() ir registruoti įvykių atgalinius iškvietimus.
Svarbu: nekvieskite window.aichatbotApi.getChatbotApi() tiesiogiai savo puslapio scenarijuje nelaukdami - API objektas neegzistuoja tol, kol ChatLab scenarijus nėra visiškai įkeltas ir inicializuotas.
Patarimas: jei Jums tereikia valdyti valdiklį (rodyti / slėpti / perjungti) ir nereikia aktyvios sesijos, verčiau klausykitės aichatbotReady DOM įvykio:
window.addEventListener('aichatbotReady', function(e) {
var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);
chatbot.showChat();
});
Metodai
| Metodas | Aprašymas |
|---|---|
showChat() |
Atidaryti pokalbių valdiklį |
hideChat() |
Uždaryti pokalbių valdiklį |
toggleChat() |
Perjungti valdiklio matomumą |
sendMessage(text) |
Išsiųsti žinutę programiškai |
updateClientContext(data) |
Atnaujinti naudotojo kontekstą (žr. toliau) |
setLanguage(code) |
Perjungti valdiklį į konkrečią kalbą (tik daugiakalbiams robotams, žr. toliau) |
getLanguage() |
Grąžinti kalbą, kurią valdiklis šiuo metu naudoja |
getAvailableLanguages() |
Grąžinti roboto siūlomų kalbų sąrašą |
addCallback(name, fn) |
Užregistruoti įvykio atgalinį iškvietimą |
Pastaba: sendMessage ir updateClientContext reikalauja aktyvios sesijos. Naudokite onSessionActivated inicializavimo šabloną, parodytą skiltyje „Darbo pradžia“.
Atgaliniai iškvietimai (callbacks)
Registruokite įvykių atgalinius iškvietimus savo onSessionActivated apdorojimo funkcijoje (žr. „Darbo pradžia“):
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);
});
Galimi atgaliniai iškvietimai
| Atgalinis iškvietimas | Duomenys | Aprašymas |
|---|---|---|
onSessionActivated |
- | Pokalbio sesija paruošta |
onUserMessage |
string |
Naudotojas išsiuntė žinutę |
onChatbotMessage |
string |
Robotas atsakė žinute |
onProductClick |
Produkto / nuorodos duomenys iš atvaizduotos kortelės | Naudotojas paspaudė produkto nuorodą; patikrinkite savo kortelės tipo duomenų paketą |
onLeadCollectionFormSubmit |
{email, phone, name} |
Pateikta potencialių klientų rinkimo forma |
onContactFormSubmit |
{email, message} |
Pateikta kontaktų / pagalbos forma |
onLiveChatFormSubmit |
{name, email} |
Pateikta tiesioginio pokalbio (Live Chat) forma, tai nėra įrodymas, kad prisijungė operatorius |
onCustomFormSubmit |
{formId, values} |
Pateikta pasirinktinė forma; įkeltų failų duomenys į šį atgalinį iškvietimą neįtraukiami |
Formų atgaliniai iškvietimai praneša apie pateikimą naršyklės pusėje, o ne apie patvirtintą išsaugojimą ar sėkmingą pristatymą. Norėdami gauti serverio patvirtintą apdorojimą, naudokite Webhooks (saityno kibirkštis). Atgalinių iškvietimų duomenyse gali būti asmens duomenų; nepersiųskite jų visų į analitikos sistemas ar viešus žurnalus.
Pasenę įvykių atgaliniai iškvietimai
Objektas window.aichatbotCallback taip pat palaiko onUserMessage ir onChatbotMessage kaip tiesiogines savybes. Naudokite addCallback(), jei norite pridėti modulinių klausytojų nepakeisdami visuotinio objekto:
window.aichatbotCallback = {
onUserMessage(message) { ... },
onChatbotMessage(message) { ... }
};
Pastaba: window.aichatbotCallback.onSessionActivated nėra pasenęs - tai rekomenduojamas paleidimo mechanizmas Chat API inicializavimui (žr. „Darbo pradžia“).
Iframe diegimas
Naudodami iframe diegimą, bendravimui su chatbot naudokite postMessage:
Komandų siuntimas
// Give the ChatLab iframe from Test & 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);
Grįžtamųjų iškvietimų (angl. callbacks) gavimas
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;
}
});
Kliento konteksto atnaujinimas
Funkcija updateClientContext leidžia atnaujinti kliento kontekstą aktyvios sesijos metu:
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"
}
});
Parametrai:
- clientId (privalomas): unikalus kliento identifikatorius
- clientName, clientEmail, clientPhone (neprivalomi): kliento duomenys, rodomi pokalbiuose
- clientSecurityToken (neprivalomas): prieigos raktas, persiunčiamas kaip kontekstas jūsų pasirinktinei integracijai. Jūsų pačių API privalo patikrinti jo autentiškumą, galiojimo laiką ir autorizaciją.
- clientHostContext (neprivalomas): papildomi konteksto parametrai, pasiekiami atliekant pasirinktinius API veiksmus
Naršyklės pateikti ID ir kontekstas nėra tapatybės įrodymas. Niekada nedėkite visos paskyros paslapčių į puslapio „JavaScript“ ir nesuteikite prieigos vien todėl, kad pateiktas clientId ar el. pašto adresas sutampa su įrašu sistemoje.
Naudojimas API iškvietimuose:
Konteksto atributai gali būti naudojami API funkcijų iškvietimuose, sukonfigūravus API parametrą kaip tipo „Context“:
clientName,clientEmail,clientPhone,clientSecurityToken- Pasirinktiniai pagrindinio kompiuterio konteksto (angl. host context) parametrai su priešdėliu
client, pvz.,clientparam1,clientparam2
Kalba
Šie metodai veikia tik daugiakalbiuose pokalbių robotuose. Vienakalbiame robote valdiklis neturi kalbos sluoksnio, kurį būtų galima perjungti, todėl setLanguage() nieko nedaro, o getAvailableLanguages() grąžina tik paties roboto kalbą. Pirmiausia įjunkite kelių kalbų palaikymą skiltyje Settings > Languages (Nustatymai > Kalbos) - žr. Daugiakalbiai pokalbių robotai.
Naudokite setLanguage(), kai jūsų puslapis veikia keliomis kalbomis ir norite, kad pokalbių langas atsidarytų ta kalba, kuria lankytojas skaito puslapį, o ne ta, kuri nustatyta jo naršyklėje:
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", ...]
});
Taip pat puslapio kalbą galite nurodyti prieš įkeliant scenarijų - taip išvengsite trumpo netinkamos kalbos mirktelėjimo:
<script>window.aichatbotLanguage = "de";</script>
Kuri kalba turi pirmenybę. Valdiklis kalbą nustato šia tvarka:
- Kalba, kurią lankytojas pasirinko pats valdiklio kalbų meniu.
- Puslapio kalba, nurodyta per
setLanguage()arbawindow.aichatbotLanguage. - Lankytojo naršyklės kalba.
- Pagrindinė pokalbių roboto kalba.
Paties lankytojo pasirinkimas įsimenamas vėlesniems apsilankymams, tačiau jis nustoja galioti, kai pasikeičia puslapio kalba - taigi jūsų kalbos perjungiklis visada turi pirmenybę prieš nebeaktualų ankstesnį pasirinkimą. Kodai atitinka ISO 639-1 standartą (en, de, pl); regioninis kodas, pavyzdžiui, de-AT, pagal numatytuosius nustatymus perjungiamas į de. Kalba, kurios robotas nesiūlo, yra ignoruojama.
Kalbos perjungimas neužbaigia pokalbio ir neišvalo susirašinėjimo istorijos.