Products & Surfaces

Setting up a chat Surface

Use a chat Surface to expose your Product’s Capabilities through an embeddable chat widget. Configure the widget’s appearance, message routing, authentication, and embed code in the Runtype dashboard.

Before you begin

Create a Product and add at least one Capability before you generate embed code. A Capability is a Flow, Agent, or connected external Agent that handles requests from the Surface. To add a Capability, see Adding capabilities to a Product. If you need to create a Flow or Agent first, see Creating and editing Flows or Creating and configuring Agents.

Use the setup wizard

When you create a chat Surface, Runtype opens the Get Your Chat Live setup wizard. The wizard includes these three steps:

  1. Configure Agent: set the system prompt, choose a model, and add tools.
  2. Style Widget: choose a theme preset or customize the widget’s appearance.
  3. Ship: select a Client Token. If none exists, the wizard creates one automatically and displays the embed code.

Complete the steps in order. After you finish the wizard, return to the Surface panel to update the configuration.

Add a chat Surface to an existing Product

Follow these steps to add a chat Surface:

  1. Open Products in the sidebar, then select the Product that you want to update.
  2. In the Product surfaces section, click Add Surface.
  3. Select Chat Widget. The dashboard opens the Surface panel with tabs for configuring the chat widget.

Configure your chat Surface

Use the tabs in the Surface panel to configure your chat Surface.

Overview

Review the Surface status and edit its name. The tab also contains settings for the Surface, such as conversation titles and logging.

Endpoints

View the chat endpoint that your widget uses to communicate with the Runtype API. Runtype generates the endpoint for the Surface.

Orchestration

The Orchestration tab appears when the Surface has at least two Capabilities or a connected external Agent. Use it to choose how the Surface routes incoming messages. Choose one of the following modes:

  • Single Orchestrator: select one Capability to handle all incoming messages. This is the default mode.
  • Multi-Capability Router: use a lightweight model to classify each message and route it to a Capability. Choose the router model and add an optional routing prompt.

Start with Single Orchestrator for a Product with one Capability. Switch to Multi-Capability Router when you need to route messages among multiple Capabilities. For more information, see Surface orchestration modes.

WebMCP

Use the WebMCP tab to configure tools that the page embedding your widget exposes. Turn on Accept WebMCP tools, then choose Allow all tools or Use an allow-list to control which page tools the Surface accepts.

A chat widget can pause while the browser runs a WebMCP or other client tool, then resume through POST /v1/client/resume. It cannot host a human approval for a server-side tool. If its attached Flow or Agent can reach a human approval gate, Client Chat rejects the request before execution with HTTP 501 and code APPROVAL_MODE_UNSUPPORTED.

Auth

Use the Auth tab to manage Client Tokens and their allowed origins. Client Tokens authenticate browser widgets in client-side code, so you can expose them in your widget code. Use Allowed Origins to restrict the origins that can use each token.

Use the following controls to manage Client Tokens:

  • Create a token: click Create Token, enter a name in Token Name, add origins in Allowed Origins, then click Create Token again.
  • Restrict origins: add exact origins, wildcard subdomains, or localhost origins in Allowed Origins.
  • Invalidate a token: delete it from the token list. Widgets that use the deleted token stop working.

Ship

Use the Ship tab to customize the widget and generate embed code.

The Widget Appearance section opens the Chat Style Editor when you click Customize. Adjust colors, typography, layout, launcher position, and widget behavior. You can also generate a theme from a website URL or a description. Use the preview to review changes before you save them.

In With Code mode, select a Client Token, then choose an embed format:

  • Script Tag: paste the generated snippet before the closing </body> tag on your website.
  • React: use the generated React component in a React application.

If you do not have a Client Token, create one in the Auth tab before you generate embed code.

Next steps

Continue with one of these guides: