Referentie voor Klaviyo Customer Hub JavaScript API

Wat je leert

Hoe je Klaviyo Customer Hub — of losse Klaviyo-webchat — vanuit je eigen storefront-code kunt bedienen met de window.customerHubApi JavaScript-API. Je opent en sluit de ervaring, navigeert naar een specifiek scherm, verstuurt namens de shopper een chatbericht en luistert naar events zoals toevoegen aan winkelwagen.

Voordat je van start gaat

Je hebt nodig:

• Klaviyo Customer Hub is ingesteld en geladen op je storefront. Als je een headless of aangepaste storefront hebt, volg dan eerst Hoe je Klaviyo Customer Hub instelt met Headless Shopify — daarin lees je hoe je de onsite loader toevoegt die deze API beschikbaar maakt.
• Mogelijkheid om de code van je webshop te bewerken en te implementeren.

Wat de Klaviyo Customer Hub-API is

Wanneer Klaviyo Customer Hub – of de losse Klaviyo-webchat – op je webshop wordt geladen, voegt Klaviyo een kleine JavaScript-API toe aan het globale window -object als window.customerHubApi. Je kunt die gebruiken om de ervaring te openen, te sluiten en ermee te werken vanuit je eigen code – bijvoorbeeld vanuit een aangepaste knop, banner of productpagina.

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

Methoden

open(route?)

Opent de lade van Klaviyo Customer Hub.

• route (string, optioneel) — een pad om naartoe te navigeren bij het openen. Als je dit weglaat, opent de Hub op het scherm dat het als laatste liet zien.

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

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

Beschikbare routes

close()

Sluit de Klaviyo Customer Hub-lade. De Hub blijft op het huidige scherm staan, dus opnieuw openen met open() (geen route) brengt de klant terug naar waar ze waren gebleven.

window.customerHubApi.close();

sendChatMessage(message)

Opent de Klaviyo Customer Hub in het chatscherm en verzendt een bericht namens de klant. Dit is handig voor de knoppen Chatten over dit product of Hulp vragen.

• message (string) — het bericht dat je moet verzenden.

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

Wanneer inloggen vereist is: Als je webshop klanten vraagt om in te loggen voordat ze kunnen chatten (en de AI-agent niet is ingeschakeld), wordt de klant naar het chatscherm gebracht waar ze eerst moeten inloggen. Het bericht wordt tijdelijk opgeslagen en automatisch verzonden zodra de klant is ingelogd. Het opgeslagen bericht verloopt na ongeveer 10 minuten als het inloggen niet is voltooid.

sendConversationContext(context)

Zet achtergrondcontext die buiten het chatgesprek is verzameld – zoals antwoorden uit een enquête vóór de chat – in de wachtrij om mee te sturen met het volgende chatbericht van de klant. Klaviyo slaat deze context vervolgens op en gebruikt deze als referentie voor de rest van dat gesprek.

• context (object) — een survey-response-object dat een entries -array bevat. Elke vermelding moet een question en een answer bevatten.

window.customerHubApi.sendConversationContext({
  type: 'survey-response',
  entries: [
    { question: 'What color are you interested in?', answer: 'Red' },
  ],
});

getActiveConversationId()

Retourneert de conversationId voor het actieve gesprek dat in de lade plaatsvindt. Retourneert null als er geen gesprek gaande is.

window.customerHubApi.getActiveConversationId();

Gebeurtenissen bekijken

window.customerHubApi.events laat je aanmelden voor gebeurtenissen die plaatsvinden in Klaviyo Customer Hub.

addtocart

Gaat af wanneer klanten een product toevoegen aan hun winkelwagen vanuit de Hub. Gebruik het om de winkelwagen van je webshop gesynchroniseerd te houden.

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

Volledig voorbeeld

Een knop Chatten over dit product die de Hub opent en een bericht verzendt, plus een listener die de winkelwagen van de webshop synchroniseert wanneer een shopper een artikel vanuit de Hub toevoegt:

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

Extra hulpbronnen