Referencia del SDK

@askdialog/dialog-sdk es el SDK core para embedder Dialog en stacks custom. Maneja la comunicación con la API Dialog, el ciclo de vida del asistente, el tracking, y expone todo lo que necesitas para construir una UI alrededor.

Install

Desde npm:

npm install @askdialog/dialog-sdk
# o
pnpm add @askdialog/dialog-sdk
# o
yarn add @askdialog/dialog-sdk

Desde CDN (sin bundler):

<script src="https://d2m6yt8rnm4dos.cloudfront.net/dialog-sdk.X.Y.Z.min.js"></script>

Cargado vía CDN, el SDK se expone como window.DialogSDK.

Instanciar

import { Dialog, type SimplifiedProduct } from '@askdialog/dialog-sdk'

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'es',
  callbacks: {
    addToCart: async ({ productId, quantity, variantId, currency }) => {
      // Añade el producto al carrito y refresca tu UI
    },
    getProduct: async (productId, variantId): Promise<SimplifiedProduct> => {
      // Obtén el producto de tu backend y devuélvelo con el formato SimplifiedProduct
    },
  },
})

Opciones del constructor

Opción	Tipo	Requerida	Descripción
`apiKey`	`string`	Sí	Tu API key pública de Dialog.
`locale`	`string`	Sí	Locale activa (ej. `'en'`, `'fr'`, `'es'`).
`callbacks.addToCart`	`(params) => Promise<void>`	Sí	Llamada cuando el usuario clica add-to-cart dentro del asistente. Tú manejas la mutación del carrito y el refresh de UI.
`callbacks.getProduct`	`(productId, variantId?) => Promise<SimplifiedProduct>`	Sí	Llamada para renderizar las cards de producto dentro del asistente. Devuelve tu producto con el formato `SimplifiedProduct`.
`theme`	`Theme`	No	Override del theme visual (colores, fuentes, forma de los CTA).
`userId`	`string`	No	ID estable del visitante. Si se omite, Dialog auto-genera uno y lo persiste.
`product`	`{ id: string; variantId?: string }`	No	El producto de la página actual. Ancla las preguntas sin producto propio (bookmark flotante, reanudación, campo libre) en el producto consultado. Ver Declarar el producto actual.
`disableAddToCart`	`boolean`	No	Oculta el add-to-cart de Dialog para esta instancia/sesión del widget (por defecto `false`). Ver «Desactivar el add-to-cart» más abajo.

Desactivar el add-to-cart

Pon disableAddToCart: true para desactivar el add-to-cart de Dialog en una sesión concreta, por ejemplo una tienda B2B que oculta las acciones de compra cuando un cliente B2B está conectado. Evalúa tu propia condición en la inicialización:

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'es',
  disableAddToCart: isB2BCustomerLoggedIn, // por sesión
  callbacks: { /* ... */ },
})

Cuando está activado:

el asistente oculta el CTA add-to-cart en las cards de recomendación y las cards de producto conversacionales;
callbacks.addToCart nunca se llama y no se trackea ningún evento add-to-cart;
los enlaces de producto y la navegación de recomendaciones siguen disponibles.

Omítelo (o pon false) para mantener el comportamiento actual. El flag se lee en la inicialización, así que se aplica durante toda la vida de la instancia del widget (un cambio de estado de sesión surte efecto en la siguiente carga de página).

Declarar el producto actual

Pasa product en las páginas de producto para que el asistente sepa siempre qué producto está viendo el visitante. Las preguntas hechas sin producto explícito — desde el bookmark flotante, la reanudación de conversación o el campo libre — se responden entonces en el contexto de ese producto, incluso después de navegar de una página de producto a otra:

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'es',
  product: { id: 'product-123', variantId: 'variant-456' }, // variantId opcional
  callbacks: { /* ... */ },
})

En tiendas single-page, actualiza la declaración en cada navegación del lado del cliente:

client.setCurrentProduct('product-456', 'variant-789') // variantId opcional
client.clearCurrentProduct() // salida hacia una página sin producto

