Configuration

Every field the widget accepts, and which settings come from the dashboard instead.

ShopAssistConfig

Field	Type	Default	What it is
`shopDomain`	`string`	—	Required. Your shop identifier. On a headless Shopify store this is the `*.myshopify.com` domain, not the public URL.
`platform`	`"custom" \| "shopify" \| "woocommerce" \| "idosell"`	`custom`	The storefront platform.
`apiUrl`	`string`	`https://api.getshopassist.com`	The ShopAssist API.
`language`	`string`	detected	UI language hint, such as `en`, `de` or `sl`.
`customerId`	`string`	—	Signed-in customer id. Powers order lookup.
`custom`	`CustomStorefrontConfig`	—	Storefront routing and locale. See below.
`cart`	`ShopAssistCartBridge`	—	Cart bridge. See below.
`scriptUrl`	`string`	the CDN bundle	Override the widget bundle URL, for self-hosting or local testing.

Only shopDomain is required.

ShopAssist({ shopDomain: "your-shop.com" });

Colors, button position and icon, greeting, modal title, tooltip text, suggestion chips, notification sound and delay, and the page, locale and country rules all come from your ShopAssist dashboard. They are not fields on this object.

This is deliberate: those are the settings a merchant changes, and a merchant cannot deploy your storefront. If you set them in code they are overwritten on load, which looks like the widget ignoring you.

Storefront routing

Set this when your product URLs are not /products/<handle>, or when the widget cannot tell what kind of page it is on.

Field	Type	Default	What it is
`currency`	`string`	`USD`	Currency for the storefront context sent to the API.
`language`	`string`	`en`	Storefront language.
`country`	`string`	`US`	Storefront country.
`routePrefix`	`string`	—	Prefix for localized routes, such as `/en`.
`productUrlPattern`	`string`	`/products/{handle}`	Template for product links. `{handle}` is the product slug.
`productPagePattern`	`string`	`/products/([^/?#]+)`	Regular expression with one capture group, used to detect a product page and read the handle.
`cartUrl`	`string`	`/cart`	Cart page URL.
`checkoutUrl`	`string`	—	Checkout URL. A custom storefront has no conventional checkout route, so without this the post-add banner can only offer the cart.
`detectLanguage`	`boolean`	`false`	Follow `<html lang>` live instead of the static `language`.

ShopAssist({
  shopDomain: "your-shop.com",
  custom: {
    currency: "EUR",
    language: "sl",
    country: "SI",
    productUrlPattern: "/izdelek/{handle}",
    productPagePattern: "/izdelek/([^/?#]+)",
  },
});

productPagePattern is a regular expression with exactly one capture group, which must capture the handle.

detectLanguage is for storefronts with a language switcher. With it on, the widget follows <html lang> as the page changes, and language becomes the fallback for when the attribute is missing.

The cart bridge

Field	Type	What it does
`add`	`(variantId, quantity, properties?) => void \| Promise<void>`	Required. Adds a variant to your cart. The widget waits for a returned promise.
`open`	`() => void`	Called after a successful add, to open your cart drawer.

See add to your cart.

Opening the chat

Field	Type	What it does
`message`	`string`	Sent as the first message of a fresh session.
`source`	`OpenSource`	Records where the conversation began.
`faqId`	`number`	Serves a stored answer as written instead of calling the model.

source records where a conversation began, and feeds the "Where conversations started" breakdown in your weekly report.

Boot outcomes

status() returns one of three values once the widget has settled, or null while it is still loading.

Value	Meaning
`mounted`	The widget is on screen.
`disabled`	The shop is turned off in the ShopAssist dashboard.
`gated`	A page, locale or country rule excluded this page.

disabled and gated are both normal outcomes, not failures. A rejected load() is the failure case, and it means the bundle did not load at all.