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.
Building your own interface? Custom chat and voice walkthroughs are coming soon. Start with Chat agents or Voice agents for the APIs.
New to Voiceflow? Build a support 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.
Before you begin
Prepare the agent, storefront access and a safe place to test.
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. 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.
Install the widget
Register one generated snippet on the selected storefront.
Studio
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.
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.
Create and save the script
Choose Create a Script and enter:
Choose Save. Leave unrelated scripts intact. BigCommerce’s Script Manager guide explains these controls.
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.
Use the storefront URL rather than a local Stencil CLI preview, which does not render these scripts.
Code
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:
Keep the access token out of source control, logs and storefront code. Check Script Manager for an existing Voiceflow installation before creating another.
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.
The Scripts API 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.
Register and check the widget
With Node.js 22, run:
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.
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.
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. Keep this as the storefront’s only Voiceflow loader.
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.
Test a shopper conversation
Verify a useful answer on the actual storefront.
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.
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.
Check the project and navigation
Find the exchange in 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.
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.
Release the storefront installation
Review the production destination separately from the agent release.
- Have the Voiceflow owner publish the reviewed agent and widget settings.
- 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.
- Repeat the shopper test 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. After the cache refreshes, verify removal in a fresh shopper window before retiring credentials or the ID file. Keep unrelated scripts intact.
Custom interface guides
Planned BigCommerce walkthroughs for your own conversation UI.
Custom chat and voice walkthroughs are coming soon, separately from this widget guide.