Referência da API JavaScript do Customer Hub

O que você vai aprender

Como controlar o Klaviyo Customer Hub — ou o chat web do Klaviyo independente — a partir do seu próprio código da loja usando a API JavaScript window.customerHubApi. Você vai abrir e fechar a experiência, navegar até uma tela específica, enviar uma mensagem no chat em nome do cliente e monitorar eventos como adicionar ao carrinho.

Antes de começar

Você precisará de:

• Klaviyo Customer Hub ou chat web independente do Klaviyo configurado e carregado na sua loja. Se você estiver usando uma vitrine headless da Shopify, siga primeiro Como configurar o Klaviyo Customer Hub com a Shopify Headless. Ela cobre a adição do carregador no site que disponibiliza essa API.
• Capacidade de editar e implementar o código da sua loja.

O que é a API do Customer Hub

Sempre que o Klaviyo Customer Hub — ou o chat web standalone da Klaviyo — é carregado na sua loja, a Klaviyo anexa uma pequena API JavaScript ao objeto global window como window.customerHubApi. Você pode usá-la para abrir, fechar e interagir com a experiência a partir do seu próprio código — por exemplo, a partir de um botão, banner ou página de produto personalizados.

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

Métodos

open(route?)

Abre a gaveta do Customer Hub.

• route (string, opcional) — um caminho para navegar ao abrir. Se omitido, o Hub abre na tela que estava sendo exibida por último.

// Open the Hub on its current screen (or its initial screen on first open)
window.customerHubApi.open();

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

Rotas disponíveis

close()

Fecha a gaveta do Klaviyo Customer Hub. O Hub permanece na tela atual; assim, ao reabrir com open() (sem rota), o cliente volta para onde parou.

window.customerHubApi.close();

sendChatMessage(message)

Abre o Klaviyo Customer Hub na tela Chat e envia uma mensagem em nome do cliente, o que é útil para botões como “Conversar sobre este produto” ou “Obter ajuda”. O chat web precisa estar visível para o comprador para que a mensagem seja enviada.

• message (string) — a mensagem a ser enviada.

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

Quando o login é obrigatório: se sua loja exige que os clientes façam login antes de conversar (e o AI Agent não estiver habilitado), o cliente é levado à tela do chat para fazer login primeiro. A mensagem é salva temporariamente e enviada automaticamente quando o usuário termina de fazer login. A mensagem salva expira após cerca de 10 minutos se o login não for concluído.

Limitações de dados do chat

A API JavaScript não inclui métodos para anexar respostas de pesquisa pré-chat nem recuperar o ID da conversa com atividade.

Escutar eventos

window.customerHubApi.events permite que você se inscreva em eventos que acontecem dentro do Klaviyo Customer Hub.

addtocart e addtocart_v2

Após uma adição ao carrinho bem-sucedida no Klaviyo Customer Hub, o addtocart é disparado quando a exibição do carrinho da sua vitrine ainda precisa ser atualizada. Atualize a exibição sem adicionar os itens novamente. No Shopify, em vez disso, o addtocart_v2 é disparado quando a Klaviyo já atualizou a contagem do carrinho do tema; a gaveta do carrinho do tema permanece fechada. Use o addtocart_v2 para rastreamento ou outras ações de acompanhamento sem repetir a atualização do carrinho.

window.customerHubApi.events.addEventListener('addtocart', (event) => {
  // The items are already in the cart. Refresh your storefront cart display.
  // event.detail.items is an array of { variantId, quantity }
  console.log('Cart display needs refreshing:', event.detail.items);
});

window.customerHubApi.events.addEventListener('addtocart_v2', (event) => {
  // Klaviyo has already updated the Shopify cart count.
  // Use this listener for tracking or other follow-up actions.
  console.log('Cart display updated:', event.detail.items);
});

Exemplo completo

Este exemplo habilita um botão “Conversar sobre este produto” e registra listeners do carrinho depois que a API é carregada. Antes de implantar, substitua o corpo de refreshStorefrontCart pelo código de atualização do carrinho da sua vitrine. O exemplo registra as alterações no carrinho até você adicionar esse código; ele não atualiza a exibição do carrinho por conta própria. Os itens já estão no carrinho, portanto, seu código de atualização não deve adicioná-los novamente.

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

<script>
  (() => {
    const button = document.getElementById('ask-about-product');

    function refreshStorefrontCart(items) {
      // TODO: Replace this log with your storefront's cart-refresh code.
      // Re-fetch and render the existing cart. Do not add these items again.
      console.log('Cart display needs refreshing:', items);
    }

    function initializeCustomerHub() {
      const api = window.customerHubApi;
      if (!api) return;

      button.disabled = false;
      button.addEventListener('click', () => {
        api.sendChatMessage('I have a question about this product.');
      });

      api.events.addEventListener('addtocart', (event) => {
        refreshStorefrontCart(event.detail.items);
      });

      api.events.addEventListener('addtocart_v2', (event) => {
        // The Shopify cart count is already updated. Add tracking here.
        console.log('Cart display updated:', event.detail.items);
      });
    }

    if (window.customerHubApi) {
      initializeCustomerHub();
    } else {
      document.addEventListener(
        'klaviyo-customer-hub-loaded',
        initializeCustomerHub,
        { once: true }
      );
    }
  })();
</script>

Recursos adicionais