Konversationen-SDK

Um über das Konversationen-Postfach von HubSpot mit Kunden und Leads auf Ihrer Website zu chatten, können Sie ein Livechat-Widget einrichten. Mit dem Konversationen-SDK können Sie Besuchern ein individuelleres Erlebnis bieten, indem Sie das Verhalten des Chat-Widgets anpassen.

Auf einer allgemeinen Ebene ermöglicht Ihnen das Konversationen-SDK Folgendes:

Initialisierung

Die API befindet sich im window.HubSpotConversations-Objekt, das Zugriff auf alle verfügbaren Methoden bietet. Das Objekt wird durch den HubSpot-Tracking-Code erstellt, ist jedoch möglicherweise beim Laden der Seite nicht sofort verfügbar. Um den Zugriff auf die API zu verzögern, bis sie initialisiert ist, können Sie die window.hsConversationsOnReadyHilfsfunktion verwenden.

window.hsConversationsOnReady ist ein optionales 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. Dieses Feld übernimmt eine Array-Funktion, die ausgeführt wird, sobald die API initialisiert wurde.

<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>

Einstellungen für Konversationen konfigurieren

hsConversationsSettings

Dieses optionale Objekt ermöglicht es Ihnen, vor dem Initialisieren einige Konfigurationsoptionen für das Widget anzugeben.

window.hsConversationsSettings = { loadImmediately: false, inlineEmbedSelector: '#some-id', enableWidgetCookieBanner: true, disableAttachment: true }; window.hsConversationsOnReady = [ () => { window.HubSpotConversations.widget.load(); }, ];
Field Type Default Description
loadImmediately Boolean true Whether the widget should implicitly load or wait until the widget.load method is called.
inlineEmbedSelector String "" Specify a selector  (#some-id) to embed the chat widget in a specific location on the page. Widget will be embedded inline within that DOM node and will remain open until it is removed with widget.remove. Learn more about styling embedded chat widgets.
enableWidgetCookieBanner Enumeration false Control behavior of the cookie banner for all chat widgets on the page. Options include:
  • false (default): uses the chat widget's settings.
  • true: presents cookie banners when the widget is loaded.
  • ON_WIDGET_LOAD: same as true.
  • ON_EXIT_INTENT: enable cookie banners when the user exhibits an exit intent.
disableAttachment Boolean false Whether to hide the upload attachment button in the chat widget.
disableInitialInputFocus Boolean false Whether to automatically prevent focusing on the widget's input field after an inline embedded widget is initially loaded.

Inline-Einbettungsstile

Wenn das Widget mit inlineEmbedSelector an einer bestimmten Stelle eingebettet wird, werden mehrere DOM-Elemente hinzugefügt, die formatiert werden können (z. B. Höhe, Breite, Rahmen). 

Wenn Sie beispielsweise das Chat-Widget mit dem #some-id-Selektor einbetten, wird es mit den folgenden Containern und IDs geladen:

<div id="some-id"> <div id="hubspot-conversations-inline-parent"> <iframe id="hubspot-conversations-inline-iframe"> <!-- rest of iframe content --> </iframe> </div> </div>

You can then customize the chat widget using those selectors, such as:

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

livechat_after

 

Widget behavior

HubSpotConversations.widget

The widget object contains a number of methods that allow you to manipulate the chat widget on your page, including:

Below, learn more about each method.

widget.load

The widget.load method handles the initial load on the page. This method is only necessary if you set loadImmediately to false. Otherwise, the widget will load itself automatically.

This method is throttled to one call per second.

window.HubSpotConversations.widget.load(); /* ... */ // Force the widget to load in an open state window.HubSpotConversations.widget.load({ widgetOpen: true });
Feld Typ Standard Beschreibung
widgetOpen Boolesch false Ob das Widget in einem geöffneten Zustand geladen werden soll.

widget.refresh

Die widget.refresh-Methode übernimmt unter Berücksichtigung der aktuellen Seiten-URL das Aktualisieren und erneute Darstellen der Informationen des Widgets. Diese Methode kann für Chat-Widgets nützlich sein, die in Einzelseitenanwendungen eingebettet sind, wenn Sie das Widget bei Routenänderungen aktualisieren müssen. Mit dieser Methode können Sie auch verschiedene Chat-Widgets auf verschiedenen Seitenrouten angeben.

Wenn Sie widget.refresh auf einer Route aufrufen, auf der kein Chat-Widget vorhanden ist und der Benutzer keinen Chat führt, wird das Widget entfernt. Das Widget wird nicht entfernt, wenn ein derzeit aktiver Chat vorhanden ist.

Diese Methode wird auf einen Aufruf pro Sekunde gedrosselt.

window.HubSpotConversations.widget.refresh(); /* ... */ // Force the widget to open to a specific chat flow window.HubSpotConversations.widget.refresh({ openToNewThread: true });
Feld Typ Standard Beschreibung
openToNewThread Boolesch false Ob das Erstellen eines neuen Threads erzwungen werden soll. 

Beispiel

Mit dieser Methode können Sie Schaltflächen und Links zum Öffnen bestimmter Chatflows auf einer Seite erstellen, indem Sie der Seiten-URL Abfrageparameter hinzufügen.

conversations-chat-widget-open-cropSie könnten beispielsweise den folgenden Code zu Ihren Seiten hinzufügen, um die Schaltflächen zu generieren:

<div class="chat-buttons"> <button onclick="window.history.pushState({}, 'talk_to_sales', '?sales_chat=true'); window.HubSpotConversations.widget.refresh({openToNewThread: true});">Talk to sales</button> <button onclick="window.history.pushState({}, 'talk_to_customer_support', '?cs_chat=true'); window.HubSpotConversations.widget.refresh({openToNewThread: true});">Talk to customer support</button> <button onclick="window.history.pushState({}, 'talk_to_the_ceo', '?ceo_chat=true'); window.HubSpotConversations.widget.refresh({openToNewThread: true});">Talk to the CEO</button> </div>

In den Zieleinstellungen jedes Chats legen Sie dann fest, dass der Chat angezeigt wird, wenn der Abfrageparameter mit dem Parameter übereinstimmt, den Sie in Ihrem Schaltflächencode festgelegt haben.
conversations-target-rule

widget.open

Die widget.open-Methode öffnet das Widget, wenn es noch nicht geöffnet oder aktuell nicht geladen ist.

window.HubSpotConversations.widget.open();

widget.close

Die widget.close-Methode schließt das Widget, wenn es noch nicht geschlossen ist.

window.HubSpotConversations.widget.close();

widget.remove

Die widget.remove-Methode entfernt das Widget von der Seite. Wenn das Widget nicht auf der Seite vorhanden ist, bewirkt diese Methode nichts. Das Widget wird beim Aktualisieren der Seite oder beim Aufrufen von widget.load erneut angezeigt.

window.HubSpotConversations.widget.remove();

widget.status

Die widget.status-Methode gibt ein Objekt zurück, das Eigenschaften enthält, die sich auf den aktuellen Status des Widgets beziehen.

const status = window.HubSpotConversations.widget.status(); if (status.loaded) { window.HubSpotConversations.widget.refresh(); } else { window.HubSpotConversations.widget.load(); }
Feld Typ Standard Beschreibung
loaded Boolesch false Ob der Widget-iframe geladen wurde oder nicht.

Chat-Cookies löschen

Die clear-Methode löscht Cookies im Zusammenhang mit dem Chat-Widget und setzt es beim nachfolgenden Laden in seinen Standardzustand zurück.

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.
  • Aufrechterhalten des geöffneten Zustands des Chat-Widgets über das Laden von Seiten hinweg.
  • Aufrechterhalten des geöffneten Zustands der Willkommensnachricht über das Laden von Seiten hinweg.

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 der Wissensdatenbank von HubSpot.

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.

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

Chat-Events

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

Um Event-Listener zu registrieren und zu entfernen, verwenden Sie on und off, wie unten gezeigt.

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

Erfahren Sie unten mehr über die einzelnen Events.

conversationStarted

Das conversationStarted-Event wird ausgelöst, wenn eine neue Konversation erfolgreich gestartet wurde.

window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); });
Feld Typ Beschreibung
conversation Thread-ID Die Thread-ID der gestarteten Konversation. Sie können diese ID verwenden, wenn Sie Aufrufe an die Konversationen-API vornehmen.

