Referencia de la API JavaScript de Customer Hub

Qué aprenderás

Cómo controlar Klaviyo Customer Hub (o el chat web independiente de Klaviyo) desde el código de la tienda usando la API de JavaScript window.customerHubApi. Abrirás y cerrarás la experiencia, irás a una pantalla específica, enviarás un mensaje de chat en nombre del comprador y escucharás eventos como añadir al carrito.

Antes de empezar

Necesitarás:

• Klaviyo Customer Hub configurado y cargado en la tienda. Si utilizas una tienda headless o personalizada, sigue primero Cómo configurar Klaviyo Customer Hub con Headless Shopify (incluye cómo añadir el cargador en el sitio que hace que esta API esté disponible).
• Puedes editar e implementar el código de tu tienda.

Qué es el API Customer Hub

Cada vez que Klaviyo Customer Hub (o el chat web independiente de Klaviyo) se carga en la tienda, Klaviyo adjunta una pequeña API de JavaScript al objeto global window como window.customerHubApi. Puedes usarla para abrir, cerrar e interactuar con la experiencia desde tu propio código (por ejemplo, desde un botón, un banner o una página de producto personalizados).

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

Métodos

open(route?)

Abre el cajón de Customer Hub.

• route (cadena, opcional): una ruta a la que navegar al abrir. Si se omite, el Hub se abre en la pantalla que se mostraba la última vez.

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

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

Rutas disponibles

close()

Cierra el cajón de Klaviyo Customer Hub. El Hub se mantiene en la pantalla actual, por lo que, al volver a abrirlo con open() (sin ruta), devuelve al cliente a donde lo dejó.

window.customerHubApi.close();

sendChatMessage(message)

Abre el Customer Hub en la pantalla de chat y envía un mensaje en nombre del cliente, útil para los botones «Chatear sobre este producto» u «Obtener ayuda».

• message (cadena) — el mensaje que se enviará.

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

Cuando se requiere iniciar sesión: si tu tienda requiere que los clientes inicien sesión antes de chatear (y el AI Agent no está habilitado), los clientes son llevados a la pantalla de Chat para iniciar sesión primero. El mensaje se guarda temporalmente y se envía automáticamente cuando termina de iniciar sesión. El mensaje guardado caduca al cabo de unos 10 minutos si no se completa el inicio de sesión.

sendConversationContext(context)

Pone en cola el contexto en segundo plano recopilado fuera de la conversación del chat (como las respuestas de una encuesta previa al chat) para enviarlo con el siguiente mensaje de chat del cliente. Luego, Klaviyo guarda y hace referencia a este contexto durante el resto de la conversación.

• context (objeto) — un objeto de respuesta de encuesta que contiene una matriz entries. Cada entrada debe incluir un question y un answer.

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

getActiveConversationId()

Devuelve el conversationId de la conversación activa que tiene lugar en el cajón. Devuelve null si no hay ninguna conversación en curso.

window.customerHubApi.getActiveConversationId();

Escucha los eventos

window.customerHubApi.events te permite suscribirte a los eventos que ocurren dentro de Klaviyo Customer Hub.

addtocart

Se activa cuando un cliente añade un producto a su carrito desde el Hub. Úsalo para mantener tu carrito de la tienda sincronizado.

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

Ejemplo completo

Un botón «Chatear sobre este producto» que abre el Hub y envía un mensaje, además de un agente de escucha que sincroniza el carrito de la tienda cuando un comprador añade un artículo desde el 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 adicionales