> For the full page index, fetch https://echonova.ai/llms.txt # SMS with Twilio What a connected Twilio number gives an agent on the text side, what the Send SMS action does, and what happens to a text message sent to the number. A Twilio phone number connected to an agent is the agent's phone line and the number its **Send SMS** action sends from. One connection covers both. This page is the text side: what **Send SMS** does, what happens to a text message someone sends to the number, and how the connection is made. Calls on the same number are covered in [Voice with Twilio](/docs/agents/voice-twilio). ## What the agent can do on SMS | Capability | Supported | | ---------- | ------------------------------------------------------------------------------------------ | | Voice | Yes, on the same connection. See [Voice with Twilio](/docs/agents/voice-twilio) | | Text | Outbound only, through the **Send SMS** action | | Inbound | A text sent to the number is not answered by the agent | | Outbound | Yes. One message per **Send SMS** call, sent from the connected number to any phone number | | Handoff | No | | Media | No. Text only | ## Prerequisites on the provider side - A Twilio account, and its **Account SID** and **Auth Token**, both shown on the [Twilio Console](https://www.twilio.com/docs/iam/api/account) home page at twilio.com/console. Connecting signs in to Twilio with them. - A phone number that belongs to that Twilio account. Connecting looks the number up in the account and refuses a number that is not there. - The number must not already be connected anywhere in EchoNova. A phone number can be connected once, to one agent. > [!WARNING] > The Auth Token gives full control of your Twilio account. Paste it only into > the **Auth Token** field of the connect dialog. Never put it in the agent's > **Personality** box, a tool description or a knowledge document, because > those are read by the agent on every turn. ## Connect Twilio uses one connect form for calls and text. Connecting once gives the agent both. ### Step 1: Open the Channels tab and choose Twilio Open the agent and select **Channels**. Press **Add Channel**. The catalog lists Twilio under **Voice & Telephony** with the line **Voice and text messages**. Select it. ![The Add Channel catalog with the Twilio card](/docs/images/agents/sms-twilio/1.png) ### Step 2: Fill in the Configure tab The dialog is titled **Connect Twilio Account**. Its **Configure** tab takes five fields, all required: - **Name**: the label shown in the Channels list, for example `Support line`. - **Credential**: one option, **Twilio API key**. Leave it as it is. - **Phone number**: the Twilio number, with its country code. The placeholder is `+15551234567`. Spaces and dashes are accepted and removed; the number is kept in the compact international form. - **Account SID**: from your Twilio account. - **Auth Token**: from your Twilio account. The field hides what you type. **Connect** stays disabled until **Name**, **Phone number**, **Account SID** and **Auth Token** all have a value. ![The Connect Twilio Account dialog on the Configure tab](/docs/images/agents/sms-twilio/2.png) ### Step 3: Read the Triggers and Tools tabs The **Triggers** tab holds one card, **Incoming calls**, with the line **Calls to this number reach the connected agent.** The **Tools** tab is headed **Actions available through your Twilio integration.** and holds one card, **Send SMS**, with the line **Send a text message to any phone number from your connected number.** ### Step 4: Press Connect Connecting signs in to Twilio, checks that the number is in the account, and points the number at EchoNova by setting its voice and messaging webhooks for you. There is nothing to paste into the Twilio console. > [!NOTE] > Connecting replaces whatever the number's voice and messaging webhooks > pointed at before. If the number served another application, that > application stops receiving the number's calls and texts. On success a toast reads **Channel connected** and the row appears under **Voice & Telephony** with your **Name**, the number under **Phone number**, **Twilio** under **Routing**, and the chip **Active**. ## Send SMS **Send SMS** is an integration tool: an action that comes ready-made from the connection and sends from the connected number. Its description, the text the agent reads to decide when to use it, is **Send an SMS text message from the connected Twilio number.** It takes two values, both required: | Parameter | What the agent fills in | | --------- | ---------------------------------------------------- | | `to` | Recipient phone number in E.164 (e.g. +15551234567). | | `body` | The text message body to send. | The message is sent from the connected number to `to`. When Twilio refuses the message, the agent is told the send failed and answers from that. There is no control in the portal today that adds **Send SMS** to an agent; the **Tools** tab of the connect dialog describes the action. Sending a message costs nothing in credits by itself. The turn that called the tool is charged like any other turn; see [What a turn costs](/docs/agents/what-a-turn-costs). Twilio's own charge for the message is billed by Twilio to your account. ## Incoming texts A text message sent to the connected number is received by Twilio and is not answered by the agent, and it does not appear in **Conversations**. For a two-way text conversation with the agent, connect a text channel: [WhatsApp](/docs/agents/whatsapp-connect), [Messenger](/docs/agents/messenger), [Instagram](/docs/agents/instagram), [Slack](/docs/agents/slack) or a helpdesk. ## Provider limits that affect you | Limit | Value | Effect | | ---------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Connections per phone number | 1 | A number already connected, in any EchoNova workspace, is refused with **Phone number "..." is already connected**, with the number in place of the dots | | Message format | Plain text | **Send SMS** takes a text body and nothing else | ## Disconnect Open the row's actions menu and choose **Disconnect**. The dialog **Disconnect channel?** names the connection and reads **This permanently deletes Support line and its saved credential. Reconnecting later starts a brand new connection. Disconnecting gives the number's call and SMS settings back to what they were.** A toast reads **Channel disconnected**. The Account SID and Auth Token are removed from EchoNova. EchoNova puts the number's voice and messaging webhook URLs back to what they were before you connected it; a number that had none is left with none. Each webhook is checked on its own: one you already pointed somewhere else in the Twilio console is left as it is. > [!TIP] > If Twilio can't be reached at the moment you disconnect, the channel is > still removed. Check the number's webhooks in the Twilio console afterwards. ## Troubleshooting Every connect failure is shown as an **Error** toast carrying the reason. ### Invalid Twilio credentials Twilio rejected the **Account SID** and **Auth Token** pair. Copy both again from the same Twilio account and retry. ### That number isn't in this Twilio account The number is not owned by the account whose credentials you entered, or it was typed differently from how Twilio lists it. Check the country code. ### Phone number "..." is already connected The toast carries the number in place of the dots. The number is connected already, in this workspace or another one. Disconnect it there first. To move it between two of your own agents, use **Assign to another agent** on the existing row instead of connecting again. ### Could not reach Twilio Twilio did not answer; the toast carries the reason after the colon. Retry in a moment. ### Failed to configure Twilio webhooks Twilio refused the change to the number. The toast carries Twilio's own reason when Twilio gives one. Check that the credentials belong to the account that owns the number, then retry. ## FAQ ### Does the agent reply when someone texts the number? No. See **Incoming texts** above for the channels that carry a two-way text conversation. ### Can the agent text a caller during a phone call? That is what **Send SMS** is for: the agent sends a message from the connected number to any phone number it is given. See **Send SMS** above for what the portal offers for it today. ### Can I connect one Twilio number to two agents? No. A number is connected to one agent. To move it, open the row's actions menu and choose **Assign to another agent**. ### Do I need a separate connection for SMS and for calls? No. The same **Connect Twilio Account** dialog covers both, and one row in the Channels list carries both. ### What does Twilio charge? Twilio bills your own Twilio account for calls and messages on the number. EchoNova charges the conversation per turn, and a **Send SMS** call adds no charge of its own. ## Related - [Voice with Twilio](/docs/agents/voice-twilio): the call side of the same connection - [Channels overview](/docs/agents/channels-overview): every channel side by side, and which one to launch first - [Tools overview](/docs/agents/tools-overview): what an integration tool is and how the agent decides to call one - [What a turn costs](/docs/agents/what-a-turn-costs): what a turn that calls a tool is charged - [Secrets](/docs/agents/secrets): where credentials belong when a tool of your own needs one - [Agent status](/docs/agents/agent-status): what pausing an agent does and does not do to a connected number