> For the full page index, fetch https://echonova.ai/llms.txt # Voice with Twilio Put an agent on a Twilio phone number so that callers reach it, and know what the caller hears, which settings apply on the call, and what ends it. Connect a Twilio phone number and the agent answers every call to it. The call is the same conversation as a **Call** in the playground: the agent speaks in its own voice, follows its **Personality**, uses its tools and knowledge, and the transcript lands in **Conversations**. The same connection also gives the agent a number to text from; that side is covered in [SMS with Twilio](/docs/agents/sms-twilio). ## What the agent can do on a Twilio number | Capability | Supported | | ---------- | ---------------------------------------------------------------------------------------------- | | Voice | Yes. Inbound calls, answered live | | Text | Outbound only, through the **Send SMS** action. See [SMS with Twilio](/docs/agents/sms-twilio) | | Inbound | Yes. Every call to the connected number | | Outbound | No. The agent does not place calls | | Handoff | No. The agent cannot transfer a call or dial a person in | | Media | Speech only. Keypad tones are not read | ## 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. - Credits on the workspace. A call is refused when the balance is empty; see **What the caller hears** below. > [!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 ### 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/voice-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 **Triggers** tab holds one card, **Incoming calls**, with the line **Calls to this number reach the connected agent.** ![The Connect Twilio Account dialog on the Configure tab](/docs/images/agents/voice-twilio/2.png) ### Step 3: 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**. The number is live from that moment: the agent it is connected to answers the next call. ## Get it right Connect the number to the agent you have already tested in the playground, not to a fresh one. A call is a real conversation and is charged from the first turn, and a caller cannot be handed to a person. **Recommended** - Test the agent with **Call** in the playground until the greeting, the language rule and the tools behave, then connect the number to that agent. - Write what the agent should do when it cannot help into **Personality**, such as reading out an opening hours line or a number to call back, since the agent cannot transfer the call. **Less effective** - Connecting the number first and tuning the agent on live calls. Every call in between is answered as it is, and charged. ## What the caller hears The call is answered and opens with the agent's **Greeting message**, spoken in the agent's default voice. When no greeting is saved, the agent opens with a line of its own. The caller hears **Sorry, this number is not available right now. Goodbye.** and the call ends, without reaching the agent, when the workspace has no credits left. ## Which settings apply on the call Everything the agent has when you press **Call** in the playground: | Setting | On a phone call | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Personality** and **Greeting message** | Used as saved. See [Write the persona](/docs/agents/persona) | | The **Voice** tab | The default voice opens the call. Speed, guidance and diacritization apply per voice. See [Voices and language](/docs/agents/voice-and-language) | | **Dialect detection** | Switches to the matching voice mid-call when it is on | | **End conversation** | Lets the agent hang up itself when it is on. See [End conversation](/docs/agents/system-tool-end-conversation) | | Knowledge and tools | Searched and called as on any voice conversation | | Model and reasoning effort | As set on the agent | A change you save applies to the next call. A call already running keeps the settings it started with. ## Take the first call Dial the connected number from any phone. The agent greets you, and you talk as you would in the playground. In the agent's **Conversations** tab the call appears with a phone icon, the channel **Twilio**, and Twilio's call id in place of a customer name. Open it to read the transcript; the **Conversation Overview** panel shows **Turns** and **Call duration** once the call has ended. See [Conversations](/docs/agents/conversations). Each turn is charged at the voice rates in [What a turn costs](/docs/agents/what-a-turn-costs). Twilio bills your own Twilio account for the call minutes. ## What ends a call - The caller hangs up. - The agent hangs up, when **End conversation** is on and its description allows it. - The balance runs out mid-call. The turn that cannot be charged is the last one and the conversation's status reads `out_of_credits`. Pausing the agent does not end or refuse calls: a number connected to a paused agent keeps answering and charging. To stop the number, disconnect it or assign it to another agent. See [Agent status](/docs/agents/agent-status). ## Move the number to another agent Open the row's actions menu and choose **Assign to another agent**. The dialog reads **Choose the agent that should receive Support line.**, with your connection's name in place of Support line, and warns **Open conversations on this channel will be closed. History stays with this agent.** Pick an agent and press **Assign**. A toast reads **Assigned to** followed by the agent's name. The next call reaches the new agent. A call already in progress finishes with the agent it started with. ## 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 and a call already in progress finishes. 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. ### The caller hears "Sorry, this number is not available right now. Goodbye." The workspace has no credits. Top up, then call again; nothing needs to be reconnected. ### Calls stopped working after I changed the Auth Token in Twilio Every call is checked against the Auth Token saved at connect time, so a rotated token makes Twilio's calls fail the check and the caller hears Twilio's own error. Disconnect the number and connect it again with the new token. ### Twilio plays an error and the call ends The number points at EchoNova but is no longer connected, or the connection's Auth Token no longer matches Twilio's. Connect the number again. ## FAQ ### Can the agent transfer the caller to a person? No. A call stays with the agent until someone hangs up. Write into **Personality** what the agent should say when a person is needed, such as a callback number or opening hours. ### Which voice does the caller hear? The agent's default voice, then the voice matching the caller's dialect when **Dialect detection** is on. See [Voices and language](/docs/agents/voice-and-language). ### Does the caller's number appear in Conversations? The conversation is labelled with Twilio's call id, not with the caller's number. ### Does pausing the agent stop the number? No. A paused agent still answers calls on its number, and they are charged. Disconnect the number or assign it to another agent. ### Can I connect one Twilio number to two agents? No. A number is connected to one agent. To move it, use **Assign to another agent**. ### What does a call cost? Each turn is charged like a playground call: the seconds transcribed, the characters spoken and the model's tokens. See [What a turn costs](/docs/agents/what-a-turn-costs). Twilio's per-minute charge is billed by Twilio to your account. ## Related - [SMS with Twilio](/docs/agents/sms-twilio): the text side of the same connection - [Channels overview](/docs/agents/channels-overview): every channel side by side, and which one to launch first - [Human handoff](/docs/agents/human-handoff): the channels where the agent can hand a conversation to a person - [Test your agent](/docs/agents/test-your-agent): the **Call** the phone call behaves like - [Voices and language](/docs/agents/voice-and-language): the voice the caller hears - [End conversation](/docs/agents/system-tool-end-conversation): letting the agent hang up - [Agent status](/docs/agents/agent-status): why pausing does not stop the number - [What a turn costs](/docs/agents/what-a-turn-costs): the voice rates a call is charged at - [Conversations](/docs/agents/conversations): where the call's transcript lands