> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add the Voiceflow widget to BigCommerce

> Add a Voiceflow AI agent to BigCommerce with the supplied chat widget. Use Script Manager or the Scripts API, configure consent and test a shopper conversation.

## Overview

Add Voiceflow’s floating chat widget to your **BigCommerce storefront** so shoppers can ask your AI agent about products, shipping or returns. **Studio** uses Script Manager; **Code** registers the same widget through the Scripts API. Both install the supplied interface for public support.

This guide covers Stencil storefronts and current Catalyst storefronts with their standard Script Manager loader. Catalyst must be version 1.1 or later. Blueprint themes, checkout and payment pages, and other headless storefronts need separate implementation work.

**Note:** 

**Building your own interface?** Custom chat and voice walkthroughs are [coming soon](#custom-interface). Start with [Chat agents](/docs/api-reference/agent-runtime/chat) or [Voice agents](/docs/api-reference/agent-runtime/voice) for the APIs.

New to Voiceflow? [Build a support agent](/docs/guides/usecases/customer-service/build-faq-agent), add your help content to Knowledge and publish it first. Installing the widget does not connect a shopper’s account or give the agent access to orders.

<a id="before-you-begin"></a>

## Before you begin

Prepare the agent, storefront access and a safe place to test.

| Requirement | What to prepare |
| --- | --- |
| Voiceflow agent | A published agent, its complete **Widget → Installation** snippet and a known-answer policy question. |
| Storefront | Its public URL and access to the correct storefront’s Script Manager. Use a test store or test storefront first. |
| Store administrator | Someone who can approve placement and the functional-cookie consent behavior. |
| Code method | Node.js 22 and a store-level API account with **Content: modify**, plus the store hash, selected storefront’s channel ID and access token. |

In Voiceflow, open **Widget → Modality & interface**. Set **Modality** to **Chat** and **Chat interface** to **Widget**, then publish. Review staging and production hosts if the project restricts widget domains.

For Code, have an authorized administrator create the scoped account under **Settings → Store-level API accounts** and supply those three values using the [API account instructions](https://docs.bigcommerce.com/developer/docs/overview/api-fundamentals/api-accounts). The token stays in your terminal environment; it never belongs in the widget or a browser bundle.

Saving a script or creating it through the API applies it to the selected storefront. It is separate from publishing the Voiceflow agent.

<a id="install-widget"></a>

## Install the widget

Register one generated snippet on the selected storefront.

#### Studio

### 1. Copy the generated snippet

In Voiceflow, open **Widget → Installation** and copy the complete snippet, including its `<script>` tags. Have the project owner supply it if you do not manage the agent.

### 2. Choose the storefront

In BigCommerce, open **Storefront → Script Manager**. For Multi-Storefront, select the intended storefront through **Channel Manager** and open its Script Manager.

Check for an existing Voiceflow installation before creating another. Remove or replace the old installation with its owner.

### 3. Create and save the script

Choose **Create a Script** and enter:

| Setting | Value |
| --- | --- |
| Script name | `Voiceflow chat widget` |
| Placement | **Footer** |
| Location | **Storefront pages** |
| Script category | **Functional** |
| Script type | **Script** |
| Load method, if shown | **Default** |
| Script contents | The complete generated snippet, including its `<script>` tags. |

Choose **Save**. Leave unrelated scripts intact. BigCommerce’s [Script Manager guide](https://support.bigcommerce.com/s/article/Using-Script-Manager?language=en_US) explains these controls.

### 4. Check the storefront

Allow about 20 seconds for BigCommerce’s script cache, then open the actual storefront in a fresh visitor window. Accept functional cookies if the storefront requires them. Confirm one launcher appears, then run the [shopper test](#test-conversation).

Use the storefront URL rather than a local Stencil CLI preview, which does not render these scripts.

#### Code

### 1. Prepare the snippet and credentials

Use a separate working directory for each storefront. Save the complete generated **Widget → Installation** snippet as `voiceflow-widget.html`, including its `<script>` tags. Preserve its authorization, loader, runtime URLs and environment settings unchanged.

Set the values supplied by your store administrator in your terminal. Replace every placeholder:

```bash
export BC_STORE_HASH='YOUR_STORE_HASH'
export BC_CHANNEL_ID='YOUR_STOREFRONT_CHANNEL_ID'
export BC_ACCESS_TOKEN='YOUR_CONTENT_MODIFY_ACCESS_TOKEN'
```

Keep the access token out of source control, logs and storefront code. Check Script Manager for an existing Voiceflow installation before creating another.

### 2. Create the registration script

Save this as `voiceflow-script.mjs`. It uses Node’s built-in `fetch` to create one footer script on your selected channel. It retains the returned ID for later updates.

```javascript
import { readFile, writeFile } from 'node:fs/promises';

const storeHash = process.env.BC_STORE_HASH;
const channelId = Number(process.env.BC_CHANNEL_ID);
const token = process.env.BC_ACCESS_TOKEN;
if (!storeHash || !token || !Number.isSafeInteger(channelId) || channelId < 1) {
  throw new Error('Set BC_STORE_HASH, BC_CHANNEL_ID and BC_ACCESS_TOKEN.');
}
const mode = process.argv[2];
if (mode && mode !== '--update') throw new Error('Use no argument or --update.');
const statePath = 'voiceflow-script-id.json';
let previous;
try {
  previous = JSON.parse(await readFile(statePath, 'utf8'));
} catch (error) {
  if (error.code !== 'ENOENT') throw error;
}
if (previous && (previous.storeHash !== storeHash || previous.channelId !== channelId)) {
  throw new Error('The saved ID belongs to another store or channel.');
}
if (mode === '--update' ? !previous?.uuid : previous) {
  throw new Error('Create once, then use --update with the saved ID file.');
}
const payload = {
  name: 'Voiceflow chat widget',
  html: await readFile('voiceflow-widget.html', 'utf8'),
  kind: 'script_tag',
  load_method: 'default',
  location: 'footer',
  visibility: 'storefront',
  consent_category: 'functional',
  channel_id: channelId,
  enabled: true,
  auto_uninstall: true,
};
const base = `https://api.bigcommerce.com/stores/${encodeURIComponent(storeHash)}/v3/content/scripts`;
const url = mode === '--update' ? `${base}/${encodeURIComponent(previous.uuid)}` : base;
const response = await fetch(url, {
  method: mode === '--update' ? 'PUT' : 'POST',
  headers: {
    'X-Auth-Token': token,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});
if (!response.ok) throw new Error(`Scripts API returned HTTP ${response.status}.`);
const { data } = await response.json();
if (!data?.uuid) throw new Error('No script ID returned; inspect Script Manager before retrying.');
await writeFile(statePath, JSON.stringify({ storeHash, channelId, uuid: data.uuid }, null, 2));
console.log(`Saved Voiceflow script ${data.uuid}`);
```

The [Scripts API](https://docs.bigcommerce.com/developer/docs/integrations/scripts) requires the original API account for later code updates. Retain that account and the local ID file. An API-created script’s code is read-only in Script Manager.

### 3. Register and check the widget

With Node.js 22, run:

```bash
node voiceflow-script.mjs
```

Check the saved ID and the selected storefront’s Script Manager entry. Allow about 20 seconds for the script cache, then open the actual storefront in a fresh visitor window. Accept functional cookies if required and run the [shopper test](#test-conversation).

An API success does not prove the agent replies. If creation times out or the ID file cannot be saved, inspect Script Manager before retrying; the remote script may already exist. Do not create a duplicate. Local Stencil CLI previews do not render these scripts.

<a id="configure-widget"></a>

## Configure appearance and placement

Keep Voiceflow settings separate from storefront delivery and consent.

Choose the launcher, colors and icon in Voiceflow’s **Widget** panel, then [publish the changes](/docs/documentation/deploy/environments/publishing). Keep this as the storefront’s only Voiceflow loader.

| Storefront behavior | What to check |
| --- | --- |
| Stencil pages | The theme retains BigCommerce’s `footer.scripts` placeholder so footer scripts render. |
| Catalyst pages | The app retains the standard Script Manager loader and its consent handling. See [Catalyst script delivery](https://docs.bigcommerce.com/developer/docs/storefront/catalyst/guides/manually-installing-scripts). |
| Consent | Use **Functional** for chat. When the storefront gates that category, the widget waits for consent. Do not relabel it Essential to bypass the choice. |
| Product, category and cart navigation | One widget remains available; client-side navigation does not initialize another loader. |
| Reload or return visit | Retention follows your [widget persistence settings](/docs/documentation/deploy/widget/web-chat-api#configuring-chat-persistence). |

Use **Storefront pages** placement. This recipe does not add checkout or payment-page behavior. If you need narrower placement, have the storefront developer own and test that rule with the site’s actual routing and consent system.

A shopper login or browser-provided customer ID does not authorize private order access. Add protected lookups through backend-authorized tools separately from widget installation.

<a id="test-conversation"></a>

## Test a shopper conversation

Verify a useful answer on the actual storefront.

### 1. Open the storefront as a shopper

Use a private window on the selected storefront URL. Make the relevant cookie choice. Confirm one launcher appears when functional scripts are allowed and opens normally. Check the decline case too if consent gating is enabled.

### 2. Ask a question and follow-up

Ask a prepared question, such as “Can I return an unused item?” Then ask “How do I start a return?” Both replies should match the policies in your agent’s Knowledge.

### 3. Check the project and navigation

Find the exchange in [Transcripts](/docs/documentation/measure/transcripts) to confirm the intended project. Move between a product, category and cart page, then reload. Confirm one launcher remains and conversation retention matches your settings.

<a id="troubleshooting" />

### BigCommerce rejects the script

Check the snippet format or API permissions.

Use **Script** or API `kind: 'script_tag'` with **Default** loading. Paste exactly the generated script tag, without surrounding page HTML or a `noscript` block. For the API, check the store hash, channel ID and **Content: modify** scope. Keep the token in the request header.

### The launcher is missing

Check the storefront, consent and script delivery.

Verify the correct channel, enabled script, Footer placement and Storefront pages location. Wait for the script cache, then use the real storefront URL. Check functional-cookie consent. Have the developer inspect the Stencil footer placeholder or Catalyst Script Manager loader, then Console and Network for blocked loader requests or rejected setup.

### Two widgets appear

Find the other installation before adding code.

Check Script Manager, API-created scripts, theme files, apps and tag managers for another Voiceflow loader. Keep one installation and check a fresh window. Do not reload the snippet after every Catalyst route change.

### The answer is wrong or missing

Check the project, release and support content.

Compare the installed snippet with the intended Voiceflow project’s generated snippet. Confirm the reviewed release is published and retry with a fresh conversation. Correct missing policy information in Knowledge or instructions; installing the widget does not import store data.

<a id="go-live"></a>

## Release the storefront installation

Review the production destination separately from the agent release.

1. Have the Voiceflow owner publish the reviewed agent and widget settings.
2. Register the reviewed snippet on the production storefront through your chosen method, using its channel and consent settings. Saving or API registration applies it without a separate theme publication.
3. Repeat the [shopper test](#test-conversation) on the production URL.

### Update or remove the widget

Keep one script and preserve its ownership.

Publish agent and appearance changes in Voiceflow. If installation settings change, replace the snippet in the existing Script Manager entry. For an API-created entry, replace `voiceflow-widget.html` and run `node voiceflow-script.mjs --update` with the original account, store/channel values and ID file.

To remove either installation, have an authorized store administrator delete its entry in the selected storefront’s Script Manager. If using the API, delete the saved UUID through the original API account’s [Scripts API](https://docs.bigcommerce.com/developer/docs/integrations/scripts). After the cache refreshes, verify removal in a fresh shopper window before retiring credentials or the ID file. Keep unrelated scripts intact.

<a id="custom-interface"></a>

## Custom interface guides

Planned BigCommerce walkthroughs for your own conversation UI.

Custom chat and voice walkthroughs are **coming soon**, separately from this widget guide.

| Planned guide | API reference |
| --- | --- |
| Add custom chat | [Chat agents](/docs/api-reference/agent-runtime/chat) |
| Add custom voice | [Voice agents](/docs/api-reference/agent-runtime/voice) |
