> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # What are Surfaces? Surfaces are interfaces that expose your [Product](/user-guide/products-surfaces/what-are-products) Capabilities to people, applications, and AI systems. Add a Surface to expose the same Flow, Agent, or external Agent through a chat widget, a REST API, a Model Context Protocol (MCP) server, or a messaging channel. ## How Surfaces work Connect each Surface to a Product. When a request or message arrives through a Surface, the Surface routes it to an attached Capability. You can add multiple Surfaces to one Product. Each Surface has a status: **Draft**, **Active**, or **Paused**. **Active** Surfaces accept requests. **Draft** and **Paused** Surfaces keep their configuration but reject most requests. The following exceptions apply to Draft Surfaces: * A Draft Webhook Surface accepts events so that it can learn a payload schema. * A Draft Email Channel accepts messages from the email address of the Product's owner, so that the owner can test it. A request to a chat, API, MCP, or A2A Surface that is not Active fails with an error that says the Surface is not active. A request to a paused Webhook Surface fails with a `SURFACE_PAUSED` error. To accept requests again, set the Surface to **Active**. Webhook Surfaces also show setup states, such as **Listening**, **Schema Proposed**, and **Drift Detected**. For more information, see [Product versioning and status](/user-guide/products-surfaces/product-versioning-and-status) and [Setting up a webhook Surface](/user-guide/products-surfaces/setting-up-a-webhook-surface). Each Surface type uses its own authentication: * Chat widgets use [Client Tokens](/user-guide/products-surfaces/client-tokens-and-domain-restrictions). * API and A2A Surfaces use [API keys](/user-guide/products-surfaces/authenticating-with-product-api-keys), which you can [scope to Capabilities](/user-guide/products-surfaces/scoping-api-keys-to-capabilities). * MCP Surfaces support OAuth, API keys, or public access. For more information, see [MCP authentication](/user-guide/products-surfaces/mcp-authentication). * Messaging Surfaces use channel-specific provider settings. ## Surface types Choose a Surface based on how you want people or systems to interact with your Product. The following sections describe each type and link to setup guides where they exist. ### Chat widget Embed a conversational interface in your website or web app. Customize the theme, welcome message, and branding. Use a **Chat Widget** for customer support, sales assistance, onboarding, or interactive demos. To create one, see [Setting up a chat Surface](/user-guide/products-surfaces/setting-up-a-chat-surface). ### REST API Expose HTTP endpoints that developers can call from applications and backend services. Runtype generates an OpenAPI specification for each API Surface. Configure rate limits and API keys to control access. To create one, see [Setting up an API Surface](/user-guide/products-surfaces/setting-up-an-api-surface). ### MCP server Expose your Capabilities as tools that MCP-compatible clients can discover and call. Connect your MCP Surface to clients such as Claude Desktop, Cursor, and VS Code. To create one, see [Setting up an MCP Surface](/user-guide/products-surfaces/setting-up-an-mcp-surface). ### A2A agent Expose your Capabilities to external agents through the Agent-to-Agent (A2A) protocol. External agents discover your Product through an Agent Card and invoke Capabilities through a JSON-RPC endpoint. Use an **A2A Agent** for multi-agent workflows and agent orchestration. To create one, see [Setting up an A2A Surface](/user-guide/products-surfaces/setting-up-an-a2a-surface). ### Slack Connect your Product to a Slack workspace. People interact with your Capabilities through direct messages, mentions, channels, and threaded replies. Use Slack for internal tools, team assistants, and support workflows. To create one, see [Setting up a Slack Surface](/user-guide/products-surfaces/setting-up-a-slack-surface). ### SMS Connect your Product to a Twilio phone number. People interact with your Capabilities through text messages. The dashboard shows **SMS Channel** as **Coming Soon**, so you can't create an SMS Surface there. For more information, see [Setting up an SMS surface](/user-guide/products-surfaces/setting-up-an-sms-surface). ### iMessage Connect your Product to a Sendblue phone number. People interact with your Capabilities through iMessage, with SMS fallback when a recipient cannot receive iMessage. The dashboard shows **iMessage Channel** as **Coming Soon**, so you can't create an iMessage Surface there. For more information, see [Setting up an iMessage surface](/user-guide/products-surfaces/setting-up-an-imessage-surface). ### Telegram Connect your Product to a Telegram bot. People interact with your Capabilities through messages in Telegram. Use Telegram for customer support, notifications, and group management. In a group or supergroup, the bot answers only messages that mention it or reply to it. To answer every message, set `inbound.channelResponseMode` to `always`. To let a judgment model decide whether to reply to each other message, set it to `judge`. The modes work as they do on a Slack Surface. For more information, see [Choose how the Surface responds](/user-guide/products-surfaces/setting-up-a-slack-surface#choose-how-the-surface-responds). When the bot answers in a group, it also receives recent group messages that it did not answer, as context only. The `inbound.contextBackfill` setting controls these messages. Set `mode` to `window` (the default) to include the recent messages, to `judged` to include only the messages that a judgment model finds necessary, or to `none` to include no earlier messages. If the judgment fails, `judged` mode includes the messages that `window` mode includes. Unlike on Slack, the `maxMessages` limit (default and maximum 20) and the `maxAgeMinutes` limit (default 360, maximum 1440) also apply in `window` mode. ### Email channel Connect your Product to email. People interact with your Capabilities by sending and receiving messages. Use an **Email Channel** for customer communication, support workflows, and automated email responses. ### Webhook Receive HTTP events from external systems and route them to your Capabilities. A Webhook Surface can learn a payload schema from sample events, verify provider signatures, route event types, and map payload fields to Flow inputs. To create one, see [Setting up a webhook Surface](/user-guide/products-surfaces/setting-up-a-webhook-surface). ### Chrome extension Build a downloadable Manifest V3 browser extension with chat in a side panel. Configure packaged browser tools for reading pages, filling forms, navigating tabs, using the clipboard, and showing notifications. Actions that change a page require confirmation. Build the extension ZIP from the Surface's **Ship** tab, then load it in Chrome or publish it to the Chrome Web Store. **Chrome Extension** is not available on every account. If it does not appear in the Surface type list, you can't create one. For the setup steps, see [Setting up a Chrome extension Surface](/user-guide/products-surfaces/setting-up-a-chrome-extension-surface). ### Messaging conversations On messaging Surfaces, you can take over a conversation from the Agent and reply from the dashboard. While you have the conversation, the Agent does not reply. For more information, see [Reply to a conversation yourself](/user-guide/products-surfaces/product-views#reply-to-a-conversation-yourself). When an attached Agent uses **Tool approval**, each messaging channel collects the decision in its own way. For more information, see [Approvals on messaging surfaces](/user-guide/products-surfaces/approvals-on-messaging-surfaces). ## Surfaces and Capabilities Connect the Capabilities that each Surface exposes. A Capability can connect to multiple Surfaces, so you can reuse the same logic across different interfaces. You can enable or disable a Capability separately for each Surface. For setup details, see [Adding capabilities to a Product](/user-guide/products-surfaces/adding-capabilities-to-a-product). Chat Surfaces support these orchestration modes: * **Single Orchestrator**: send every request to one selected Capability. * **Router**: use a lightweight model to classify each request and route it to the relevant Capability. API Surfaces expose each enabled connected Capability through an endpoint. MCP Surfaces expose each enabled connected Capability as a tool. A2A Surfaces list each Capability as a skill on the Agent Card, and the calling Agent selects the skill. Turn on the **Orchestrator Skill** switch to also add a skill that routes each request to a Capability for the caller. For more information, see [Surface orchestration modes](/user-guide/products-surfaces/surface-orchestration-modes). ## Example Dana runs a customer-support Product with an order lookup Agent and an FAQ Flow. Dana connects both Capabilities to a Chat Widget and a REST API. On the Chat Widget, Dana selects **Router**, so each website message goes to the order lookup Agent or the FAQ Flow. On the REST API, the mobile app calls each Capability's endpoint directly. ## Next steps Follow these guides to create and configure a Surface: * [What is Runtype?](/): get an overview of the platform * [Creating a Product](/user-guide/products-surfaces/creating-a-product): organize your Capabilities and Surfaces * [Adding capabilities to a Product](/user-guide/products-surfaces/adding-capabilities-to-a-product): connect Flows and Agents to Surfaces * [Surface orchestration modes](/user-guide/products-surfaces/surface-orchestration-modes): choose how each Surface routes requests * [Setting up a chat Surface](/user-guide/products-surfaces/setting-up-a-chat-surface): embed a chat experience * [Setting up an API Surface](/user-guide/products-surfaces/setting-up-an-api-surface): expose REST endpoints * [Setting up an MCP Surface](/user-guide/products-surfaces/setting-up-an-mcp-surface): connect AI clients to your tools * [Setting up an A2A Surface](/user-guide/products-surfaces/setting-up-an-a2a-surface): connect external agents * [Setting up a Slack Surface](/user-guide/products-surfaces/setting-up-a-slack-surface): answer messages in Slack * [Setting up a webhook Surface](/user-guide/products-surfaces/setting-up-a-webhook-surface): trigger Capabilities from external events * [Setting up a Telegram surface](/user-guide/products-surfaces/setting-up-a-telegram-surface): connect a Telegram bot to a Product * [Setting up an email surface](/user-guide/products-surfaces/setting-up-an-email-surface): receive and reply to email through a Product * [Taking over messaging conversations](/user-guide/products-surfaces/taking-over-conversations): take over a conversation from the Agent and hand it back