Authorize your website widget

Use a client key to authorize the Voiceflow widget on your website. It grants access to the Conversation API for its project and is intended to be included in your website’s installation code.

A client key is different from a personal key or service key. Those credentials belong on your server or in local development secrets; never put them in website JavaScript. Use a client key for the widget, not for managing projects through the API.

Before you begin

  • Open the project you want visitors to talk to. You need permission to manage its API keys.
  • Publish the agent to the environment your widget will use.
  • Have access to edit and publish your website’s HTML or custom-code settings.

If you have not built an agent yet, start with the Web agent quickstart.

Find and use your client key

1

Open Client key settings

In your project, open Settings → Client key. Voiceflow creates the project’s key automatically if it does not already have one.

2

Copy the key

Click the copy icon beside the key. You can return to this page to copy the same value again; you do not need to regenerate it for each website.

3

Copy the widget installation code

Under Deploy, open Widget, then find Installation. Copy the generated snippet. It includes your client key in the verify.clientKey setting, along with the widget’s other configuration.

Use the complete generated snippet rather than constructing one yourself. Keep its environment settings unless you intend to load another environment. Client-key authorization does not require making the agent’s API access public.

4

Install and publish your website

Paste the snippet immediately before your website’s closing </body> tag. If you use a website builder, add it to the custom-code area that runs at the end of the page body. Save and publish the website.

For more installation details, see Install widget.

Verify the installation

Open the published website, start a fresh widget conversation, and send a question your agent can answer. Confirm that a reply arrives from the intended agent.

A visible launcher alone does not confirm authorization. Test a conversation on the website, not only with Run inside Creator.

Replace a key or resolve a problem

Regenerate a client key

Regenerating replaces the project’s current key. All widgets using the old key will stop working until you update their installation code. Be ready to update every website that uses it before continuing.

  1. Open Settings → Client key and click Regenerate.
  2. Read the warning and confirm Regenerate.
  3. Return to Widget → Installation and copy the updated snippet.
  4. Replace the old installation code on every website using the key, publish those changes, and test a fresh conversation on each website.

Troubleshoot

I cannot find Client key in Settings

Confirm that you opened the intended project’s settings and that your account has permission to manage its API keys. Ask a workspace administrator to review your access if the page is missing.

The widget stopped replying after regeneration

Update every installation that still contains the old key. Copy the current snippet from Widget → Installation, publish the website changes, and reload the page before starting a fresh conversation. Check for an older copy of the snippet in your website builder or tag manager.

The widget does not reply after installation

Confirm that you copied the complete snippet from the correct project and published the website changes. If the key has been regenerated, copy the snippet again. Check that the agent is published to the environment used by the widget. If your widget restricts allowed domains, check that your website’s domain is allowed.

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