Kit de développement logiciel pour les conversations

Pour discuter avec des clients et des leads sur votre site Web à l'aide de la boîte de réception conversation de HubSpot, vous pouvez configurer un widget de chat en direct. Grâce au Kit de développement logiciel (SDK) pour les conversations, vous pouvez offrir une expérience plus personnalisée pour les visiteurs en adaptant le comportement du widget de chat.

À un niveau élevé, le SDK pour les conversations vous permet de faire ce qui suit :

Initialisation

L'API est hébergée dans l'objet window.HubSpotConversations, qui donne accès à toutes les méthodes disponibles. L'objet est créé par le code de suivi HubSpot, mais il peut ne pas être disponible immédiatement lors du chargement de la page. Pour reporter l'accès à l'API jusqu'à son initialisation, vous pouvez utiliser l'assistant window.hsConversationsOnReady.

window.hsConversationsOnReady est un champ facultatif 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. Ce champ prend un tableau de fonctions à exécuter une fois l'API initialisée.

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

Configurer les paramètres des conversations

hsConversationsSettings

Cet objet facultatif vous permet de fournir des options de configuration au widget avant son initialisation.

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.

Style d'intégration en ligne

Lorsque le widget est intégré à un emplacement spécifique à l'aide de inlineEmbedSelector, plusieurs éléments DOM sont ajoutés et peuvent être stylisés (par exemple, hauteur, largeur, bordure). 

Par exemple, si vous intégrez le widget de chat à l'aide du sélecteur #some-id, il sera chargé avec les conteneurs et les ID suivants :

<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 });
Champ Type Par défaut Description
widgetOpen Booléen false Indique si le widget doit être chargé avec le statut ouvert.

widget.refresh

La méthode widget.refresh gère l'actualisation et la restitution des informations du widget, en fonction de l'URL de la page actuelle. Cette méthode peut être utile pour les widgets de chat intégrés dans des applications d'une seule page lorsque vous devez actualiser le widget selon les modifications des chemins. Cette méthode vous permet également de spécifier différents widgets de chat sur différents chemins de page.

Si vous appelez widget.refresh sur un chemin où il n'y a pas de widget de chat et que l'utilisateur n'est pas engagé dans une conversation, le widget sera supprimé. Cela ne supprimera pas le widget s'il y a un chat actuellement actif.

Cette méthode est limitée à un appel par seconde.

window.HubSpotConversations.widget.refresh(); /* ... */ // Force the widget to open to a specific chat flow window.HubSpotConversations.widget.refresh({ openToNewThread: true });
Champ Type Par défaut Description
openToNewThread Booléen false Indique s'il convient de forcer la création d'un nouveau fil. 

Exemple

En utilisant cette méthode, vous pouvez créer des boutons et des liens pour ouvrir des chatflows spécifiques sur une page en ajoutant des paramètres de requête à l'URL de la page.

conversations-chat-widget-open-cropPar exemple, vous pouvez ajouter le code suivant à vos pages pour générer les boutons :

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

Ensuite, dans les paramètres cibles de chaque chat, vous paramétrez le chat pour qu'il s'affiche lorsque le paramètre de requête correspond à celui que vous avez défini dans votre code de bouton.
conversations-target-rule

widget.open

La méthode widget.open ouvre le widget s'il n'est pas déjà ouvert ou s'il n'est pas actuellement chargé.

window.HubSpotConversations.widget.open();

widget.close

La méthode widget.close ferme le widget s'il n'est pas déjà fermé.

window.HubSpotConversations.widget.close();

widget.remove

La méthode widget.remove supprime le widget de la page. Si le widget n'est pas présent sur la page, cette méthode ne fait rien. Le widget s'affichera à nouveau lors de l'actualisation de la page ou si widget.load est appelé.

window.HubSpotConversations.widget.remove();

widget.status

La méthode widget.status renvoie un objet contenant des propriétés liées au statut actuel du widget.

