Products & Surfaces

Embedding the chat widget (script tag)

The simplest way to add the Runtype chat widget to your website is with a script tag. This works on any HTML page without framework dependencies.

Getting the embed code

  1. Open your Product and select the chat Surface.
  2. Go to the Ship tab.
  3. Select the JavaScript tab.
  4. Select or create a Client Token.
  5. Copy the generated script snippet.

The snippet includes a CDN-hosted script and an initialization call configured with your Client Token, theme, and API URL. Paste it before the closing </body> tag on any page where you want the chat widget.

Installation steps

  1. Copy the script from your chat Surface’s Ship tab.
  2. Open your website’s HTML file or template.
  3. Paste the script before </body>.
  4. Save and deploy your changes.
  5. Load the page to see the chat widget.

Widget configuration

The generated embed code calls initAgentWidget() from the @runtypelabs/persona package with your configuration. The Ship tab lets you customize:

  • Theme — Colors, borders, launcher position, and styling
  • Welcome message — The first message users see
  • Launcher — Position and style of the chat bubble

Changes you make in the Ship tab are reflected in the generated embed code.

Client Tokens

Chat widgets use Client Tokens for authentication instead of API keys. Client Tokens are:

  • Public — Safe to expose in client-side code
  • Scoped — Limited to a specific Surface
  • Domain-restricted — Can be restricted to approved domains via Allowed Origins

Client Tokens use the ct_live_ or ct_test_ prefix. Create and manage them in the Auth tab of your chat Surface.

Domain restrictions

Configure which domains can use your chat widget by setting Allowed Origins in the Auth tab. The widget only works on approved domains.

React integration

For React applications, copy the embed code from the React tab in the Ship tab instead. See Embedding the chat widget (React).

Troubleshooting

Widget not appearing:

  • Check that the script tag is before </body>
  • Verify the Client Token is valid
  • Check browser console for errors
  • Confirm the Surface status is Active

Widget appears but does not respond:

  • Verify the Product has active Capabilities
  • Check Allowed Origins in the Auth tab
  • Review execution logs for errors

Next steps