Twilio SMS Integration
Connect a phone number in your own Twilio account so AI agents can send and receive text messages, with Outermind checking that you own the number and handling delivery status automatically.
Watch: Twilio SMS: connecting your number, and what the page tells you (4:36)
What the Connector Does
The Twilio SMS integration connects one phone number from your own Twilio account to Outermind. Once connected:
- Agents can send texts from that number, but only after you turn on autonomous sends.
- A reply reaches the agent that texted that person. Other texts from people in your organization reach your default agent (see Who Can Text).
- Outermind points the number's incoming-message webhook at itself, confirms you own the number, and receives delivery status for every message it sends.
- Outermind never shows you the webhook secret it uses to verify incoming requests.
Your organization can have one SMS connection at a time, either Azure Communication Services or Twilio, not both. See Azure Communication Services SMS Integration if you already use that connector.
Before You Start
-
A Twilio account with an SMS-capable phone number.
-
The number registered for business messaging. Carriers block texts from unregistered numbers: a toll-free number needs toll-free verification, and a local US number needs an A2P 10DLC campaign. Complete this in your Twilio account before connecting.
-
An API key. A Restricted key is recommended, scoped to:
twilio/messaging/messages/createtwilio/phone-numbers/active-numbers/listtwilio/phone-numbers/active-numbers/readtwilio/phone-numbers/active-numbers/updatetwilio/messaging/services/listtwilio/messaging/services.phonenumbers/list
Outermind uses the last two to check where your incoming texts are routed.
A Standard key also works. Outermind never asks for your Auth Token.
Message content is processed by Twilio in the United States.
Connecting
- Go to Capabilities > Connections > + Add Connection and choose Twilio SMS. Once connected, it is listed under Capabilities > Connections.
- Fill in the connection fields:
| Field | Notes |
|---|---|
| Connection Name | A friendly label for this connection |
| Account SID | Starts with AC |
| API Key SID | Starts with SK |
| API Key Secret | Stored encrypted; Outermind shows only its last four characters afterward, never the full value again |
| Phone Number | E.164 format, for example +15551234567 |
| Default agent for incoming texts | Optional |
- Tick the checkbox "Outermind will receive all texts sent to this number" and click Connect.
This checkbox confirms you understand that Outermind replaces the number's incoming-message webhook in Twilio. Anything that used to receive texts sent to this number through that webhook stops receiving them until you disconnect the connection.
Updating the Connection
You can change the connection name, the API key, and the default agent. To change the API key, enter both the new API key SID and its secret. Leave both blank to keep the key already stored.
To change the phone number itself, disconnect the current connection and connect again with the new number.
Autonomous Sends
Agents cannot send texts from the connected number until you turn on autonomous sends. This setting is off by default, and turning it on asks you to confirm. Once enabled, messages your agents send are billed on your own Twilio account.
Who Can Text and How Replies Are Routed
A reply reaches the agent that texted that person in the last 30 days. A text from a number your agents have not texted reaches your default agent only when:
- the sender is a person in your organization who has opted in to SMS from their own profile; or
- the default agent is not a Personal Assistant and the number belongs to exactly one enabled user in your Microsoft Entra directory (their mobile or business phone). The agent sees that person's name marked as an unverified directory match and may text an answer back to that number only. Where SMS opt-in is available, the platform also sends that person (on a +1 number) one informational text from your number, at most once every 30 days, pointing them to the Mobile SMS opt-in on their Outermind Profile.
Any other text is ignored. A Personal Assistant answers only numbers it texted first or users who opted in to SMS from their own profile, so a directory match does not reach it.
Checking Incoming Texts
The connection page shows whether texts sent to your number will actually reach Outermind. It also runs a daily health check that re-verifies your credentials and the number, and marks the connection as in error, with a message explaining why, if something needs attention.
Working
Texts sent to the number reach Outermind.
A Messaging Service Is Overriding the Number
In Twilio, open Messaging Services, then the service that holds this number, then Integration, and turn on "Defer to sender's webhook." Outermind never changes your Messaging Services; you need to make this change yourself.
A TwiML App Is Overriding the Number
The number sends incoming texts to a TwiML App, so they do not reach Outermind. Select Rotate webhook secret to point the number back at Outermind, then Test connection to confirm.
The Number's Webhook No Longer Points at Outermind
Use Test connection to confirm, then Rotate webhook secret to re-point the number at Outermind.
Unknown
Outermind could not check where the number's incoming texts go. If you use a Restricted API key,
make sure it has twilio/messaging/services/list and twilio/messaging/services.phonenumbers/list
(see Before You Start), then use Test connection.
Test Connection and Rotate Webhook Secret
Test connection checks whether texts sent to your number currently reach Outermind and reports the result on the page.
Rotate webhook secret issues a new secret and re-points the number's webhook at Outermind with it. If Twilio is unavailable when you rotate, nothing changes and the current secret keeps working; select Rotate webhook secret again later.
Disconnecting
Disconnecting removes the connection, its tools, and every agent's access to it. Outermind also puts back the webhook the number used before it was connected, as long as the number's webhook still points at Outermind.
If the number's webhook no longer points at Outermind when you disconnect (for example, you pointed it at another system or a TwiML App in the Twilio Console), Outermind leaves it unchanged and the page tells you so.
If Outermind cannot restore the previous webhook, for example because the API key was revoked, the page tells you so. In that case, set the number's webhook back yourself in the Twilio Console, under the number's messaging configuration.