Przegląd Chat API
Widget API pozwala programowo sterować widgetem czatu i rejestrować wywołania zwrotne (callbacks) dla zdarzeń czatu.
Szukasz REST API? Ten artykuł opisuje działające w przeglądarce JavaScript widget API (window.aichatbotApi) dla stron, na których osadzony jest widget ChatLab. Informacje o interfejsie REST API server-to-server, służącym do prowadzenia rozmów z botami z poziomu Twojego backendu lub programowego zarządzania botami, znajdziesz w artykułach o Bot Talk API i Management API.
Pierwsze kroki
API chatbota nie jest dostępne od razu po załadowaniu Twojej strony - skrypt musi się najpierw załadować i zainicjalizować. Musisz użyć window.aichatbotCallback.onSessionActivated jako mechanizmu bootstrap, aby bezpiecznie uzyskać dostęp do API.
Użyj publicznego klucza widgetu z zakładki Deploy (Wdrożenie) jako YOUR_API_KEY, nigdy tajnego klucza ck_ ani mk_. Zachowaj identyfikator dostawcy i host skryptu z własnego fragmentu kodu w sekcji Deploy. Umieść konfigurację callbacku przed tym tagiem skryptu:
<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 uruchamia się, gdy sesja stanie się dostępna, w tym także przy przywróconych sesjach. W zależności od ustawień wdrożenia i ekranu powitalnego nie musi to być pierwsze kliknięcie otwierające widget. Może uruchomić się ponownie; zarejestruj callbacki raz na obiekt API, aby uniknąć zduplikowanych procedur obsługi. Wewnątrz niego masz gwarancję, że obiekt API istnieje, a sesja jest aktywna, dzięki czemu możesz bezpiecznie wywoływać sendMessage(), updateClientContext() oraz rejestrować callbacki zdarzeń.
Ważne: Nie wywołuj window.aichatbotApi.getChatbotApi() bezpośrednio w skrypcie swojej strony bez oczekiwania - obiekt API nie istnieje, dopóki skrypt ChatLab się nie załaduje i nie zainicjalizuje.
Wskazówka: Jeśli potrzebujesz jedynie kontrolować widget (pokazywać/ukrywać/przełączać) i nie wymagasz aktywnej sesji, nasłuchuj zamiast tego zdarzenia DOM aichatbotReady:
window.addEventListener('aichatbotReady', function(e) {
var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);
chatbot.showChat();
});
Metody
| Metoda | Opis |
|---|---|
showChat() |
Otwórz widget czatu |
hideChat() |
Zamknij widget czatu |
toggleChat() |
Przełącz widoczność widgetu |
sendMessage(text) |
Wyślij wiadomość programowo |
updateClientContext(data) |
Zaktualizuj kontekst użytkownika (szczegóły poniżej) |
setLanguage(code) |
Przełącz widget na dany język (tylko boty wielojęzyczne, szczegóły poniżej) |
getLanguage() |
Zwróć język aktualnie używany przez widget |
getAvailableLanguages() |
Zwróć listę języków oferowanych przez bota |
addCallback(name, fn) |
Zarejestruj funkcję zwrotną dla zdarzenia |
Uwaga: Metody sendMessage oraz updateClientContext wymagają aktywnej sesji. Skorzystaj ze wzorca inicjalizacji onSessionActivated przedstawionego w sekcji Pierwsze kroki.
Wywołania zwrotne (callbacks)
Zarejestruj wywołania zwrotne zdarzeń wewnątrz swojej funkcji obsługi onSessionActivated (zobacz Pierwsze kroki):
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);
});
Dostępne wywołania zwrotne
| Wywołanie zwrotne | Dane | Opis |
|---|---|---|
onSessionActivated |
- | Sesja czatu jest gotowa |
onUserMessage |
string |
Użytkownik wysłał wiadomość |
onChatbotMessage |
string |
Bot odpowiedział wiadomością |
onProductClick |
Ładunek produktu/linku z wyrenderowanej karty | Użytkownik kliknął link produktu; sprawdź ładunek dla swojego typu karty |
onLeadCollectionFormSubmit |
{email, phone, name} |
Wysłano formularz zbierania leadów |
onContactFormSubmit |
{email, message} |
Wysłano formularz kontaktowy/wsparcia |
onLiveChatFormSubmit |
{name, email} |
Wysłano formularz czatu na żywo; nie oznacza to dołączenia konsultanta |
onCustomFormSubmit |
{formId, values} |
Wysłano formularz niestandardowy; dane przesłanych plików nie są zawarte w tym wywołaniu |
Wywołania zwrotne formularzy zgłaszają wysłanie po stronie przeglądarki, a nie potwierdzony zapis w bazie czy pomyślne doręczenie. Do przetwarzania potwierdzonego przez backend użyj webhooków. Ładunki wywołań zwrotnych mogą zawierać dane osobowe; nie przekazuj ich w całości do systemów analitycznych ani publicznych logów.
Starsze wywołania zwrotne zdarzeń
Obiekt window.aichatbotCallback obsługuje również onUserMessage oraz onChatbotMessage jako bezpośrednie właściwości. Użyj addCallback() dla modułowych funkcji nasłuchujących bez zastępowania obiektu globalnego:
window.aichatbotCallback = {
onUserMessage(message) { ... },
onChatbotMessage(message) { ... }
};
Uwaga: window.aichatbotCallback.onSessionActivated nie jest przestarzałe - jest to zalecany mechanizm startowy do inicjalizacji Chat API (zobacz Pierwsze kroki).
Wdrożenie przez iframe
W przypadku wdrożenia przez iframe użyj postMessage do komunikacji z chatbotem:
Wysyłanie poleceń
// 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);
Odbieranie wywołań zwrotnych
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;
}
});
Zaktualizuj kontekst klienta
Funkcja updateClientContext pozwala zaktualizować kontekst klienta podczas aktywnej sesji:
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"
}
});
Parametry:
- clientId (wymagany): Unikalny identyfikator klienta
- clientName, clientEmail, clientPhone (opcjonalne): Dane klienta wyświetlane w rozmowach
- clientSecurityToken (opcjonalny): Token przekazywany jako kontekst dla Twojej niestandardowej integracji. Twoje własne API musi zweryfikować jego autentyczność, ważność oraz uprawnienia.
- clientHostContext (opcjonalny): Dodatkowe parametry kontekstu dostępne w niestandardowych akcjach API
Identyfikatory i kontekst przekazywane przez przeglądarkę nie stanowią dowodu tożsamości. Nie umieszczaj w kodzie JavaScript strony sekretów dotyczących całego konta i nie przyznawaj dostępu wyłącznie na podstawie tego, że podany clientId lub adres e-mail pasuje do rekordu.
Użycie w wywołaniach API:
Atrybuty kontekstu mogą być używane w wywołaniach funkcji API poprzez skonfigurowanie parametru API jako typu "Context":
clientName,clientEmail,clientPhone,clientSecurityToken- Niestandardowe parametry kontekstu hosta poprzedzone prefiksem
client, np.clientparam1,clientparam2
Język
Te metody działają tylko w chatbotach wielojęzycznych. W bocie jednojęzycznym widget nie ma warstwy językowej do przełączenia, więc setLanguage() nic nie robi, a getAvailableLanguages() zwraca wyłącznie własny język bota. Najpierw włącz obsługę wielu języków w Settings > Languages (Ustawienia > Języki) - zobacz Wielojęzyczne chatboty.
Użyj setLanguage(), gdy Twoja strona istnieje w kilku językach i chcesz, aby czat otwierał się w tym, który użytkownik właśnie przegląda, zamiast w języku ustawionym w jego przeglądarce:
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", ...]
});
Możesz także zadeklarować język strony przed załadowaniem skryptu, co pozwala uniknąć chwilowego mignięcia niewłaściwego języka:
<script>window.aichatbotLanguage = "de";</script>
Który język ma pierwszeństwo. Widget ustala język w następującej kolejności:
- Język wybrany samodzielnie przez odwiedzającego w menu językowym samego widgetu.
- Język strony, z
setLanguage()lubwindow.aichatbotLanguage. - Język przeglądarki odwiedzającego.
- Język bazowy chatbota.
Samodzielny wybór odwiedzającego jest zapamiętywany na kolejne wizyty, ale przestaje obowiązywać, gdy zmieni się język strony - dzięki temu przełącznik języka na Twojej stronie zawsze wygrywa z nieaktualnym wyborem. Kody są zgodne z ISO 639-1 (en, de, pl); kod regionalny, taki jak de-AT, jest sprowadzany do de. Język, którego bot nie obsługuje, jest ignorowany.
Przełączenie języka nie kończy rozmowy ani nie czyści historii rozmów.