> ## 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 Shopify

> Add a Voiceflow AI agent to your Shopify storefront with the supplied chat widget. Install it in your theme, test a conversation and publish the reviewed theme.

## 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.

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

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

## Before you begin

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

| Requirement | What to prepare |
| --- | --- |
| Voiceflow agent | A published agent with a floating chat widget, its complete **Widget → Installation** snippet and a known-answer question. |
| Shopify store | An Online Store theme you own or have purchased. Trial copies of paid themes cannot be edited. |
| Site access | A store owner or staff member with **Themes** and **Edit code** permissions for the browser editor. CLI users need the applicable theme access. |
| Review target | An unpublished copy of the theme and a preview URL to test before publication. |

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](https://help.shopify.com/en/manual/online-store/themes/customizing-themes/edit-code/edit-theme-code) covers editor access; [Shopify CLI requirements](https://shopify.dev/docs/storefronts/themes/tools/cli) cover local development access.

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

## Install the widget

Add one widget installation to the storefront layout.

#### Studio

### 1. Copy the generated snippet

In [Agent studio](https://creator.voiceflow.com), open your project’s **Widget → Installation** panel. Copy the complete snippet, including its script tags. Keep its generated authorization and release settings unchanged.

Widget Installation panel with the generated snippet and copy control — Copy the complete installation snippet from your Voiceflow project.

### 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](#test-conversation).

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.

```bash
mkdir voiceflow-theme
cd voiceflow-theme
npx --yes @shopify/cli@5.0.2 theme pull \
  --store YOUR_STORE.myshopify.com \
  --live
```

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:

```liquid
  {% render 'voiceflow-widget' %}
</body>
```

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**:

```bash
npx --yes @shopify/cli@5.0.2 theme check
npx --yes @shopify/cli@5.0.2 theme push \
  --store YOUR_STORE.myshopify.com \
  --unpublished \
  --theme "Voiceflow widget review" \
  --strict
```

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](#test-conversation). For a later review upload, target this unpublished theme by its ID instead of creating another copy.

See the current [pull](https://shopify.dev/docs/api/shopify-cli/theme/theme-pull), [Theme Check](https://shopify.dev/docs/api/shopify-cli/theme/theme-check) and [push](https://shopify.dev/docs/api/shopify-cli/theme/theme-push) references for command options.

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

## 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](/docs/documentation/deploy/environments/publishing). The theme controls placement; Voiceflow controls the agent and widget settings. The [widget API](/docs/documentation/deploy/widget/web-chat-api#choosing-which-environment-the-widget-loads) explains environment selection if you need to change the generated release routing.

| Storefront event | What to check |
| --- | --- |
| First visit | The widget opens without a Shopify account and answers a public support question. |
| Page navigation or reload | Pages using the edited layout load one widget. The conversation follows your [persistence settings](/docs/documentation/deploy/widget/web-chat-api#configuring-chat-persistence). |
| Account sign-in or sign-out | A guest widget conversation does not become authenticated customer support automatically. |

This installation applies to pages using [`theme.liquid`](https://shopify.dev/docs/storefronts/themes/architecture/layouts). 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](/docs/documentation/build/tools/shopify) and server-side authorization. A browser-provided customer ID is not proof that the visitor owns an order.

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

## 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](/docs/documentation/measure/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.

<a id="troubleshooting" />

### 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.

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

## 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](#test-conversation) 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](https://help.shopify.com/en/manual/online-store/themes/managing-themes/publishing-themes) 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.

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

## Custom interface guides

Planned Shopify 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) |
