For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dashboard
User GuideDeveloper GuidesAPI Reference
User GuideDeveloper GuidesAPI Reference
  • Getting Started
    • What is Runtype?
    • Creating your account
    • Platform Keys vs. BYOK
    • Understanding the Runtype UI
    • Quickstart: Social Media Post Generator
    • Quickstart: From Agent to Chat Widget
  • Dashboard
    • What is the Dashboard?
    • Daily Executions
  • Playground
    • What is the Playground?
  • Products & Surfaces
    • What are Products?
    • What are Surfaces?
    • Creating a Product
    • Setting up a Chat Surface
    • Setting up an API Surface
    • Setting up an MCP Surface
    • Setting up an A2A Surface
    • Setting up a Slack Surface
    • MCP authentication
    • Authenticating with product API keys
    • Embedding the chat widget (script tag)
    • Embedding the chat widget (React)
    • Surface orchestration modes
    • Product views
    • Adding Capabilities to a product
    • Connecting external agents
    • How A2A works
    • Connecting to Cursor / VS Code
    • Connecting to Claude Desktop
    • Scoping API keys to capabilities
    • Auto-generated OpenAPI spec
    • Calling your API endpoints
    • Client tokens and domain restrictions
    • AI-powered theme generation
    • Widget theming and customization
    • Product versioning and status
  • Flows
    • What are Flows?
    • Creating and Editing Flows
    • Flow step types overview
    • Agent and Flow Templates
    • Using prompt steps
    • Using transform-data steps
    • Using conditional steps
    • Using fetch-url and api-call steps
    • Using record steps (upsert/retrieve)
    • Flow variables and templates
    • Flow versioning and publishing
    • Running flows in batch
    • Handling batch failures
    • Debugging flows
  • Agents
    • What are Agents?
    • Creating and configuring Agents
    • Agent tools
  • Records
    • What are Records?
    • Creating and managing records
    • Using records in flows
    • Filtering and searching records
  • Tools
    • What are Tools?
    • Built-in Tools
    • Creating custom tools
    • Creating external tools
    • Runtime tools
  • Evals
    • What are Evals?
    • Running an Eval
    • Interpreting eval results
  • Schedules
    • What are Schedules?
    • Automating batch processing
  • Logs
    • What are Logs?
    • Working with Logs
  • Integrations
    • Connecting AI model providers
    • Slack integration
    • Google Workspace integration
    • GitHub integration
    • Linear integration
    • Weaviate (vector search)
    • Firecrawl (web scraping)
    • Exa (web search)
  • Settings
    • What's in Settings?
    • Available AI models
    • What are Organizations?
    • Managing AI models
    • Managing API keys
    • Billing and plans
    • Usage data
    • Team members and permissions
    • Appearance and preferences
    • Integrations (PostHog, Weaviate, Daytona)
  • Troubleshooting & FAQ
    • FAQ
    • Rate Limits and Usage
    • Managing Runtype with Claude
    • Flow execution failures
    • Common errors and solutions
    • Authentication issues
Dashboard
LogoLogo
On this page
  • Getting the embed code
  • Installation steps
  • Widget configuration
  • Client Tokens
  • Domain restrictions
  • React integration
  • Troubleshooting
  • Next steps
Products & Surfaces

Embedding the chat widget (script tag)

Was this page helpful?
Previous

Embedding the chat widget (React)

Next
Built with

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

  • Embedding the chat widget (React) for React apps
  • Widget theming and customization
  • Client tokens and domain restrictions