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:
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.hsConversationsOnReady
Hilfsfunktion 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.
hsConversationsSettings
Dieses optionale Objekt ermöglicht es Ihnen, vor dem Initialisieren einige Konfigurationsoptionen für das Widget anzugeben.
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:
|
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. |
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:
You can then customize the chat widget using those selectors, such as:
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.
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.
Feld | Typ | Standard | Beschreibung |
---|---|---|---|
widgetOpen |
Boolesch | false |
Ob das Widget in einem geöffneten Zustand geladen werden soll. |
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.
Feld | Typ | Standard | Beschreibung |
---|---|---|---|
openToNewThread |
Boolesch | false |
Ob das Erstellen eines neuen Threads erzwungen werden soll. |
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.
Sie könnten beispielsweise den folgenden Code zu Ihren Seiten hinzufügen, um die Schaltflächen zu generieren:
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.
Die widget.close
-Methode schließt das Widget, wenn es noch nicht geschlossen ist.
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.
Die widget.status
-Methode gibt ein Objekt zurück, das Eigenschaften enthält, die sich auf den aktuellen Status des Widgets beziehen.
Feld | Typ | Standard | Beschreibung |
---|---|---|---|
loaded |
Boolesch | false |
Ob der Widget-iframe geladen wurde oder nicht. |
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.
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.
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:
- conversationStarted
- conversationClosed
- unreadConversationCountChanged
- contactAssociated
- userInteractedWithWidget
- widgetLoaded
- quickReplyButtonClick
- widgetClosed
Um Event-Listener zu registrieren und zu entfernen, verwenden Sie on
und off
, wie unten gezeigt.
Erfahren Sie unten mehr über die einzelnen Events.
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. |
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.
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. |
Das unreadConversationCountChanged
-Event wird ausgelöst, wenn die Anzahl der Konversationen mit ungelesenen Nachrichten zunimmt oder abnimmt.
Feld | Typ | Beschreibung |
---|---|---|
unreadCount |
Zahl | Die Gesamtzahl der Konversationen mit mindestens einer ungelesenen Nachricht. |
Das contactAssociated
-Event wird ausgelöst, wenn der Besucher einem Kontakt im CRM zugeordnet ist.
Feld | Typ | Beschreibung |
---|---|---|
message |
Zeichenfolge | Eine Bestätigungsnachricht, dass der Besucher mit einem Kontakt verknüpft wurde. |
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.
Feld | Typ | Beschreibung |
---|---|---|
message |
Zeichenfolge | Eine Bestätigungsnachricht, dass der Besucher mit dem Widget interagiert hat. |
Das widgetLoaded
-Event wird ausgelöst, wenn der Widget-iframe geladen wird.
Feld | Typ | Beschreibung |
---|---|---|
message |
Zeichenfolge | Eine Bestätigungsnachricht, dass der Widget-iframe geladen wurde. |
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. |
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:
Das widgetClosed
-Event wird ausgelöst, wenn der Besucher das Chat-Widget schließt.
Feld | Typ | Beschreibung |
---|---|---|
message |
Zeichenfolge | Eine Bestätigungsnachricht, dass der Besucher das Chat-Widget geschlossen hat. |
Vielen Dank, dass Sie Ihr Feedback mit uns geteilt haben.