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.

Using React or Vue?

Don’t use the vanilla SDK directly. Use @askdialog/dialog-react or @askdialog/dialog-vue: they ship a pre-built DialogProductBlock and DialogInput on top of this SDK. You’d be reinventing them otherwise.

This page is for Svelte, SolidJS, Lit, vanilla JS, server-side templated frontends (Twig, Blade, ERB, etc.), or any other framework without a Dialog package.

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.
product	{ id: string; variantId?: string }	No	The product of the current page. Grounds questions that carry no product of their own (floating bookmark, resume surface, free text) on the product being viewed. See Declaring the current product.
disableAddToCart	boolean	No	Hides Dialog add-to-cart for this widget instance/session (default false). See “Disabling add-to-cart” below.

Note

The widget’s “View cart” button URL is not set here, it’s a dashboard setting. See Configure the cart button.

Disabling add-to-cart

Set disableAddToCart: true to suppress Dialog add-to-cart for a specific session, for example a B2B storefront that hides purchasing actions when a B2B customer is logged in. Evaluate your own condition at initialization:

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'en',
  disableAddToCart: isB2BCustomerLoggedIn, // per session
  callbacks: { /* ... */ },
})

When enabled:

• the assistant hides the add-to-cart CTA on recommendation and conversational product cards;
• callbacks.addToCart is never called and no add-to-cart event is tracked;
• product links and recommendation browsing stay available.

Omit it (or set false) to keep the current behavior. The flag is read at initialization, so it applies for the lifetime of that widget instance (a login-state change takes effect on the next page load).

Declaring the current product

Pass product on product pages so the assistant always knows which product the visitor is looking at. Questions asked without an explicit product — from the floating bookmark, the resume surface or the free-text input — are then answered in the context of that product, including after the visitor navigates from one product page to another:

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

On single-page storefronts, update the declaration on client-side navigation:

client.setCurrentProduct('product-456', 'variant-789') // variantId optional
client.clearCurrentProduct() // left for a non-product page

The id must match the product ID of your Dialog catalog feed. Without a declared product, questions asked outside a product click are answered without product context.

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.