conversationClosed

Das conversationClosed-Event wird ausgelöst, wenn eine neue Konversation vom Konversationen-Postfach als geschlossen markiert wurde.

Website-Besucher, die das Chat-Widget minimieren oder schließen, lösen dieses Event nicht aus. Verwenden Sie für dieses Event stattdessen widgetClosed.

window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); });
Feld Typ Beschreibung
conversation Thread-ID Die Thread-ID der gestarteten Konversation. Sie können diese ID verwenden, wenn Sie Aufrufe an die Konversationen-API vornehmen.

unreadConversationCountChanged

Das unreadConversationCountChanged-Event wird ausgelöst, wenn die Anzahl der Konversationen mit ungelesenen Nachrichten zunimmt oder abnimmt.

window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });
Feld Typ Beschreibung
unreadCount Zahl Die Gesamtzahl der Konversationen mit mindestens einer ungelesenen Nachricht.

 

contactAssociated

Das contactAssociated-Event wird ausgelöst, wenn der Besucher einem Kontakt im CRM zugeordnet ist.

window.HubSpotConversations.on('contactAssociated', payload => { console.log(payload.message); });
Feld Typ Beschreibung
message Zeichenfolge Eine Bestätigungsnachricht, dass der Besucher mit einem Kontakt verknüpft wurde.

userInteractedWithWidget

Das userInteractedWithWidget-Event wird ausgelöst, wenn der Besucher mit dem Widget interagiert, z. B. durch Klicken, um das Widget zu öffnen oder die erste Willkommensnachricht zu schließen.

window.HubSpotConversations.on(‘userInteractedWithWidget’, payload => { console.log(payload.message); });
Feld Typ Beschreibung
message Zeichenfolge Eine Bestätigungsnachricht, dass der Besucher mit dem Widget interagiert hat.

widgetLoaded

Das widgetLoaded-Event wird ausgelöst, wenn der Widget-iframe geladen wird.

window.HubSpotConversations.on(‘widgetLoaded’, payload => { console.log(payload.message); });
Feld Typ Beschreibung
message Zeichenfolge Eine Bestätigungsnachricht, dass der Widget-iframe geladen wurde.

quickReplyButtonClick

Das quickReplyButtonClick-Event wird ausgelöst, wenn der Besucher auf eine Schnellantwort in einer Bot-Konversation klickt.

Feld Typ Beschreibung
value Array Ein Array, das den Text der Schnellantwortoption enthält, auf die geklickt wurde.
window.HubSpotConversations.on('quickReplyButtonClick', event => { console.log(`The text content of the clicked button is ${payload.value[0]}`); });

quick-reply-options-in-bot-conversation

Im obigen Beispiel-Screenshot enthält der Bot-Chatflow drei Schnellantwortoptionen. Wenn der Benutzer Mehr erfahren auswählt, 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" ] }

widgetClosed

Das widgetClosed-Event wird ausgelöst, wenn der Besucher das Chat-Widget schließt.

window.HubSpotConversations.on('widgetClosed', event => { console.log(event); });
Feld Typ Beschreibung
message Zeichenfolge Eine Bestätigungsnachricht, dass der Besucher das Chat-Widget geschlossen hat.
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.