Phone Numbers
Managing Twilio phone numbers for your agents
Why This Matters
Every live phone agent needs a working Twilio number. That number tells the platform which client and which agent should answer the call.
If the wrong number is attached, the wrong agent can answer, calls can miss the proper webhook, or SMS follow-ups can fail.
What a Good Setup Looks Like
Before you mark a number as ready, make sure:
- the number exists in Twilio
- the number is saved in full E.164 format, such as
+15551234567 - the number is assigned to the correct client
- the number is attached to the correct agent
- the voice webhook points to your live inbound route
Ways To Assign a Number
During client setup
When you create a client, add the Twilio number in the setup flow. This usually becomes the main number for the primary phone agent.
From the client record
- Open the client.
- Go to Connections -> Twilio.
- Click Sync Twilio to pull in available numbers.
- Pick the number you want.
- Assign it to the correct agent.
When adding another agent
If the client uses more than one phone agent, give each agent its own number or
use the routing setup your team has approved. Always enter the full E.164
number, such as +15551234567.
Number Fields
| Field | What it means |
|---|---|
| Number | The full phone number in E.164 format. This must stay unique in the platform. |
| Client | The client account that owns the number in your system. |
| Agent | The live agent currently using the number. |
| Type | Whether the number is used for inbound, outbound, or both. |
| Provider | The phone provider. Right now this is Twilio. |
| Status | Whether the number is active, reserved, or released. |
| Capabilities | Voice, SMS, and MMS support from Twilio. |
| Monthly Cost | The monthly carrier cost for keeping the number active. |
Webhook Setup
The number must send calls to your platform before the agent can answer them.
Typical routing looks like this:
- Voice URL:
https://api.youragency.com/inbound - SMS URL:
https://api.youragency.com/sms
In many cases the platform can set this for you when the number is assigned. If calls are not reaching the agent, check the webhook first.
Reassigning or Releasing a Number
If a client stops using a number:
- Remove the number from the old agent or move it to the new one.
- Confirm no active workflow still depends on it.
- Decide whether you are only removing it from the platform or fully releasing it in Twilio.
Removing a number from the platform does not automatically release it from Twilio.
Warning: If you release a number from Twilio, you may not be able to get that same number back later.
Status Meanings
| Status | Meaning |
|---|---|
| Active | The number is assigned and should be routing traffic now. |
| Reserved | The number is being held for later use and is not part of the normal live flow. |
| Released | The number was removed from platform use. It may still exist inside Twilio. |
Troubleshooting
| Problem | Likely cause | What to do |
|---|---|---|
| Calls do not reach the agent | Voice webhook is missing or wrong | Re-sync Twilio or update the voice webhook manually. |
| Number does not appear in the platform | The number is not in the connected Twilio account | Buy or move the number inside Twilio, then sync again. |
| Duplicate number error | The number is already attached somewhere else | Find the old assignment and release or reassign it first. |
| SMS follow-up fails | The number does not support SMS | Check Twilio capabilities and swap to a number with SMS support. |