Guide de l’API JavaScript du Customer Hub

Objectif de cet article

Comment contrôler Klaviyo Customer Hub — ou le chat web autonome de Klaviyo — depuis le code de votre propre vitrine à l’aide de l’API JavaScript window.customerHubApi. Vous ouvrirez et fermerez l’expérience, accéderez à un écran spécifique, enverrez un message de chat au nom du client, et écouterez des événements comme l’ajout au panier.

Avant de commencer

Vous aurez besoin des éléments suivants :

• Klaviyo Customer Hub est configuré et chargé sur votre vitrine. Si vous utilisez une vitrine headless ou personnalisée, suivez d’abord Comment configurer Klaviyo Customer Hub avec Shopify headless — cela explique comment ajouter le chargeur sur site qui rend cette API disponible.
• Possibilité de modifier et de déployer votre code de vitrine.

Définition Customer Hub API

Chaque fois que Klaviyo Customer Hub — ou le chat web Klaviyo autonome — se charge sur votre vitrine, Klaviyo associe une petite API JavaScript à l’objet global window en tant que window.customerHubApi. Vous pouvez l’utiliser pour ouvrir, fermer et interagir avec l’expérience depuis votre propre code — par exemple, depuis un bouton personnalisé, une bannière ou une page produit.

if (window.customerHubApi) {
  window.customerHubApi.open();
}

des méthodes

open(route?)

Ouvre le tiroir du Customer Hub.

• route (chaîne, facultatif) — un chemin vers lequel naviguer lors de l’ouverture. Si cet élément est omis, le Hub s’ouvre sur l’écran qu’il affichait en dernier.

// Open the Hub on its default screen
window.customerHubApi.open();

// Open the Hub directly to a specific screen
window.customerHubApi.open('/orders');

Itinéraires disponibles

close()

Ferme le tiroir Klaviyo Customer Hub. Le Hub reste sur l’écran actuel ; ainsi, une réouverture avec open() (sans itinéraire) renvoie le client à l’endroit où il s’était arrêté.

window.customerHubApi.close();

sendChatMessage(message)

Ouvre le Customer Hub sur l’écran de chat et envoie un message au nom du client, utile pour les boutons « Discuter de ce produit » ou « Obtenir de l’aide ».

• message (string) — le message à envoyer.

window.customerHubApi.sendChatMessage('I have a question about my order.');

Lorsque la connexion est requise : si votre boutique exige que les clients se connectent avant de chatter (et que AI Agent n’est pas activé), le client est dirigé vers l’écran Chat pour se connecter en premier. Le message est enregistré temporairement et envoyé automatiquement une fois la connexion terminée. Le message enregistré expire après environ 10 minutes si la connexion n’est pas terminée.

getActiveConversationId()

Renvoie le conversationId de la conversation active se déroulant dans le tiroir. Renvoie null si aucune conversation n’est en cours.

window.customerHubApi.getActiveConversationId();

Écoutez les événements

window.customerHubApi.events vous permet de vous abonner aux événements qui se produisent dans Klaviyo Customer Hub.

addtocart

Se déclenche lorsqu’un client ajoute un produit à son panier à partir du Hub. Utilisez-le pour synchroniser votre panier vitrine.

window.customerHubApi.events.addEventListener('addtocart', (event) => {
  // event.detail.items is an array of { variantId, quantity }
  event.detail.items.forEach((item) => {
    console.log('Added to cart:', item.variantId, 'x', item.quantity);
  });
});

Exemple complet

Bouton « Discuter de ce produit » qui ouvre le Hub et envoie un message, ainsi qu’un écouteur qui synchronise le panier vitrine lorsqu’un acheteur ajoute un article à partir du Hub :

<button id="ask-about-product">Ask us about this product</button>

<script>
  document
    .getElementById('ask-about-product')
    .addEventListener('click', () => {
      if (window.customerHubApi) {
        window.customerHubApi.sendChatMessage(
          'I have a question about this product.'
        );
      }
    });

  // Sync the storefront cart when a customer adds an item from the Hub
  if (window.customerHubApi) {
    window.customerHubApi.events.addEventListener('addtocart', (event) => {
      refreshStorefrontCart(event.detail.items);
    });
  }
</script>

Ressources supplémentaires