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.

Before you begin, create a Product and decide which Capability handles text messages. Get an SMS-capable Twilio phone number and find your credentials in the Twilio Console.

In the production dashboard, SMS is unavailable. Use a staging or local dashboard to test the setup.

Create an SMS Surface

Create the SMS Surface and enter the Twilio credentials:

  1. Open the Product that you want to connect to SMS.
  2. Open Surfaces and click Add Surface.
  3. Under Messaging Channels, select SMS.
  4. Enter your Twilio Account SID and Auth Token. An Account SID starts with AC.
  5. Click Validate to verify the Twilio credentials.
  6. Enter your Twilio Phone Number in E.164 format, such as +18005550100.
  7. Click Save Changes.

Runtype uses the Auth Token to send messages through Twilio and verify inbound webhook signatures. The webhook rejects requests without a valid Twilio signature.

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.

Assign a Capability

Assign the Capability that processes inbound texts:

  1. In the Surface panel, open General.
  2. In Capability, select the Capability that you want to run.
  3. Click Save Changes.

For more information, see Adding capabilities to a Product.

Configure tool approvals

SMS has no approval controls. When an attached Agent uses Tool approval, reply to the approval request by text. Runtype interprets your reply as an approval or denial.

For a Runtype Agent, reply-based approval requires an Agent loop with Max turns set to 2 or higher. A Managed external Agent already executes through an effective Runtime Agent Loop and does not need an authored Agent Loop or Max turns setting. Runtype accepts an approval reply only after the inbound webhook verifies the reply with the Auth Token.

Do not reply with STOP or CANCEL to deny an approval. Twilio treats these single-word replies as opt-out keywords, not approval denials. For the full reply-based approval contract, 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. Confirm that your Product receives the message.
  3. Confirm that the response arrives by text.

Your SMS Surface is ready when the response arrives.

Troubleshoot the connection

Check these settings when a test message does not reach your Product:

  • 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.
  • Auth Token: verify that the saved Auth Token belongs to the Twilio account that owns the phone number.
  • Capability: select a Capability in the Surface panel and click Save Changes.

Next steps

Continue with these guides: