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 des conversations 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 général, le SDK pour les conversations vous permet d'exécuter les actions suivantes :

Configurer les paramètres du widget de chat
gérer le comportement du widget
Effacer les cookies de chat
Participer et répondre aux événements de widgets

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>

 
<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();
  },
];

xxxxxxxxxx
 
window.hsConversationsSettings = {
  loadImmediately: false,
  inlineEmbedSelector: '#some-id',
  enableWidgetCookieBanner: true,
  disableAttachment: true,
};
window.hsConversationsOnReady = [
  () => {
    window.HubSpotConversations.widget.load();
  },
];

Champ	Type	Par défaut	Description
`loadImmediately`	Booléen	`true`	Si le widget doit se charger implicitement ou attendre que la méthode `widget.load` soit appelée.
`inlineEmbedSelector`	Chaîne	`""`	Spécifiez un sélecteur (`#some-id`) pour intégrer le widget de chat à un endroit spécifique de la page. Le widget sera intégré en ligne dans ce nœud DOM et restera ouvert jusqu'à ce qu'il soit supprimé à l'aide de `widget.remove`. En savoir plus sur le style des widgets de chat intégrés.
`enableWidgetCookieBanner`	Énumération	`false`	Contrôlez le comportement de la bannière de cookies pour tous les widgets sur la page. Les options sont les suivantes : `false` (par défaut) : utilise les paramètres du widget de chat. `true` : présente des bannières de cookies lorsque le widget est chargé. `ON_WIDGET_LOAD` : identique à `true`. `ON_EXIT_INTENT` : active les bannières de cookies lorsque l'utilisateur manifeste une intention de sortie.
`disableAttachment`	Booléen	`false`	Indique s'il faut masquer le bouton de téléchargement des pièces jointes 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.
`avoidInlineStyles`	Booléen	`false`	Lorsqu'il est défini sur `true`, ajoute une balise de lien avec un CSS extérieur au lieu d'une insertion dynamique directe d'une balise de style.
`hideNewThreadLink`	Booléen	`false`	Lorsqu'il est défini sur `true`, le lien Pour démarrer une nouvelle conversation, cliquez ici n'apparaît pas sous le texte Votre discussion est terminée lorsqu'une discussion est terminée.

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>

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

Vous pouvez ensuite personnaliser le widget de chat à l'aide de ces sélecteurs, par exemple :

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

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

livechat_after

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, notamment :

widget.load
widget.refresh
widget.open
widget.close
widget.remove
widget.status

Découvrez-en davantage ci-dessous sur chaque méthode.

La méthode widget.load gère le chargement initial de la page. Cette méthode est uniquement nécessaire si vous définissez l'indicateur loadImmediately sur false. Autrement, le widget se chargera automatiquement.

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

window.HubSpotConversations.widget.load();

/* ... */

// Force the widget to load in an open state
window.HubSpotConversations.widget.load({ widgetOpen: true });

​x
 
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.

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

xxxxxxxxxx
 
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-crop Par 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>

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

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();

xxxxxxxxxx
 
window.HubSpotConversations.widget.open();

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

window.HubSpotConversations.widget.close();

xxxxxxxxxx
 
window.HubSpotConversations.widget.close();

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();

xxxxxxxxxx
 
window.HubSpotConversations.widget.remove();

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

xxxxxxxxxx
 
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 clear 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 :

Référencement de conversations historiques.
Maintien de l'état d'ouverture du widget de chat lors des chargements de pages.
Maintien de l'état d'ouverture du message de bienvenue lors du chargement des pages.

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();

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

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

conversationStarted
conversationClosed
userSelectedThread
unreadConversationCountChanged
contactAssociated
userInteractedWithWidget
widgetLoaded
quickReplyButtonClick
widgetClosed

Pour enregistrer et supprimer des participants à un événement, utilisez on et off, comme indiqué ci-dessous.

const handleEvent = (eventPayload) => console.log(eventPayload);

window.HubSpotConversations.on('conversationStarted', handleEvent);

/* ... */

window.HubSpotConversations.off('conversationStarted', handleEvent);

xxxxxxxxxx
 
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}`
  );
});

xxxxxxxxxx
 
window.HubSpotConversations.on('conversationStarted', (payload) => {
  console.log(
    `Started conversation with id ${payload.conversation.conversationId}`
  );
});

Champ	Type	Description
`payload.conversation.conversationId`	Nombre	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 plutôt widgetClosed.

window.HubSpotConversations.on('conversationClosed', (payload) => {
  console.log(
    `Conversation with id ${payload.conversation.conversationId} has been closed!`
  );
});

xxxxxxxxxx
 
window.HubSpotConversations.on('conversationClosed', (payload) => {
  console.log(
    `Conversation with id ${payload.conversation.conversationId} has been closed!`
  );
});

Champ	Type	Description
`payload.conversation.conversationId`	Nombre	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.

userSelectedThread

L'événement userSelectedThread se déclenche lors de la création d'un fil ou de la sélection d'un fil existant.

window.HubSpotConversations.on('userSelectedThread', (payload) => {
  console.log(
    `User selected thread with ID ${payload.conversation.conversationId}!`
  );
});

xxxxxxxxxx
 
window.HubSpotConversations.on('userSelectedThread', (payload) => {
  console.log(
    `User selected thread with ID ${payload.conversation.conversationId}!`
  );
});

Champ	Type	Description
`payload.conversation.conversationId`	Nombre	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}!`);
});

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

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

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

xxxxxxxxxx
 
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
`value`	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]}`);
});

xxxxxxxxxx
 
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"]
}

xxxxxxxxxx
 
// 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);
});

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

Kit de développement logiciel pour les conversations

Initialisation

Configurer les paramètres des conversations

Style d'intégration en ligne

Comportement du widget

widget.load

widget.refresh