Referencia de la API de JavaScript del Customer Hub

Objetivos del artículo

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

Antes de empezar

Necesitarás lo siguiente:

• Klaviyo Customer Hub configurado y cargado en la tienda en línea. Si tienes una tienda en línea sin interfaz o personalizada, sigue primero Cómo configurar Klaviyo Customer Hub con Shopify sin interfaz; ahí se explica cómo agregar el cargador en el sitio que hace que esta interfaz de programación de aplicaciones (API) esté disponible.
• Posibilidad de editar e implementar el código de tu tienda.

Qué es la API del Customer Hub

Siempre que se cargue Klaviyo Customer Hub —o el chat web independiente de Klaviyo— en tu tienda, Klaviyo adjunta una pequeña interfaz de programación de aplicaciones (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 personalizada.

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

Métodos

open(route?)

Abre el cajón del 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 mostró por ú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 panel lateral de Klaviyo Customer Hub. El Hub permanece en su pantalla actual, por lo que volver a abrirlo con open() (sin ruta) devuelve al cliente al lugar donde lo dejó.

window.customerHubApi.close();

sendChatMessage(message)

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

• message (string) — 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 agente de IA no está habilitado), el cliente es llevado a la pantalla de Chat para iniciar sesión primero. El mensaje se guarda temporalmente y se envía automáticamente una vez que finaliza la sesión. El mensaje guardado caduca después de unos 10 minutos si no se completa el inicio de sesión.

getActiveConversationId()

Devuelve el conversationId de la conversación con actividad que se está llevando a cabo en el panel lateral. Devuelve null si no hay ninguna conversación en curso.

window.customerHubApi.getActiveConversationId();

Escucha los eventos

window.customerHubApi.events permite suscribirse a 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 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