Build with

Overview

Add Voiceflow’s widget to your Shopify storefront so shoppers can ask your AI agent about products, shipping and returns. This guide installs the same widget through Shopify admin (Studio) or a local theme project (Code).

It covers public support on an Online Store Liquid theme. Checkout, the password page, new customer accounts and headless storefronts use other surfaces; editing theme.liquid does not install the widget there.

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 with your policies in Knowledge, then publish it before connecting the store.

Before you begin

Prepare the agent, store access and a theme you can safely edit.

Before copying the snippet, open Widget → Modality & interface in Voiceflow. Set Modality to Chat and Chat interface to Widget, then publish.

If someone else manages Shopify, send them the complete generated snippet and test question. Ask them to return the theme name and preview URL. Browser code must not contain a personal or service API key.

The theme-code guide covers editor access; Shopify CLI requirements cover local development access.

Install the widget

Add one widget installation to the storefront layout.

Studio

1

Copy the generated snippet

In Agent studio, open your project’s Widget → Installation panel. Copy the complete snippet, including its script tags. Keep its generated authorization and release settings unchanged.

Copy the complete installation snippet from your Voiceflow project. Photo:
2

Edit an unpublished theme

In Shopify, open Online Store → Themes. Use the current theme’s … → Duplicate action, then find the copy under Draft themes. On that copy, choose … → Edit code.

Open layout/theme.liquid. Paste the complete snippet immediately before the existing closing </body> tag, preserving the rest of the file. Choose Save.

3

Open the theme preview

Return to Themes and preview the edited copy. Open a normal storefront page; the widget launcher should appear. Keep this theme unpublished while you complete the visitor test.

Use one installation. Remove an older Voiceflow snippet or app-based installation before enabling a second copy.

Code

Use Node.js 22.12 or later. These commands pin Shopify CLI 5.0.2; no global installation is required.

1

Pull the current theme

Create an empty working folder, then download the store’s live theme. Replace YOUR_STORE with its myshopify.com prefix. Follow the browser sign-in prompt using an account with theme access.

This reads the current theme into your folder. It does not publish changes. If you already maintain this theme in version control, work from its current reviewed source instead of pulling over local edits.

2

Create the widget snippet

Create snippets/voiceflow-widget.liquid. Paste the complete generated Widget → Installation snippet supplied by the Voiceflow project owner into this file, including the script tags.

Keep the JavaScript unchanged: do not translate the configuration into Liquid, wrap the script in another script tag or replace its authorization with an API key.

In layout/theme.liquid, insert the render line immediately before the existing closing body tag:

Keep the rest of the layout, including Shopify’s content_for_header and content_for_layout output. Call this snippet once; do not also render it from product sections or a Custom Liquid block.

3

Check and upload for review

Run Theme Check and resolve errors. Then upload a new unpublished theme:

The push creates a review copy; it does not replace the live theme. Open its preview link, confirm that the launcher appears and complete the visitor test. For a later review upload, target this unpublished theme by its ID instead of creating another copy.

See the current pull, Theme Check and push references for command options.

Configure appearance and sessions

Keep storefront presentation separate from customer account access.

In Voiceflow’s Widget settings, choose the launcher, colors and icon, then publish the changes. The theme controls placement; Voiceflow controls the agent and widget settings. The widget API explains environment selection if you need to change the generated release routing.

This installation applies to pages using theme.liquid. If you need selected-page placement, have the theme developer scope the installation and supply an included and excluded URL for testing.

Order lookup needs the separate Shopify integration and server-side authorization. A browser-provided customer ID is not proof that the visitor owns an order.

Test a shopper conversation

Verify a useful answer through the installed storefront widget.

1

Open the review URL

Open the unpublished theme’s preview link in a private browser window. Pass the store password if required, then visit a normal storefront page. Confirm that one launcher appears and opens. The password screen itself is outside this installation.

2

Ask a question and follow-up

Ask a prepared question, such as “How long do I have to return an unused item?” Then ask “How do I start a return?” Both replies should match the policies in your agent’s Knowledge. Do not use real customer order details for this public-support test.

3

Check the project and navigation

Find the exchange in Transcripts to confirm the intended project. Visit product, collection and cart pages, then reload. Check for duplicate launchers and confirm the conversation behaves according to your persistence settings. If placement is scoped, test an excluded page too.

The launcher is missing

Check the theme, layout and browser requests.

Confirm that the preview link opens the theme you edited. Inspect the page source for the snippet. If it is absent, check the saved layout and any page conditions. If present, inspect Console and Network for a blocked cdn.voiceflow.com request or initialization error; review consent and optimization rules with the site owner.

The widget loads twice

Find the second initialization.

Search the theme for another widget snippet or voiceflow.chat.load call, and check existing app embeds. Keep one active installation, then reload the page. A cart drawer or dynamically refreshed section should not initialize another copy.

The answer is wrong or missing

Verify the installed project and published release.

Compare the saved snippet with the project owner’s generated installation code. Check the selected environment and published agent, then repeat with a fresh conversation. Correct missing policy answers in the agent’s Knowledge or instructions.

It disappears outside the storefront

Check whether the destination uses the edited layout.

Checkout, new customer accounts, password pages and a headless storefront are outside this theme recipe. Do not copy the snippet into a customer-event pixel to reach them; that is a different execution surface.

Publish the reviewed theme

Release the website installation separately from the Voiceflow agent.

  1. Have the Voiceflow owner publish the reviewed agent and widget settings.
  2. In Shopify’s Online Store → Themes → Draft themes, find the tested theme and choose Publish, then confirm. Coordinate any theme changes made since the review copy was created.
  3. Repeat the shopper test on the production store URL, without the theme-preview link.

Shopify keeps the previously published theme in Draft themes, so you can publish it again if a rollback is needed. Publishing a theme does not remove the store password.

Update or remove the widget

Maintain the installation when the agent or theme changes.

Publish agent and appearance changes in Voiceflow. Replace the saved snippet when the project owner supplies changed installation settings.

Manual code belongs to the edited theme. After a theme update or replacement, check that the installation remains and repeat the visitor test. Keep local theme changes in version control.

To remove the widget, delete only its inserted script or render line, plus the unused snippet file if applicable. Save or deploy the change and check the live storefront. Keep other theme code intact.

Custom interface guides

Planned Shopify walkthroughs for your own conversation UI.

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

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.