Products & Surfaces

Embedding the chat widget (script tag)

Use the script-tag embed to add the Runtype chat widget to an HTML page without installing a framework package.

Before you begin

Complete the following prerequisites before you get the embed code:

  • Create a Product with a chat Surface.
  • Link at least one Capability to the Surface.
  • Create a client token in the Auth tab.
  • Add your website origin to Allowed Origins.

Get the embed code

To copy the script-tag snippet, follow these steps:

  1. Open your Product and select the chat Surface.
  2. Select the Ship tab.
  3. Select With Code.
  4. Select Script Tag.
  5. Select a client token when the Ship tab lists more than one.
  6. Copy the generated snippet.

The snippet loads the install.global.js installer from the @runtypelabs/persona package. It includes the selected client token, API URL, and widget configuration.

Install the widget

To install the widget on an HTML page, paste the generated snippet before the closing </body> tag. The following sample shows the supported installer format:

Script tag
1<script
2  src="https://cdn.runtype.com/persona/latest/install.global.js"
3  data-runtype-token="YOUR_CLIENT_TOKEN"
4></script>

Replace YOUR_CLIENT_TOKEN with the client token that you select in the Ship tab. Copy the full generated snippet to include the saved widget configuration.

Configure the widget

Use the Customize control in the Ship tab to configure the widget. The generated snippet reflects your saved settings. You can configure the following settings:

  • Theme: Set colors, borders, launcher position, and other styles.
  • Welcome message: Set the first message that visitors see.
  • Launcher: Set the chat bubble’s position and style.

Use client tokens

Use a client token to authenticate a browser chat widget. Do not put an API key in client-side code. Client tokens have the following properties:

  • Public: Safe to include in browser code.
  • Scoped: Bound to a specific Surface and its linked Flows or Agents.
  • Origin-restricted: Limited to browser origins that match Allowed Origins.

Client tokens use the ct_live_ or ct_test_ prefix. Create and manage them in the Auth tab.

Restrict widget origins

Set Allowed Origins in the Auth tab to control which website origins can use the client token. Enter each origin with its scheme, such as https://example.com.

Use * to allow any origin. For production, list the exact origins that host the widget. Test tokens also allow localhost origins automatically.

Use React

If your application uses React, select React beside Script Tag in With Code. The Ship tab displays the React component code.

Verify the installation

To verify that the widget works, follow these steps:

  1. Save and deploy your HTML changes.
  2. Load the page that contains the script.
  3. Open the chat launcher.
  4. Send a message and confirm that the widget returns a response.

Troubleshoot the widget

Use the following checks when the widget does not work.

Widget does not appear

Check the following items:

  • Place the script before </body>.
  • Confirm that the client token is valid and active.
  • Check the browser console for errors.
  • Confirm that the Surface status is Active.

Widget appears but does not respond

Check the following items:

  • Confirm that the Product has active Capabilities.
  • Confirm that the page origin matches Allowed Origins.
  • Review execution logs for errors.

Next steps

Continue with these guides to customize and extend the widget: