Skip to navigation
Products & Surfaces

What are Surfaces?

Surfaces are interfaces that expose your Product 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 and Setting up a webhook Surface.

Each Surface type uses its own authentication:

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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: