> 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.

# Setting up an SMS surface

Connect a Twilio phone number to a Product with an SMS Surface. Runtype routes inbound texts to your Product and sends responses as SMS.

> **Note**
>
> In the production dashboard, **SMS Channel** shows **Coming Soon** and you can't select it, so you can't create an SMS Surface there.

## Before you begin

Make sure that you have these items:

* A Product.
* The Capability that handles text messages.
* An SMS-capable Twilio phone number.
* Your Twilio **Account SID** and **Auth Token** from the [Twilio Console](https://console.twilio.com).

## Create an SMS Surface

Create the SMS Surface and configure it in one pass:

1. Open the Product that you want to connect to SMS.
2. Open **Surfaces** and click **Add Surface**.
3. Under **Messaging Channels**, select **SMS Channel**. The Surface panel opens on the **General** tab.
4. Click the **Inbound** tab.
5. Enter your Twilio **Account SID** and **Auth Token**. An Account SID starts with `AC`.
6. Click **Validate** to verify the Twilio credentials.
7. Enter your Twilio **Phone Number** in E.164 format, such as `+18005550100`.
8. Optional: Click the **Outbound** tab and enter an **Error Message** to replace the default error reply.
9. Click the **General** tab. In **Capability**, select the Capability that you want to run.
10. In **Status**, select **Active**. A new Surface starts as **Draft**, and only an active Surface accepts inbound texts.
11. Click **Save Changes**.

Runtype uses the **Auth Token** to send messages through Twilio and to verify that inbound texts come from Twilio.

The **Outbound** tab also has a **Welcome Message** field. Runtype saves it but doesn't send it on an SMS Surface.

For more information about Capabilities, see [Adding capabilities to a Product](/user-guide/products-surfaces/adding-capabilities-to-a-product).

## Configure the Twilio webhook

Configure Twilio to send inbound texts to Runtype:

1. In the Surface panel, open **General** and copy the **Webhook URL**.
2. In the Twilio Console, open **Phone Numbers > Manage > Active numbers**, then open your number.
3. Under **Messaging Configuration**, set **A message comes in** to **Webhook**, paste the URL, and select **HTTP POST**.
4. Click **Save configuration**.

## How replies are delivered

Runtype sends replies as plain text and doesn't convert Markdown, so formatting characters such as `**` appear in the text. It sends no images or files, and it cuts off a reply longer than 1,600 characters and ends it with `...`. Ask for short, plain-text answers in the instructions of the Capability that handles texts.

Each sending phone number gets its own conversation. When the Surface has one enabled Capability, or one Surface item marked as the entry point, that Capability answers every text. Otherwise, a billed routing judgment chooses a Capability, and the conversation keeps that Capability. For details, see [Surfaces with several Capabilities](/user-guide/products-surfaces/setting-up-a-slack-surface#surfaces-with-several-capabilities).

## Approve tool calls by text

When an attached Agent uses [**Tool approval**](/user-guide/agents/creating-and-configuring-agents), Runtype sends the approval request by text. Reply `YES` to approve or `NO` to deny.

For a Runtype Agent, reply-based approval requires an **Agent loop** with **Max turns** set to 2 or higher. A Managed external Agent already supports multi-turn tool approval and doesn't need an **Agent loop** or **Max turns** setting. Reply-based approval also requires a saved **Auth Token**.

Don't reply `STOP` or `CANCEL` to deny an approval. Carriers treat these words as opt-out commands. The approval stays unresolved, and your number stops receiving messages. For the full reply rules, see [Approvals on messaging surfaces](/user-guide/products-surfaces/approvals-on-messaging-surfaces).

## Test the connection

Use these steps to verify the connection:

1. Send a text to your Twilio number from your phone.
2. In the Product, open **Activity** and confirm that a conversation from your phone number appears.
3. Confirm that the response arrives by text.

Your SMS Surface is ready when the response arrives.

## Troubleshoot the connection

If a test message doesn't reach your Product, check these settings:

* **Status**: set the Surface **Status** to **Active**. Draft, Paused, and Archived Surfaces don't accept inbound texts.
* **Webhook URL**: copy the URL from the Surface panel and confirm that Twilio uses it.
* **HTTP method**: select **HTTP POST** for **A message comes in**.
* **Rejecting events**: if the channel shows **Rejecting events** in the product editor, Twilio's signature didn't match the saved **Auth Token**, or a proxy removed Twilio's signature header. Save the **Auth Token** of the Twilio account that owns the phone number, and point Twilio directly at the **Webhook URL**. Rejected texts don't appear in **Logs**. For more information, see [Inbound webhook rejected](/user-guide/troubleshooting-faq/common-errors-and-solutions#inbound-webhook-rejected).

If you receive an error reply instead of an answer, check these settings:

* **Capability**: select a Capability in the Surface panel and click **Save Changes**.
* **Debug Mode**: while you test, turn on **Debug Mode** on the **Outbound** tab. Runtype adds the error details to the error reply. Turn it off before real users text the number.

## Next steps

Continue with these guides:

* [Approvals on messaging surfaces](/user-guide/products-surfaces/approvals-on-messaging-surfaces): configure reply-based approval over SMS.
* [Setting up an iMessage surface](/user-guide/products-surfaces/setting-up-an-imessage-surface): connect a Sendblue number for iMessage conversations.
* [What are Surfaces?](/user-guide/products-surfaces/what-are-surfaces): review the available Surface types.
* [Surface orchestration modes](/user-guide/products-surfaces/surface-orchestration-modes): compare how each Surface type picks a Capability.