Skip to navigation
Products & Surfaces

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.

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.

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.

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.

Approve tool calls by text

When an attached Agent uses Tool approval, 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.

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.

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: