Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

How many Phone Numbers do I need?

We strongly recommend you read the Proxy Phone Number Management introduction first.

An important setup task with Twilio Proxy is adding phone numbers to your Proxy Service, as you'll see from the quickstart and REST API documentation. How many phone numbers should you add to your service?

In the quickstart, you add only a single number with no additional configuration options set. This means that Proxy will use that single number to pair Participants in each Session. If you try and pair the same individuals in additional Sessions while the first Session is still open, you'll get an error because Proxy has used all available numbers.

The exact "number of numbers" you'll need in the Proxy number pool is based on a number of factors, but the Proxy number rule of thumb comes from this question:

How many concurrent Sessions can my customers be active in at once?

For one example, in a ridesharing app a driver will usually only be paired with one passenger at a time.

Let's say we make a Session last four hours, so a typical ridesharing customer can call the driver for a few hours after their ride ends to ask about a misplaced item. In that case, we'll need a number for each rider-driver pairing:

Session 1 Customer A using Number 1 paired with Driver X Leave Session open for 4 hours
Session 2 Customer A using Number 2 paired with Driver Y Customer needs a separate number, because number 1 is in use

To illustrate further, let's say we have an application where our customer can interview several service providers at once over voice or SMS. In this scenario, there will be multiple concurrent sessions open and you'll require at minimum a separate number for each Session:

Interview 1 Customer A paired to Provider X 1 Twilio number required
Interview 2 Customer A paired to Provider Y 2 Twilio numbers required
Interview 3 Customer A paired to Provider Z 3 Twilio numbers required

This same logic applies to the Provider - if we know that the provider can be involved in any number of concurrent Sessions the provider will also need multiple phone numbers.

Note: Proxy will enforce these rules for both voice and message modes so that no collisions are possible.

Remember: The best time to create a Session is when it's needed. For example, show a "Call" button in-app, then create the Session and add the Participant, and then finally retreive the assigned phone numbers.

What other factors affect how many Phone Numbers are required?

Sessions per Phone Number

At high scale, you may start to encounter issues if too many Sessions are concurrently using the same Phone Number. This is particularly true if your application sends an high volume of bulk messages over multiple sessions at once or if you deployed Proxy outside of the US. In these cases, we recommend limiting your use of Proxy to 100 unique Sessions per Phone Number. This is to ensure message and voice traffic over a single Phone Number does not encounter throttling and/or blocking by carriers. If you have an high volume of Sessions and you need more guidance in scoping how many Phone Numbers you should have in your pool, don't hesitate to reach out to us.


Setting strict GeoMatching rules on your Proxy Service will mean that you require far more local Phone Numbers in your pool to successfully match Participants.

How can I tell if I need more Phone Numbers?

When adding Participants to a Session, you will receive an error if your Proxy Phone Number pool has no available Phone Numbers. This error is reported to debugger events. In the future, a metrics API will allow you to check utilization of your Phone Number pool. We are also investigating automated alerts when your Phone Number pool is approaching full utilization.

If that doesn't answer all of your questions about how to estimate the number of phone numbers you will need in your Twilio Proxy service, and you've already read our guide to Phone Number Management, then please contact using the support channel below.

Hopefully it does, and you're ready to dig into the Proxy API Reference next.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.