Phone calls
Let people phone one of your Twilio numbers and talk to an agent: the key to create, the three steps of Add a number, what callers hear, approvals during a call, reading a call afterwards, and what a call costs.
A phone number can be answered by one of your agents. A caller talks, Twilio turns their words into text, the agent answers with its own instructions and tools, and Twilio speaks the answer back. Every call is kept with its transcript, the tools the agent used and what it cost.
Harbor & Pine puts its stockist line on Order desk: stockists phone to check an order's status, and the agent looks it up in the Order log while they wait.
What you need
- A Twilio account with a phone number. A number bought in Twilio appears in the list when you add one; buying a number from here is not offered. A trial account can't buy numbers.
- An API key for that account, made in Twilio's console. We never ask for the account's auth token.
- An agent to answer. Pick a fast model for it and turn thinking and planning off on the agent: answers start sooner, and a weaker model doesn't loop on its plan. Groq and Cerebras models, and Amazon Nova Micro or Lite, answer in about a second. A workflow agent can feel slow on the phone, because the caller waits for its run.
Which key
Add a number asks which kind of key you made. Each is a trade-off:
| Key | What it can do | How calls are checked |
|---|---|---|
| Restricted (recommended) | Only what calls need: read and answer calls, point a number. | Twilio can't sign its requests with a Restricted key, so each call is checked by the secret tokens in its address. |
| Standard | Almost anything in your Twilio account. | The tokens, and Twilio also signs every request it sends. |
A Restricted key needs these permissions. Tick calls.recordings/create only if you will record calls; recordings/read plays a voicemail in a call's log.
/twilio/voice/calls/read
/twilio/voice/calls/update
/twilio/voice/calls.recordings/create
/twilio/voice/recordings/read
twilio/phone-numbers/active-numbers/list
twilio/phone-numbers/active-numbers/read
twilio/phone-numbers/active-numbers/updateAdd a number
Open Channels › Phone and press Add a number. It takes three steps.
Twilio key
Open API keys in Twilio's console, create a key of the kind you chose, and paste the Account SID (it starts with AC), the API key SID (SK…) and the API key secret. Check and continue checks them with Twilio straight away; the secret is stored encrypted and never shown again.
The number
Pick one of the account's numbers. Each says where it points now. The one you pick is pointed at your agent, and put back where it was when you turn it off or delete it.
If the key may read numbers but not change them, the number still connects: its pane gives you the address to paste into Twilio's console, as the number's Voice URL for "A call comes in" (HTTP POST).
Who answers
- Agent: answers every call to this number, as a visitor's conversation.
- Name: how the number is listed. Empty uses the number.
- What callers hear first: the opening words. They always begin with a notice that the caller is talking to an AI assistant; you can reword it, but not remove it.
- Hand off to a person (optional): a number with its country code, such as
+14155550100. The agent can transfer a caller there. - Recording: recordings stay in your Twilio account. Transcripts are always kept.
- Language: the language your callers speak. Pick your callers' English — English (India) hears an Indian accent better than English (United States).
Press Connect number.
What callers hear
- The notice first, then your opening words. With recording on, This call may be recorded. is added.
- While a tool runs, one short line (One moment while I check that.), and a second if it is still running after 6 seconds.
- Talking over the agent stops it. The transcript keeps what the caller actually heard.
- A hand-off: with a hand-off number set, the agent can connect the caller to a person. If nobody answers, the caller can leave a voicemail; it stays in your Twilio account, the bell tells you, and it plays in the call's log.
- The end of a call: when the agent thinks the caller is done, the call asks Is there anything else I can help you with? before it says goodbye. After 8 seconds of silence it asks Are you still there?, twice, then ends the call. A minute before the plan's longest call, the agent is told to wrap up.
Approvals during a call
A caller is always a visitor: a phone number can be faked, so a caller is never treated as a member of your workspace, and the agent uses only the tools you allow for visitors. A tool that needs approval asks someone in the bell, and the caller hears that someone on the team will follow up.
Answer it from the bell or from the call's log. If you answer while the caller is still on the line, they hear it on the call; otherwise, call them back.
Reading a call
Open a number's Recent calls. A call's log shows the transcript with the agent's tools, the filler it said and where the caller spoke over it; any approval it raised; and a strip with the call's length, how long the first words took, the model cost, and an estimate of Twilio's charge.
What a call costs
On Cloud, a call is 4 credits a started minute, one line on the bill per call; the agent's turns inside a call are not charged again. Model tokens are billed as usual, from the model wallet or your own key. A five-minute call is 20 credits plus its model tokens. Each plan sets how many calls may be on the line at once and the longest call:
| Free | Solo | Team | Growth | Business | |
|---|---|---|---|---|---|
| Calls at once | 1 | 2 | 5 | 10 | 20 |
| Longest call | 10 min | 30 min | 60 min | 90 min | 120 min |
Self-hosted, there are no credits: you pay Twilio and your model provider directly.
Either way, Twilio bills your account for the call itself: ConversationRelay, the inbound minute, and recording if it is on. The call's log shows an estimate.
Self-hosted: let Twilio reach the backend
A call is a live connection from Twilio to this server, and it must reach the backend directly: the app's own proxy can't carry it. On the Channels tab, set the Webhook address to a public https address that reaches the backend port, for example a cloudflared tunnel. Until it is set, connecting a number says so. (The Channels hub shows while messaging_enabled is on, which is the default.)
On Cloud there is nothing to set.
Turning a number off, or deleting it
Both put the number back where it pointed before. A Standard key makes a SharedKey for the number in your Twilio account, and a trial account can't delete it (Twilio allows 50 an account); the number says so when you turn it off. Deleting a Cloud workspace puts its numbers back too.
Schedules and channels
Work that starts without anyone pressing Run: a workflow every Monday morning, an agent that answers in Telegram (and in Slack or Discord when self-hosted), and a human step that asks its question in a channel.
Members and roles
Bring your team into the workspace, give each person the role they need, and see who did what: roles, seats, sessions, notifications and the audit log.