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.

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.