Agents

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.

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
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 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.

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

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

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.

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
The Voice tab The default voice opens the call. Speed, guidance and diacritization apply per voice. See Voices 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
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.

Each turn is charged at the voice rates in 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.

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.

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.

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. Twilio's per-minute charge is billed by Twilio to your account.