SDK reference

@askdialog/dialog-sdk is the core SDK for embedding Dialog in custom stacks. It handles communication with the Dialog API, the assistant lifecycle, tracking, and exposes everything you need to build a UI around it.

Install

From npm:

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

From CDN (no bundler):

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

When loaded via CDN the SDK is exposed as window.DialogSDK.

Instantiate

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

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'en',
  callbacks: {
    addToCart: async ({ productId, quantity, variantId, currency }) => {
      // Add the product to your cart and update your UI
    },
    getProduct: async (productId, variantId): Promise<SimplifiedProduct> => {
      // Fetch the product from your backend and return it in SimplifiedProduct shape
    },
  },
})

Constructor options

Option	Type	Required	Description
`apiKey`	`string`	Yes	Your Dialog public API key.
`locale`	`string`	Yes	Active locale (e.g. `'en'`, `'fr'`, `'es'`).
`callbacks.addToCart`	`(params) => Promise<void>`	Yes	Called when a user clicks add-to-cart inside the assistant. You handle the actual cart mutation and UI refresh.
`callbacks.getProduct`	`(productId, variantId?) => Promise<SimplifiedProduct>`	Yes	Called to render product cards inside the assistant. Return your product in `SimplifiedProduct` shape.
`theme`	`Theme`	No	Override visual theme (colors, fonts, CTA shape).
`userId`	`string`	No	Stable user ID for your visitor. If omitted, Dialog auto-generates one and persists it.

Sending messages

With product context

client.sendProductMessage({
  question: 'Is this top runs small?',
  productId: 'product-123',
  productTitle: 'Linen V-neck top',
  selectedVariantId: 'variant-456', // optional
})

Without product context

client.sendGenericMessage({
  question: 'What is your return policy?',
})

Fetching suggestions

Get the AI-generated suggestion list for a given product. Useful if you build a custom suggestions UI on your PDP rather than using our DialogProductBlock component.

const suggestions = await client.getSuggestions('product-123')
// {
//   questions: [{ question: '...' }, ...],
//   assistantName: 'Your expert',
//   inputPlaceholder: 'Ask any question...',
//   description: 'Ask any question about this product'
// }

Locale information

const info = client.getLocalizationInformations()
// { countryCode: 'US', formatted: 'en-US', language: 'English', locale: 'en' }

Tracking

The SDK auto-tracks assistant interactions (open / close / message / add-to-cart from assistant). Use the methods below for events that happen outside the assistant.

Manual add-to-cart and checkout

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',
})

Call these whenever the customer adds to cart or completes checkout without going through the Dialog assistant, so the dashboard can attribute conversion correctly. See Tracking — SDK custom for full guidance.

Listening to assistant events

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

// Later
unsubscribe()

Available event types (full guidance in Tracking — SDK custom):

userOpenedAssistant
userClosedAssistant
userSentMessage
userClickedOnProductCard
userOpenedRecommendation
userAddedToCart
userSendPositiveFeedback
userSendNegativeFeedback

Theme

Pass a theme object on construction:

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

The title, description, and content keys on theme only apply to the Vue / React components. The vanilla SDK doesn’t render those — you do.

SimplifiedProduct shape

Your getProduct callback must return this shape:

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, e.g. '29.99'
  currencyCode: string                // ISO code, e.g. 'USD'
  compareAtPrice?: string | null
  url?: string
  selectedOptions?: { name: string; value: string }[]
  image?: { url?: string } | null
}

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

Next steps

React components — drop-in UI with the SDK.
Vue components — same, for Vue 3.
Tracking SDK custom — full tracking guidance for the SDK path.
Add-to-cart issues — common UI-sync patterns.