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 :

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 :

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

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 :

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

hsConversationsSettings

Cet objet vous permet de fournir des options de configuration au widget avant son initialisation. L'utilisation de cet objet est facultative.

Champs
Nom du champ Type de données Par défaut  Description

loadImmediately

 

 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 partir


Notez 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.
 
window.hsConversationsSettings = { loadImmediately: false, inlineEmbedSelector: '#some-id', enableWidgetCookieBanner: true, disableAttachment: true }; window.hsConversationsOnReady = [ () => { window.HubSpotConversations.widget.load(); }, ];

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 :

livechat_before

 

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

livechat_after

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.
 
window.HubSpotConversations.widget.load(); /* ... */ // Force the widget to load in an open state window.HubSpotConversations.widget.load({ widgetOpen: true });

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 :
window.HubSpotConversations.widget.refresh(); /* ... */ // Force the widget to open to a specific chat flow window.HubSpotConversations.widget.refresh({ openToNewThread: true });

Remarque : widget.refresh ne supprimera pas les conversations existantes qu'un visiteur a démarrées dans le widget.

 

widget.open

Ouvrez le widget. Si le widget est déjà ouvert ou n'est actuellement pas chargé, il s'agit d'une non-opération.

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

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 :
window.HubSpotConversations.widget.close();

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 :
window.HubSpotConversations.widget.remove();

widget.status

Renvoie un objet contenant des propriétés liées au statut du widget.

Nom du champ Type de données Par défaut Description
loaded Booléen false Indique si l'iFrame de widget est chargé ou non.

 

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

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

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

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 :
window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); });

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 :
window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); });

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 :
window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });

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 :
window.HubSpotConversations.on('contactAssociated', payload => { console.log(payload.message); });

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 :
window.HubSpotConversations.on(‘userInteractedWithWidget’, payload => { console.log(payload.message); });

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 :
window.HubSpotConversations.on(‘widgetLoaded’, payload => { console.log(payload.message); });

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 :
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 que l'utilisateur peut sélectionner. 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" ] }
window.HubSpotConversations.on('quickReplyButtonClick', event => { console.log(`The text content of the clicked button is ${payload.value[0]}`); });

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 :
window.HubSpotConversations.on('widgetClosed', event => { console.log(event); });

Enregistrer et supprimer des participants à un événement

on

Inscrivez un participant à un événement. Découvrez les types d'événement pris en charge.

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

off

Supprimez un participant à un événement. Découvrez les types d'événement pris en charge.

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

Types de données

Voici une référence aux types de données communs avec le kit de développement logiciel de JavaScript.

Conversation
Nom du champ Type de données Description
conversationId Nombre L'ID de la conversation.
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é.