Runtype
Products & Surfaces

Setting up a chat Surface

A chat Surface makes your Flows and Agents accessible through an embeddable widget on your website. Before adding a chat Surface, you need to create a Product and add Capabilities to it.

When creating a new Product with a Chat Surface, it'll show a Get Your Chat Live setup guide with steps to configure your capability, style the chat widget, and then ship it.

Add a chat Surface to your Product

  1. Navigate to Products in the sidebar and open your Product.

  2. In the Surfaces section, click Add surface.

  3. Select Chat as the Surface type.

  4. Click Save.

The Surface side panel opens with tabs: Overview, Endpoints, Orchestration, Auth, and Ship.

Configure your chat Surface

Use the tabs to set up orchestration, authentication, theming, and deployment. Here's what each tab controls:

Overview

Shows your Surface status and key information. Use this to verify configuration before deploying.

Endpoints

Displays the technical endpoints your chat widget uses to communicate with Runtype. These are managed automatically—you don't configure them.

Orchestration

Control how user messages are routed to your Capabilities. Open the Orchestration tab to choose a mode:

  • Single Orchestrator — One Capability handles all messages. For Single Orchestrator mode, select which Capability handles requests. This is the default and recommended for single-Capability Products.

  • Multi-Capability Router — The AI routes each message to the best Capability. Configure the router model and optionally add a custom routing prompt.

Learn more in Surface orchestration modes.

Auth

Manage client tokens and domain security. Client tokens authenticate your chat widget and are public by design. In the Auth tab, you can:

  • Create or edit client tokens — Click Create Client Token or edit an existing one.

  • Set Allowed Origins — Restrict where your chat widget can be embedded. Add specific domains (e.g., example.com), use wildcards for subdomains (e.g., *.example.com), and include localhost for local development.

  • Rotate tokens — If a token is compromised, click Rotate Token to invalidate the old one. Update your embed code immediately—old tokens stop working after rotation.

See Client tokens and domain restrictions for details.

Ship

Get your embed code and customize the widget appearance. The Ship tab has two main sections:

Widget Appearance — Customize your chat widget's look to match your brand:

  • Colors — Configure the widget color scheme using hex codes or the color picker

  • Typography — Customize fonts and text sizing

  • Positioning — Control where the widget appears on the page

  • Styling — Adjust the chat bubble and header appearance

  • Mobile behavior — Decide how the chat operates on mobile devices

  • Custom CSS — Expand for complete control with your own styles

You can also start with a theme template (Modern, Classic, Vibrant, or Corporate) or use AI-powered theme generation. Preview changes in the preview panel, then click Save.

See Widget theming and customization for advanced options.

Embed Code — In the Ship tab, select or create a client token (create one in the Auth tab if needed). Copy the embed code from the Script Tag or React tab and add it to your website before the closing </body> tag.

If no client token exists, the Ship tab shows "No client token — Create one in the Auth tab to generate embed code."

For React applications, see Embedding the chat widget (React). For detailed script tag instructions, see Embedding the chat widget (script tag).

Next steps

After setting up your chat Surface:

Was this helpful?