API JavaScript czatu na żywo
Użyj API JavaScript onWebChat, aby dostosować widżet czatu i automatyzować przebieg rozmów. Możesz przekazywać dane odwiedzającego, ustawiać język widżetu, maksymalizować lub ukrywać widżet i nie tylko.
Na przykład możesz przekazać do czatu dane odwiedzającego, ustawić język dla konkretnej strony lub programowo otworzyć widżet, gdy użytkownik kliknie przycisk.
Dodaj swój kod API tuż pod skryptem widżetu czatu, jak pokazano po prawej.
<script type='text/javascript'>
/* Wklej tutaj fragment kodu instalacyjnego widżetu onWebChat z panelu. */
</script>
<script type='text/javascript'>
/* Dodaj poniżej wywołania JavaScript API, na przykład onWebChat.set() lub onWebChat.get() */
</script>
Ustawianie danych odwiedzającego
Możesz ustawiać dane odwiedzającego przed lub podczas sesji czatu. Ustawienie imienia pomaga zespołowi identyfikować kontakty na liście odwiedzających.
Użyj tych wywołań API, aby ustawić imię, e-mail, telefon i notatki odwiedzającego:
onWebChat.set("name","Sarah Chen");
onWebChat.set("email","sarah.chen@example.com");
onWebChat.set("phone","+1 555 010 0142");
onWebChat.set("notes","Returning visitor, requested an Enterprise trial");
Pobieranie danych odwiedzającego
Możesz odczytać imię, e-mail, telefon i notatki odwiedzającego, jeśli wartości te zostały podane za pośrednictwem tego API JavaScript, zebrane w formularzu przed czatem lub zaktualizowane przez agentów w panelu.
Wywołaj te funkcje dopiero po pełnym załadowaniu widżetu. Przykład:
onWebChat.set("onWebChatLoaded", function() { console.log("visitor name: " + onWebChat.get("name")); });
onWebChat.get("name");
onWebChat.get("email");
onWebChat.get("phone");
onWebChat.get("notes");
Ustawianie języka widżetu
Możesz ustawić język widżetu za pomocą kodu dowolnego języka włączonego w panelu.
Na przykład "pl" dla polskiego, "en" dla angielskiego i "de" dla niemieckiego. Jeśli podany kod języka nie jest włączony, widżet użyje Twojego języka domyślnego. Bez tego wywołania widżet używa języka przeglądarki odwiedzającego, jeśli masz włączony ten język. Włączonymi językami i językiem domyślnym zarządzasz w Settings > Widget > Languages.
Dostępne kody języków:
onWebChat.set("language","es");
Ustawianie wyglądu widżetu
Możesz sterować widocznością widżetu i tym, czy jest otwarty:
Użyj parametru max z wartością 0, aby zminimalizować widżet, lub 1, aby go zmaksymalizować.
Aby całkowicie ukryć widżet, użyj parametru show z wartością 0. Użyj 1, aby ponownie go pokazać.
onWebChat.set("max",1);
onWebChat.set("show",0);
Ustawianie rozmiaru widżetu
Na wybranej stronie możesz pokazać widżet w jednym z trzech rozmiarów dostępnych w Settings > Widget > Widget settings, bez zmiany rozmiaru zapisanego na Twoim koncie.
Użyj parametru size z wartością "standard" (rozmiar Small w panelu), "large" lub "xlarge" (Extra Large). Przydaje się to na stronach z małą ilością wolnego miejsca albo na stronie docelowej (landing page), na której chcesz pokazać większy widżet.
Ważne: umieść to wywołanie tuż pod skryptem widżetu, zanim widżet się załaduje. Widżet jest budowany raz, podczas ładowania, więc rozmiar ustawiony później jest ignorowany.
onWebChat.set("size","standard");
onWebChat.set("size","large");
onWebChat.set("size","xlarge");
Zmiana tekstów widżetu
Możesz zastąpić teksty widżetu na wybranej stronie, na przykład wyświetlić inne powitanie na stronie z cennikiem. Nowe teksty działają tylko na tej stronie i nie są zapisywane w panelu.
Użyj parametru texts z obiektem zawierającym pola, które chcesz zmienić, np. max_title, max_subtitle, min_online, min_offline, off_title, off_subtitle, off_msg lub prechat_msg.
Tekst podany jako ciąg znaków jest używany we wszystkich językach widżetu. Aby zmienić tylko jeden język, przekaż obiekt z kodami języków, jak w drugim przykładzie.
Możesz ją wywołać pod skryptem widżetu, zanim widżet się załaduje, albo w dowolnym momencie później: widżet zostanie wtedy przerysowany z nowymi tekstami.
onWebChat.set("texts",{
max_title: "Need help?",
max_subtitle: "We usually reply in a minute"
});
onWebChat.set("texts",{
min_online: { en: "Chat with us", es: "Chatea con nosotros" }
});
Ustawianie kolorów widżetu
Na wybranej stronie możesz nadać nagłówkowi widżetu jeden kolor, gdy czat jest online, i inny, gdy jest offline. Użyj parametrów onlineColor i offlineColor z dowolnym kolorem CSS, np. "#2e7d32".
Kolory działają tylko na tej stronie i nie zmieniają koloru zapisanego w Settings > Widget > Widget settings. Możesz je ustawić przed załadowaniem widżetu albo w dowolnym momencie później. Kolor offline jest też używany dla przycisku wysyłania w formularzu offline.
onWebChat.set("onlineColor","#2e7d32");
onWebChat.set("offlineColor","#757575");
Ustawianie informacji o stronie
Możesz nadpisać aktualny adres URL i tytuł strony, które trafiają do panelu onWebChat:
Użyj parametru pageUrl, aby ustawić własny adres URL. Jest to szczególnie przydatne w aplikacjach typu single-page (SPA) lub przy własnym routingu, gdy adres URL w przeglądarce się nie zmienia.
Użyj parametru pageTitle, aby ustawić niestandardowy tytuł, który agenci zobaczą zamiast tytułu strony przeglądarki.
onWebChat.set("pageUrl","https://www.example.com/checkout/step-2");
onWebChat.set("pageTitle","Checkout: shipping details");
Pobieranie statusu widżetu
Zwraca "online" lub "offline" w zależności od aktualnej dostępności czatu.
Wywołaj ją dopiero po pełnym załadowaniu widżetu. Przykład:
onWebChat.set("onWebChatLoaded", function() { console.log("chat status: " + onWebChat.get("status")); });
onWebChat.get("status");
Pobieranie statusu połączenia
Zwraca true, jeśli widżet czatu ma aktywne połączenie (socket) z serwerem, a w przeciwnym razie false.
onWebChat.get("isConnected");
Stan otwarty/zamknięty widżetu
Zwraca true, jeśli widżet czatu jest aktualnie zmaksymalizowany (otwarty), lub false, jeśli jest zminimalizowany (zamknięty).
onWebChat.get("isMaximized");
Pobieranie ID dialogu
Zwraca ID aktualnie aktywnego dialogu lub 0, jeśli nie ma aktywnej sesji czatu. To ten sam identyfikator co chat_id w danych webhooków, więc przydaje się w integracjach, które muszą powiązać sesję czatu z CRM lub systemem zgłoszeń.
onWebChat.get("dialogId");
Wysyłanie wiadomości
Możesz programowo wysłać wiadomość czatu w imieniu odwiedzającego. Przydaje się to do tworzenia kontekstowych ścieżek pomocy, np. automatycznego wysłania „Potrzebuję pomocy z zamówieniem”, gdy odwiedzający kliknie określony przycisk.
Wiadomość pojawi się w czacie dokładnie tak, jakby napisał ją odwiedzający, a okno czatu się otworzy. Przed wysłaniem wiadomości widżet musi być w pełni załadowany i połączony. Aby zapobiec nadużyciom, widżet wysyła w ten sposób maksymalnie 3 wiadomości na sekundę, 8 na minutę i 30 na godzinę.
onWebChat.set("sendMessage","I need help with my order");
Ustawianie działu
Możesz wstępnie wybrać dział dla odwiedzającego na podstawie kontekstu strony. Na przykład możesz automatycznie kierować odwiedzających ze strony cennika do działu „Sprzedaż”, a odwiedzających ze strony pomocy do działu „Wsparcie”.
Możesz przekazać nazwę działu (jako string) lub ID działu (jako liczbę). Jeśli używasz nazwy, musi ona dokładnie odpowiadać jednemu z działów skonfigurowanych w panelu.
ID działu znajdziesz w panelu: przejdź do Settings > Team > Departments i kliknij dział. ID jest wyświetlane obok nazwy działu.
Nie musisz włączać opcji działów w formularzu przed czatem: ustawienie działu przez API JavaScript działa samodzielnie.
Jeśli żaden agent wybranego działu nie jest online, wiadomość trafia do wszystkich połączonych agentów. Jeśli chatbot AI jest włączony, nie odpowiada, dopóki online jest agent tego działu, a odpowiada odwiedzającemu, gdy nikogo z działu nie ma online.
Więcej informacji o działach znajdziesz w naszym przewodniku po działach.
onWebChat.set("department","Sales");
onWebChat.set("department",1333);
Funkcje callback
Możesz uruchamiać funkcje callback przy określonych zdarzeniach czatu:
onClick uruchamia się, gdy odwiedzający kliknie widżet czatu.
onMaximize uruchamia się, gdy widżet zostanie zmaksymalizowany (otwarty).
onMinimize uruchamia się, gdy widżet zostanie zminimalizowany (zamknięty).
onTrigger uruchamia się, gdy zadziała wyzwalacz typu Engagement lub Exit-intent, nawet jeśli widżet jest ukryty (show ustawione na 0).
onStartWriting uruchamia się, gdy odwiedzający zaczyna pisać wiadomość (raz na sesję przeglądarki).
onNewMessage uruchamia się, gdy nowa wiadomość zostanie wysłana lub odebrana. Callback otrzymuje dwa argumenty: tekst wiadomości i nadawcę ("visitor", "agent" lub "bot").
onEndChat uruchamia się, gdy sesja czatu się zakończy. Callback otrzymuje jeden argument wskazujący, kto ją zakończył ("visitor", "agent" lub "bot").
onChatStatusChange uruchamia się, gdy zmieni się status widżetu czatu. Callback otrzymuje jeden argument wskazujący nowy status ("online" lub "offline").
onWebChatLoaded uruchamia się, gdy tylko widżet czatu zakończy ładowanie.
onWebChat.set("onClick",function(){ alert('chat widget is clicked'); });
onWebChat.set("onMaximize",function(){ alert('chat maximized'); });
onWebChat.set("onMinimize",function(){ alert('chat minimized'); });
onWebChat.set("onTrigger",function(){ alert('trigger activated'); });
onWebChat.set("onStartWriting",function(){ alert('visitor is writing'); });
onWebChat.set("onNewMessage",function(msg, by){
console.log('new message by ' + by + ': ' + msg);
});
onWebChat.set("onEndChat",function(endedBy){
console.log('chat ended by ' + endedBy);
});
onWebChat.set("onChatStatusChange",function(status){
console.log('agents are now ' + status);
});
onWebChat.set("onWebChatLoaded",function(){ alert('chat widget is loaded'); });