Conversations SDK

Mit dem Live-Chat-Widget von HubSpot können Sie mit Kunden und Leads auf Ihrer eigenen Website chatten. Mit dem Chat-Widget-SDK können Sie Besuchern ein individuelleres Erlebnis bieten, indem Sie das Verhalten des Chat-Widgets anpassen.

Anwendungsfall: Das Chat-Widget-SDK kann verwendet werden, um anzupassen, wann und wie das Chat-Widget von HubSpot auf Ihrer Website angezeigt wird.

Auf allgemeiner Ebene können Sie Folgendes tun:

Erste Schritte

Die API befindet sich im  window.HubSpotConversations-Objekt. Alle verfügbaren Methoden können über dieses Objekt aufgerufen werden. Der HubSpot-Skriptlader (also der HubSpot-Tracking-Code) auf Ihrer Seite erstellt dieses Objekt für Sie, aber es ist möglicherweise nicht sofort verfügbar. Um den Zugriff auf die API zu verschieben, bis sie initialisiert ist, können Sie den window.hsConversationsOnReady-Helfer verwenden. Im Folgenden finden Sie ein einfaches Beispiel:

<script type="text/javascript"> function onConversationsAPIReady() { console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`); } /* configure window.hsConversationsSettings if needed. */ window.hsConversationsSettings = {}; /* If external API methods are already available, use them. */ if (window.HubSpotConversations) { onConversationsAPIReady(); } else { /* Otherwise, callbacks can be added to the hsConversationsOnReady on the window object. These callbacks will be called once the external API has been initialized. */ window.hsConversationsOnReady = [onConversationsAPIReady]; } </script>

SDK-Referenz 

window.hsConversationsOnReady

Dies ist ein spezielles Feld, das Sie im window-Objekt definieren können. Damit können Sie Code angeben, der ausgeführt wird, sobald das Widget verfügbar ist. Die Verwendung dieser Eigenschaft ist optional. Wenn sie verwendet wird, sollte dieses Feld auf ein Array von Funktionen festgelegt werden. Sobald die API initialisiert wurde, überprüft sie auf das Vorhandensein dieses Arrays und führt seine Funktionen der Treihe nach aus. Zum Beispiel:

if (window.HubSpotConversations) { console.log('The api is ready already'); } else { window.hsConversationsOnReady = [ () => { console.log('Now the api is ready'); }, ]; }

hsConversationsSettings

Dieses Objekt ermöglicht es Ihnen, vor dem Initialisieren einige Konfigurationsoptionen für das Widget anzugeben. Die Verwendung dieses Objekts ist optional.

Felder
Feldname Datentyp Standard  Beschreibung

loadImmediately

 

 Boolesch true Ob das Widget implizit geladen werden oder gewartet werden soll, bis die widget.load-Methode aufgerufen wird
inlineEmbedSelector Zeichenfolge "" Wo das Widget in der Seite eingebettet sein soll. Wenn ein Selektor (z. B. #some-id) angegeben wird, wird das Widget inline in diesem DOM-Knoten eingebettet. Es bleibt so lange offen, bis es über widget.remove entfernt wird
enableWidgetCookieBanner Enumeration false Verhalten des Cookie-Banners für alle Chatflows auf der Seite steuern:

false – Verwenden Sie die Einstellung von Chatflows (Standard)

true – Aktivieren Sie Cookie-Banner, wenn das Widget geladen wird

ON_WIDGET_LOAD – Wie „true“: aktivieren Sie Cookie-Banner, wenn das Widget geladen wird

ON_EXIT_INTENT – Aktivieren Sie Cookie-Banner, wenn der Benutzer scheinbar die Seite verlassen will (Exit Intent)


Beachten Sie, dass dieses Feld früher ein boolesches Feld (Boolean) war. Es kann nun sowohl die ursprünglichen Boolean-Werte als auch die aktualisierten enum-Werte aufnehmen.
disableAttachment Boolesch false Ob die Schaltfläche zum Hochladen eines Anhangs im Chat-Widget ausgeblendet sein soll.
disableInitialInputFocus Boolesch false Legt fest, ob die Fokussierung auf das Eingabefeld des Widgets automatisch verhindert werden soll, nachdem ein eingebettetes Inline-Widget zunächst auf einer Seite geladen wurde.
 
window.hsConversationsSettings = { loadImmediately: false, inlineEmbedSelector: '#some-id', enableWidgetCookieBanner: true, disableAttachment: true }; window.hsConversationsOnReady = [ () => { window.HubSpotConversations.widget.load(); }, ];

Inline-Einbettungsstile

window.hsConversationsOnReady

Wenn das Widget auf einer vom Kunden festgelegten Stelle eingebettet wird, können mehrere DOM-Elemente hinzugefügt und den Anforderungen des Kunden (z. B. Höhe, Breite, Rand) entsprechend formatiert werden. Beachten Sie, dass diese Struktur nur angewendet wird, wenn Sie die  inlineEmbedSelector-Option verwenden.

<�div� �id�=�"hubspot-conversations-inline-parent"�>
<�iframe� �id�=�"hubspot-conversations-inline-iframe"� />
</�div�>

Das Chat-Widget kann beispielsweise standardmäßig wie folgt aussehen:

livechat_before

 

Dieses gequetschte Layout ist nicht ideal, daher können Sie das Widget durch Berücksichtigen von Stilen wie diesem anpassen:


#hubspot-conversations-inline-iframe {
width: 300px;
height: 500px;
border:none;
}

livechat_after

Dies bietet ein sehr viel angenehmeres Benutzererlebnis.

 

HubSpotConversations.widget

Das Widget-Objekt enthält eine Reihe von Methoden, die es Ihnen ermöglichen, das Chat-Widget auf Ihrer Seite zu ändern.

widget.load

Lädt das Widget zum ersten Mal auf der Seite. Wenn das Widget derzeit geladen wird, sind die nachfolgenden Aufrufe dieser Methode Nulloperationen.

Diese Methode ist nur erforderlich, wenn Sie das loadImmediately-Flag auf false festlegen. Andernfalls lädt sich das Widget automatisch selbst.

Hinweis: widget.load wird auf einen Aufruf pro Sekunde gedrosselt.

Parameter:
Feldname Datentyp? Standard Beschreibung
widgetOpen Boolesch false Ob das Widget in einem offenen Zustand geladen werden soll
 
window.HubSpotConversations.widget.load(); /* ... */ // Force the widget to load in an open state window.HubSpotConversations.widget.load({ widgetOpen: true });

widget.refresh

Aktualisiert unter Angabe der aktuellen Seiten-URL die Informationen des Widgets und stellt sie erneut dar.

Wenn sich das Chat-Widget auf einer Anwendung mit nur einer Seite befindet, kann diese Methode nützlich sein, um das Widget bei Routenänderungen zu aktualisieren. Dadurch können Sie unterschiedliche Chatflows auf verschiedenen Seitenrouten angeben. Wenn widget.refresh auf einer Route aufgerufen wird, auf der kein Chatflow vorhanden ist, und der Benutzer nicht gerade in einer Konversation aktiv ist, wird das Widget entfernt.

Hinweis: widget.refresh wird auf einen Aufruf pro Sekunde gedrosselt.

Parameter:
Feldname Datentyp? Standard Beschreibung
openToNewThread Boolesch false Ob das Erstellen eines neuen Threads erzwungen werden soll

Ein Beispiel für die Verwendung des optoNewThread-Feldes finden Sie unter Öffnen eines bestimmten Chatflows auf der Seite.

Beispiel:
window.HubSpotConversations.widget.refresh(); /* ... */ // Force the widget to open to a specific chat flow window.HubSpotConversations.widget.refresh({ openToNewThread: true });

Hinweis: widget.refresh entfernt keine vorhandenen Konversationen, die ein Besucher im Widget gestartet hat.

 

widget.open

Öffnet das Widget. Wenn das Widget bereits geöffnet oder derzeit nicht geladen ist, ist dies eine Nulloperation.

Beispiel:
window.HubSpotConversations.widget.open();

widget.close

Schließt das Widget. Wenn das Widget bereits geschlossen oder derzeit nicht geladen ist, ist dies eine Nulloperation.

Beispiel:
window.HubSpotConversations.widget.close();

widget.remove

Entfernt das Widget von der Seite. Wenn das Widget nicht auf der Seite vorhanden ist, ist dies eine Nulloperation. Um das Widget erneut anzuzeigen, muss eine vollständige Seitenaktualisierung erfolgen, oder widget.load kann aufgerufen werden.

Beispiel:
window.HubSpotConversations.widget.remove();

widget.status

Gibt ein Objekt mit Eigenschaften im Zusammenhang mit dem Widget-Status zurück.

Feldname Datentyp Standard Beschreibung
loaded Boolesch false Ob der Widget-iframe geladen wurde oder nicht.

 

Beispiel:
const status = window.HubSpotConversations.widget.status(); if (status.loaded) { window.HubSpotConversations.widget.refresh(); } else { window.HubSpotConversations.widget.load(); }

clear

Das Chat-Widget erstellt mehrere Cookies, um seinen Zustand über Website-Besuche und Seitenaktualisierungen hinweg beizubehalten. Der Bereich dieser Cookies ist auf die Domain der Seite angepasst, die das Widget hosten, und die Cookies werden zur Unterstützung der folgenden Eigenschaften verwendet:

  • Verweisen auf historische Konversationen
  • Fortsetzen des offenen Zustands des Chat-Widgets über das Laden von Seiten hinweg
  • Fortsetzen des offenen Zustands der Willkommensnachricht über das Laden von Seiten hinweg

Die clear-Methode kann verwendet werden, um diese Cookies zu löschen. Dabei kehrt das Widget bei nachfolgenden Ladevorgängen zu seinem Standardzustand zurück.

Die folgenden Cookies werden mit dieser Methode gelöscht:

  • messagesUtk
  • hs-messages-is-open
  • hs-messages-hide-welcome-message

Weitere Informationen zu diesen Cookies finden Sie in diesem Wissensdatenbankartikel.

Beispiel:
window.HubSpotConversations.clear();

Sie können auch {resetWidget:true} an die clear()-Funktion übergeben, um alle Cookies im Zusammenhang mit Chats zu löschen, das Widget von der Seite zu entfernen und eine neue Instanz des Chat-Widgets zu erstellen.

Beispiel:
window.HubSpotConversations.clear({resetWidget:true});

Event specification

Das Chat-Widget gibt verschiedene Events aus, auf die Sie während deren gesamten Lebenszyklus überwachen und reagieren können.

 

Unterstützte Events

conversationStarted

Wird ausgegeben, wenn eine neue Konversation erfolgreich gestartet wurde.

Event-Payload
Feldname Datentyp Beschreibung
conversation Konversation Details zu der Konversation, die gestartet wurde

 

Beispiel:
window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); });

conversationClosed

Wird ausgegeben, wenn eine neue Konversation erfolgreich abgeschlossen wurde.

Hinweis: Dieses Event wird ausgelöst, wenn die Konversation vom Conversations-Postfach als abgeschlossen markiert ist, und ist unabhängig vom Benutzer, der das Widget minimiert oder schließt.

 

Event-Payload
Feldname Datentyp Beschreibung
conversation Konversation Details zu der Konversation, die geschlossen wurde

 

Beispiel:
window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); });

unreadConversationCountChanged

Wird ausgegeben, wenn sich die Anzahl der Konversationen im Widget mit jeglichen ungelesenen Nachrichten ändert (Erhöhung oder Verringerung).

Event-Payload
Feldname Datentyp Beschreibung
unreadCount Zahl Die neue Summe an Konversationen im Widget mit allen ungelesenen Nachrichten

 

Beispiel:
window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });

contactAssociated

Wird ausgegeben, wenn der Besucher einem Kontakt im CRM zugeordnet ist. 

Event-Payload
Feldname Datentyp Beschreibung
message Zeichenfolge Eine Bestätigungsnachricht, dass der Besucher mit einem Kontakt verknüpft wurde
Beispiel:
window.HubSpotConversations.on('contactAssociated', payload => { console.log(payload.message); });

userInteractedWithWidget

Wird ausgegeben, sobald der Benutzer mit dem Widget interagiert (z. B. Klicken auf das Widget, um es zu öffnen, Schließen der ersten Begrüßungsnachricht usw.)

Event-Payload
Feldname Datentyp Beschreibung
message Zeichenfolge Eine Bestätigungsnachricht, dass der Benutzer mit dem Widget interagiert hat.
Beispiel:
window.HubSpotConversations.on(‘userInteractedWithWidget’, payload => { console.log(payload.message); });

widgetLoaded

Wird ausgegeben, wenn der Widget-IFrame geladen wurde.

Event-Payload
Feldname Datentyp Beschreibung
message Zeichenfolge Bestätigungsnachricht, dass der Widget-IFRAME geladen wurde.
Beispiel:
window.HubSpotConversations.on(‘widgetLoaded’, payload => { console.log(payload.message); });

quickReplyButtonClick

Wird ausgegeben, wenn der Benutzer in einer Bot-Konversation auf die Schnellantwort-Schaltfläche klickt

Event-Payload
Feldname Datentyp Beschreibung
value Array Enthält den Textinhalt der Schnellantwort-Schaltfläche, die angeklickt wurde.
Beispiel:
quick-reply-options-in-bot-conversation

Im obigen Beispiel-Screenshot enthält der Bot-Chatflow drei Schnellantwortoptionen, die dem Benutzer zur Auswahl stehen. Wenn der Benutzer „Mehr erfahren“ ausgewählt hat, lautet die resultierende Event-Payload wie folgt:

// Example event payload when a quick reply option is selected { "name": "QUICK_REPLIES", "multiSelect": false, "value": [ "Learn more" ] }
window.HubSpotConversations.on('quickReplyButtonClick', event => { console.log(`The text content of the clicked button is ${payload.value[0]}`); });

widgetClosed

Wird ausgegeben, wenn das Widget geschlossen wird.

Event-Payload
Feldname Datentyp Beschreibung
message Zeichenfolge Bestätigungsmeldung, dass das Widget geschlossen ist.
Beispiel:
window.HubSpotConversations.on('widgetClosed', event => { console.log(event); });

Event-Listener registrieren und entfernen

on

Registriert einen Event-Listener. Siehe Unterstützte Event-Typen

Beispiel:
window.HubSpotConversations.on('conversationStarted', payload => { console.log(payload); });

off

Entfernt einen Event-Listener. Siehe Unterstützte Event-Typen

Beispiel:
const handleEvent = eventPayload => console.log(eventPayload); window.HubSpotConversations.on('conversationStarted', handleEvent); /* ... */ window.HubSpotConversations.off('conversationStarted', handleEvent);

Datentypen

Die folgenden Angaben sind ein Verweis auf Datentypen, die häufig im JavaScript-SDK vorkommen.

Konversation
Feldname Datentyp Beschreibung
conversationId Zahl Die ID der Konversation
War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.