El id debe coincidir con el ID de producto de tu feed de catálogo Dialog. Sin producto declarado, las preguntas hechas fuera de un clic de producto se responden sin contexto de producto.

Enviar mensajes

Con contexto de producto

client.sendProductMessage({
  question: '¿Esta camiseta talla pequeña?',
  productId: 'product-123',
  productTitle: 'Camiseta de lino cuello V',
  selectedVariantId: 'variant-456', // opcional
})

Sin contexto de producto

client.sendGenericMessage({
  question: '¿Cuál es vuestra política de devoluciones?',
})

Obtener sugerencias

Obtén la lista de sugerencias generadas por IA para un producto dado. Útil si construyes una UI custom de sugerencias en tu PDP en lugar de usar nuestro componente DialogProductBlock.

const suggestions = await client.getSuggestions('product-123')
// {
//   questions: [{ question: '...' }, ...],
//   assistantName: 'Tu experto',
//   inputPlaceholder: 'Haz una pregunta...',
//   description: 'Haz cualquier pregunta sobre este producto'
// }

Información de locale

const info = client.getLocalizationInformations()
// { countryCode: 'ES', formatted: 'es-ES', language: 'Spanish', locale: 'es' }

Tracking

El SDK auto-trackea las interacciones con el asistente (open / close / message / add-to-cart desde el asistente). Usa los métodos abajo para los eventos que pasan fuera del asistente.

Add-to-cart y checkout manuales

client.registerAddToCartEvent({
  productId: 'product-123',
  quantity: 1,
  currency: 'EUR',
  variantId: 'variant-456',
  price: 29.99,
})

client.registerSubmitCheckoutEvent({
  productId: 'product-123',
  quantity: 1,
  currency: 'EUR',
  variantId: 'variant-456',
})

Llama estos métodos cada vez que el cliente añade al carrito o completa el checkout sin pasar por el asistente Dialog, para que el dashboard pueda atribuir la conversión correctamente. Ver Tracking: SDK custom para detalles.

Escuchar eventos del asistente

const unsubscribe = client.onAssistantEvent((event) => {
  // event.type, event.payload
})

// Más tarde
unsubscribe()

Tipos de eventos disponibles (guía completa en Tracking SDK personalizado):

userOpenedAssistant
userClosedAssistant
userSentMessage
userClickedOnProductCard
userOpenedRecommendation
userAddedToCart
userSendPositiveFeedback
userSendNegativeFeedback

Theme

Pasa un objeto theme en la construcción:

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'es',
  theme: {
    backgroundColor: '#ffffff',
    primaryColor: '#000000',
    ctaTextColor: '#ffffff',
    ctaBorderType: 'rounded', // 'straight' | 'rounded'
    capitalizeCtas: false,
    fontFamily: 'Inter, sans-serif',
    highlightProductName: true,
  },
  callbacks: { /* ... */ },
})

Las claves title, description y content del theme solo aplican a los componentes Vue / React. El SDK vanilla no renderiza esas zonas, eres tú quien lo hace.

Formato SimplifiedProduct

Tu callback getProduct debe devolver este formato:

interface SimplifiedProduct {
  id: string
  title: string
  handle: string
  descriptionHtml?: string
  url?: string
  totalInventory: number
  featuredImage?: { url?: string } | null
  variants: SimplifiedProductVariant[]
  options?: SimplifiedProductOption[]
}

interface SimplifiedProductVariant {
  id: string
  displayName?: string
  inventoryQuantity?: number
  price: string                       // string, ej. '29.99'
  currencyCode: string                // código ISO, ej. 'EUR'
  compareAtPrice?: string | null
  url?: string
  selectedOptions?: { name: string; value: string }[]
  image?: { url?: string } | null
}

interface SimplifiedProductOption {
  id: string
  name: string
  position: number
  values: string[]
}

Siguientes pasos

Componentes React: UI drop-in con el SDK.
Componentes Vue: lo mismo, para Vue 3.
Tracking SDK custom: guía completa de tracking desde el SDK.
Problemas al añadir al carrito: patterns comunes de sync de UI.