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 configurado e carregado na sua loja. Se você estiver em uma loja headless ou personalizada, siga primeiro Como configurar o Klaviyo Customer Hub com Shopify Headless — ele aborda como adicionar o carregador no site que disponibiliza esta 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 default screen
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 Customer Hub na tela do chat e envia uma mensagem no nome do cliente — útil para os botões “Conversar sobre este produto” ou “Obter ajuda”.

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

sendConversationContext(context)

Coloca em fila o contexto em segundo plano coletado fora da conversa de chat — como respostas de uma pesquisa pré-chat — para enviar com a próxima mensagem de chat do cliente. O Klaviyo então salva e faz referência a esse contexto pelo restante dessa conversa.

• context (object) — um objeto de resposta de pesquisa que contém uma matriz entries. Cada entrada deve incluir um question e um answer.

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

getActiveConversationId()

Retorna o conversationId da conversa com atividade que está acontecendo na gaveta. Retorna null se nenhuma conversa estiver em andamento.

window.customerHubApi.getActiveConversationId();

Escutar eventos

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

addtocart

Acionado quando um cliente adiciona um produto ao carrinho a partir do Hub. Use-o para manter seu carrinho de loja em sincronia.

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

Exemplo completo

Um botão “Chat about this product” que abre o Hub e envia uma mensagem, além de um ouvinte que sincroniza o carrinho da loja quando um comprador adiciona um item do 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>

Recursos adicionais