Kit de développement logiciel pour les conversations
Le widget de chat en direct de HubSpot vous permet de discuter avec vos clients et leads sur votre propre site web. Grâce au kit de développement logiciel pour widget de chat, vous pouvez offrir une expérience plus personnalisée pour les visiteurs en adaptant le comportement du widget de chat.
Cas d'utilisation : le kit de développement logiciel pour widget de chat peut être utilisé pour personnaliser le moment auquel le widget de chat de HubSpot apparaît sur votre site web ainsi que son apparence.
À un niveau élevé, il vous permet de :
- gérer le comportement du widget ;
- participer et répondre aux événements dans le widget ;
- interroger pour comprendre l'état du widget.
Premiers pas
L'API est hébergée dans l'objet window.HubSpotConversations
. Toutes les méthodes disponibles peuvent être consultées via cet objet. Le chargeur de scripts HubSpot (ou code de suivi HubSpot) sur votre page créera cet objet pour vous, mais il ne pourra pas être immédiatement disponible. Pour reporter l'accès à l'API jusqu'à son initialisation, vous pouvez utiliser l'assistant window.hsConversationsOnReady
. Voici un exemple simple :
Référence pour le kit de développement logiciel
window.hsConversationsOnReady
Il s'agit d'un champ spécial que vous pouvez définir sur l'objet window
qui vous permet de spécifier le code à exécuter dès que le widget est disponible. L'utilisation de cette propriété est facultative. Si tel est le cas, ce champ doit être défini sur un tableau de fonctions. Une fois que l'API a été initialisée, elle vérifiera l'existence de ce tableau et exécutera ses fonctions en série. Par exemple :
hsConversationsSettings
Cet objet vous permet de fournir des options de configuration au widget avant son initialisation. L'utilisation de cet objet est facultative.
Nom du champ | Type de données | Par défaut | Description |
---|---|---|---|
|
Booléen | true | Indique si le widget se charge de manière implicite ou patiente jusqu'à ce que la méthode widget.load soit appelée. |
inlineEmbedSelector |
Chaîne | "" | Indique si le widget doit être intégré à la page. Si un sélecteur (par exemple, #some-id) est fourni, le widget sera intégré en ligne dans ce nœud DOM. Il sera toujours ouvert jusqu'à ce qu'il soit supprimé via widget.remove . |
enableWidgetCookieBanner |
Énumération | false | Contrôlez le comportement de la bannière de cookies pour tous les chatflows sur la page :false - Utilisez le paramètre à partir des chatflows (par défaut)true - Autorisez la bannière de cookies lorsque le widget est chargéON_WIDGET_LOAD (identique à true) - Autorisez la bannière de cookies lorsque le widget est chargéON_EXIT_INTENT - Autorisez la bannière de cookies lorsque l'utilisateur démontre une intention de partirNotez que ce champ est utilisé pour être un Boolean . Il peut désormais être adapté aux valeurs Boolean initiales et aux valeurs enum mises à jour. |
disableAttachment |
Booléen | false | Indique si le bouton de chargement de pièce jointe est masqué ou non dans le widget de chat. |
disableInitialInputFocus |
Booléen | false | Détermine s'il faut empêcher automatiquement la mise au point sur le champ de saisie du widget après le chargement initial d'un widget intégré en ligne sur une page. |
Style d'intégration en ligne
window.hsConversationsOnReady
Si le widget est intégré à un endroit spécifié par le client, plusieurs éléments DOM sont ajoutés et peuvent être stylisés pour répondre aux exigences de personnalisation du client (par exemple, hauteur, largeur, bordure). Notez que cette structure s'applique uniquement si vous utilisez l'option inlineEmbedSelector
.
<�div� �id�=�"hubspot-conversations-inline-parent"�>
<�iframe� �id�=�"hubspot-conversations-inline-iframe"� />
</�div�>
Par exemple, le widget de chat peut ressembler à ceci par défaut :
Cette mise en page n'est pas idéale. Vous pouvez personnaliser le widget en incluant des styles tels que :
#hubspot-conversations-inline-iframe {
width: 300px;
height: 500px;
border:none;
}
Cela offre une expérience utilisateur bien plus conviviale.
HubSpotConversations.widget
L'objet du widget contient un certain nombre de méthodes qui vous permettent de manipuler le widget de chat sur votre page.
widget.load
Chargez le widget pour la première fois sur la page. Si le widget est actuellement chargé, les appels suivants de cette méthode sont des non-opérations.
Cette méthode est uniquement nécessaire si vous définissez l'indicateur loadImmediately
sur false
. Autrement, le widget se chargera automatiquement.
Remarque : widget.load
est limité à un appel par seconde.
Paramètres :
Nom du champ | Type de données ? | Par défaut | Description |
---|---|---|---|
widgetOpen |
Booléen | false | Indique si le widget doit être chargé avec le statut ouvert. |
widget.refresh
Actualisez et restituez à nouveau les informations du widget, en fonction de l'URL de la page actuelle.
Si vous hébergez le widget de chat sur une application à page unique, cette méthode peut être utile pour actualiser le widget selon les modifications des chemins. Cela vous permet de spécifier différents chatflows sur différents chemins de page. Si widget.refresh
est appelé sur un chemin où il n'y a aucun chatflow et que l'utilisateur n'est pas engagé dans une conversation, le widget sera supprimé.
Remarque : widget.refresh
est limité à un appel par seconde.
Paramètres :
Nom du champ | Type de données ? | Par défaut | Description |
---|---|---|---|
openToNewThread |
Booléen | false | Indique s'il convient de forcer la création d'un nouveau fil. |
Pour un exemple d'utilisation du champ openToNewThread
, consultez Ouvrir un chatflow spécifique.
Exemple :
widget.close
Fermez le widget. Si le widget est déjà fermé ou n'est actuellement pas chargé, il s'agit d'une non-opération.
Exemple :
widget.remove
Supprimez le widget de la page. Si le widget n'est pas présent sur la page, il s'agit d'une non-opération. Pour afficher à nouveau le widget, une actualisation complète de la page doit être effectuée ou widget.load
peut être utilisé.
Exemple :
clear
Le widget de chat crée plusieurs cookies pour préserver son statut à travers les visites et les actualisations. Ces cookies sont étendus au domaine de la page hébergeant le widget et sont utilisés pour prendre en charge les fonctionnalités suivantes :
- mentionner des conversations historiques ;
- rendre le statut ouvert du widget de chat persistant à travers les chargements de page ;
- rendre le statut ouvert du message de bienvenue persistant à travers les chargements de page.
La méthode clear
peut être utilisée pour supprimer ces cookies, redirigeant le widget vers son statut par défaut lors des chargements ultérieurs.
Les cookies suivants sont effacés avec cette méthode :
messagesUtk
hs-messages-is-open
hs-messages-hide-welcome-message
Pour plus d'informations sur ces cookies, consultez cet article de base de connaissances.
Exemple :
Vous pouvez également transmettre {resetWidget:true}
à la fonction clear()
pour effacer tous les cookies associés aux chats, supprimer le widget de la page et créer une nouvelle instance du widget de chat.
Exemple :
Event specification
Le widget de chat enverra différents événements auxquels vous pouvez participer et répondre tout au long du cycle de vie.
Événements pris en charge
conversationStarted
Envoyé lorsqu'une nouvelle conversation est correctement démarrée.
Charge utile d'événement
Nom du champ | Type de données | Description |
---|---|---|
conversation |
Conversation | Détails de la conversation démarrée |
Exemple :
conversationClosed
Envoyé lorsqu'une nouvelle conversation est correctement fermée.
Remarque : Cet événement se déclenche lorsque la conversation est marquée comme fermée depuis la boîte de réception des conversations et qu'elle n'est pas associée à l'utilisateur qui réduit ou ferme le widget de chat.
Charge utile d'événement
Nom du champ | Type de données | Description |
---|---|---|
conversation |
Conversation | Détails de la conversation fermée |
Exemple :
unreadConversationCountChanged
Envoyé lorsque le nombre de conversations dans le widget avec des messages non lus change (augmentation ou baisse).
Charge utile d'événement
Nom du champ | Type de données | Description |
---|---|---|
unreadCount |
Nombre | Le nouveau nombre total de conversations dans le widget avec des messages non lus. |
Exemple :
contactAssociated
Envoyé lorsque le visiteur est associé à un contact dans le CRM.
Charge utile d'événement
Nom du champ | Type de données | Description |
---|---|---|
message |
Chaîne | Un message de confirmation indiquant que le visiteur est associé à un contact. |
Exemple :
userInteractedWithWidget
Émis dès que l'utilisateur interagit avec le widget (par exemple, en cliquant sur le lanceur pour ouvrir le widget, en fermant le message de bienvenue initial, etc.).
Charge utile d'événement
Nom du champ | Type de données | Description |
---|---|---|
message |
Chaîne | Un message de confirmation indiquant que l'utilisateur a interagi avec le widget. |
Exemple :
widgetLoaded
Émis lorsque l'iFrame du widget est chargé.
Charge utile d'événement
Nom du champ | Type de données | Description |
---|---|---|
message |
Chaîne | Message de confirmation indiquant que l'iFrame du widget a été chargé. |
Exemple :
quickReplyButtonClick
Émis lorsque l'utilisateur clique sur le bouton de réponse rapide dans une conversation de bot.
Charge utile d'événement
Nom du champ | Type de données | Description |
---|---|---|
value |
Tableau | Contient le contenu textuel du bouton de réponse rapide sur lequel vous avez cliqué. |
Exemple :

Dans l'exemple de capture d'écran ci-dessus, le chatflow du bot contient trois options de réponse rapide que l'utilisateur peut sélectionner. Si l'utilisateur sélectionne En savoir plus, la charge utile de l'événement résultant sera :
widgetClosed
Émis lorsque le widget est fermé.
Charge utile d'événement
Nom du champ | Type de données | Description |
---|---|---|
message |
Chaîne | Message de confirmation indiquant que le widget est fermé. |
Exemple :
on
Inscrivez un participant à un événement. Découvrez les types d'événement pris en charge.
Exemple :
off
Supprimez un participant à un événement. Découvrez les types d'événement pris en charge.
Exemple :
Merci d'avoir partagé votre avis.