Build with

Overview

Install Voiceflow’s widget so visitors can ask your agent questions on WordPress. This guide covers public support using WPCode (Studio) or a site plugin (Code); both methods install the same widget.

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 to create an agent, add your policies to Knowledge and publish it.

Before you begin

Prepare your agent and WordPress access.

  • Have a published agent and a question it can answer, such as your returns policy.
  • Use a staging site first. You or your WordPress administrator need permission to install plugins.
  • If someone else manages the site, send them the snippet, target pages and a test question. Ask for the published test URL.

See WordPress.com’s code installation and hosting activation requirements. Use the generated widget client key in browser code; keep personal and service API keys on your backend.

Install the widget

Connect your published agent to the website.

Studio

1

Copy your widget snippet

Open your project in Agent studio. Select Widget → Installation and copy the complete snippet, including its script tags.

Copy the installation code from your Voiceflow project. Photo:
2

Add it to WordPress

In WordPress, open Plugins → Add New Plugin. Find WPCode, then choose Install Now and Activate. If your site already has a footer-script manager, use that instead.

Open Code Snippets → Header & Footer. Paste the snippet into Footer, keeping any unrelated code.

WPCode Footer field containing a Voiceflow widget snippet with an example client key
Paste the complete snippet into Footer. The client key shown is an example.

See WPCode’s header/footer instructions for its field settings.

3

Save the installation

Choose Save Changes, clear the page cache if enabled, and open your site. The widget launcher should appear. Continue with Test a visitor conversation.

Install the widget once. A second copy in your theme, builder or another plugin can initialize it twice.

Code

Use this plugin for the default floating widget whose generated configuration contains verify.clientKey. It stays separate from your theme.

1

Create the plugin

Create voiceflow-widget/voiceflow-widget.php. Replace YOUR_WIDGET_CLIENT_KEY with verify.clientKey from Widget → Installation, supplied by the Voiceflow project owner.

The example uses the standard runtime URLs shown above. For a generated snippet using verify.projectID, a different environment or embedded render configuration, use the complete generated snippet in a footer manager instead of this plugin example. The widget environment reference explains release selection.

WordPress queues the loader in the footer and prints the initializer after it. Keep that order; adding async or defer requires a different readiness mechanism.

2

Upload and activate

Zip the voiceflow-widget folder. In WordPress, choose Plugins → Add New Plugin → Upload Plugin, upload it, then activate Site Voiceflow Widget. You can also deploy the folder to wp-content/plugins/ through your normal site deployment.

Use this plugin as the site’s only Voiceflow installation.

3

Check the output

Clear the page cache and open a public page. In its source, find site-voiceflow-widget-js followed by the initializer. Continue with Test a visitor conversation.

Choose widget appearance and pages

Match the supplied widget to your site and control where it appears.

Studio

  1. In Voiceflow’s Widget settings, choose your launcher, colors, icon and interface options, then publish the changes.
  2. Open the WordPress site to check the result. WPCode’s global Footer applies across the site.

For selected pages, send your WordPress developer the included and excluded URLs. Ask them to replace the global snippet with a scoped installation and return those URLs for testing.

Code

  1. Ask the Voiceflow owner to publish the widget appearance, or use the supported widget customization options.
  2. To limit this plugin to selected WordPress Pages, add the following inside its wp_enqueue_scripts callback, before $handle:

Replace support and contact with your page slugs or IDs. is_page() matches Pages; other content types need the corresponding WordPress condition. Deploy the change before testing an included and excluded URL.

Handle identity and sessions

Keep public widget conversations separate from customer accounts.

This installation provides public support. A WordPress login or client-supplied user ID does not authorize the agent to access customer records.

The widget does not automatically identify WordPress or WooCommerce customers. Order access needs a separate WooCommerce integration and backend authorization. Clearing the visible messages alone does not establish an account boundary.

Test a visitor conversation

Check the reply through the installed WordPress widget.

1

Open the public page

Use a logged-out browser window. Open the widget on the published WordPress page, rather than the editor or Voiceflow’s Run panel.

2

Ask a question and follow-up

Send your prepared policy question, then a related follow-up. Check both widget replies against the agent’s Knowledge and instructions.

3

Check sessions and page coverage

Find the exchange in Transcripts to confirm the intended project. Test relevant layouts, including Elementor, Divi or WooCommerce pages. For scoped widget placement, check that excluded pages have no launcher. Verify your session policy after navigation and account changes.

The script is missing

Check the saved installation, cache and footer output.

Confirm that WPCode saved Footer or that your plugin is active. Clear the page cache. For a custom theme, ask its developer to check wp_footer(). On WordPress.com, check the hosting requirements above.

The widget does not appear

Inspect blocked scripts and duplicate installations.

Check Console and Network for a failed cdn.voiceflow.com request. Have the site owner review relevant consent or script-optimization rules and remove duplicate widget installations.

The agent gives no answer or the wrong answer

Check the published agent and installed widget configuration.

Compare the installed client key and environment with the generated snippet. Check the release and Transcripts. Missing policy or product answers belong in the agent’s Knowledge and instructions.

It works only for administrators

Compare the page delivered to logged-out visitors.

Inspect the logged-out page’s HTML and browser errors. Check whether caching, page conditions or consent changes the delivered script. Correct the rule, clear the affected cache and repeat the visitor test.

Release the widget

Publish the widget installation on your production WordPress site.

Studio

  1. Publish the reviewed agent and widget settings in Voiceflow.
  2. Save the snippet on the production WordPress site and clear its page cache.
  3. Repeat the visitor test on the production URL.

Update or remove the widget

Maintain the footer snippet after launch.

Publish later agent or appearance changes in Voiceflow. Replace the WordPress snippet if its generated installation details change.

To remove the widget, delete only its script from Footer, save and clear the page cache. Check that the launcher is gone.

Code

  1. Have the Voiceflow owner publish the reviewed agent and widget settings.
  2. Deploy and activate the plugin with the production project’s widget client key; clear the page cache.
  3. Repeat the visitor test on the production URL.

Update or remove the widget

Maintain the site plugin after launch.

Keep the plugin in version control. Update its configuration when the generated installation details change.

To remove it, deactivate Site Voiceflow Widget and clear the page cache. Check that the script and launcher are gone.

Custom interface guides

Planned WordPress guides for your own chat or voice UI.

WordPress walkthroughs for custom chat and voice interfaces are coming soon. These are separate 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.