const status = window.HubSpotConversations.widget.status(); if (status.loaded) { window.HubSpotConversations.widget.refresh(); } else { window.HubSpotConversations.widget.load(); }
Champ Type Par défaut Description
loaded Booléen false Indique si l'iframe de widget est chargé ou non.

Effacer les cookies de chat

La méthode effacer supprime les cookies liés au widget de chat et le renvoie à son statut par défaut lors du chargement ultérieur.

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.

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 la Base de connaissances de HubSpot.

window.HubSpotConversations.clear();

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.

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

Événements de chat

Le widget de chat envoie différents événements auxquels vous pouvez participer et répondre tout au long de son cycle de vie. Ces événements incluent :

Pour enregistrer et supprimer des participants à un événement, utilisez activer et désactiver, comme indiqué ci-dessous.

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

En savoir plus sur chaque événement ci-dessous.

conversationStarted

L'événement conversationStarted se déclenche lorsqu'une nouvelle conversation est correctement démarrée.

window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); });
Champ Type Description
conversation ID de fil L'ID de fil de la conversation qui a été démarrée. Vous pouvez utiliser cet ID lorsque vous effectuez des appels vers l'API conversations.

conversationClosed

L'événement conversationClosed se déclenche lorsqu'une nouvelle conversation est marquée comme fermée à partir de la boîte de réception conversations.

Les visiteurs du site qui réduisent ou ferment le widget de chat ne déclencheront pas cet événement. Pour cet événement, utilisez widgetClosed à la place.

window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); });
Champ Type Description
conversation ID de fil L'ID de fil de la conversation qui a été démarrée. Vous pouvez utiliser cet ID lorsque vous effectuez des appels vers l'API conversations.

unreadConversationCountChanged

L'événement unreadConversationCountChanged est déclenché lorsque le nombre de conversations avec des messages non lus augmente ou diminue.

window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });
Champ Type Description
unreadCount Nombre Le nombre total de conversations avec au moins un message non lu.

 

contactAssociated

L'événement contactAssociated est déclenché lorsque le visiteur est associé à un contact dans le CRM.

window.HubSpotConversations.on('contactAssociated', payload => { console.log(payload.message); });
Champ Type Description
message Chaîne Un message de confirmation indiquant que le visiteur est associé à un contact.

userInteractedWithWidget

L'événement userInteractedWithWidget est déclenché lorsque le visiteur interagit avec le widget, par exemple en cliquant pour ouvrir le widget ou en fermant le message de bienvenue initial.

window.HubSpotConversations.on(‘userInteractedWithWidget’, payload => { console.log(payload.message); });
Champ Type Description
message Chaîne Un message de confirmation indiquant que le visiteur a interagi avec le widget.

widgetLoaded

L'événement widgetLoaded est déclenché lorsque l'iframe du widget est chargé.

window.HubSpotConversations.on(‘widgetLoaded’, payload => { console.log(payload.message); });
Champ Type Description
message Chaîne Message de confirmation indiquant que l'iframe du widget est chargé.

quickReplyButtonClick

L'événement quickReplyButtonClick est déclenché lorsque le visiteur clique sur une réponse rapide dans une conversation de bot.

Champ Type Description
Valeur Tableau Un tableau contenant le texte de l'option de réponse rapide qui a été sélectionnée.
window.HubSpotConversations.on('quickReplyButtonClick', event => { console.log(`The text content of the clicked button is ${payload.value[0]}`); });

quick-reply-options-in-bot-conversation

Dans l'exemple de capture d'écran ci-dessus, le chatflow du bot contient trois options de réponse rapide. Si l'utilisateur sélectionne En savoir plus, la charge utile de l'événement résultant sera :

// Example event payload when a quick reply option is selected { "name": "QUICK_REPLIES", "multiSelect": false, "value": [ "Learn more" ] }

widgetClosed

L'événement widgetClosed est déclenché lorsque le visiteur ferme le widget de chat.

window.HubSpotConversations.on('widgetClosed', event => { console.log(event); });
Champ Type Description
message Chaîne Un message de confirmation indiquant que le visiteur a fermé le widget de chat.
Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.