This page gives details and background information on how Proxy handles phone numbers. If you just want to get started working with Proxy, head over to the quickstart.
Behind the scenes, Proxy intelligently manages phone number selection from your number pool.
For masked communications between two participants, Proxy relies on the concept of
Sessions are our pairings of two individuals. A
Session doesn't just wrap up a single voice call or SMS message, it contains all the calls and messages for the given pairing of numbers. The following diagram shows a
Session with two numbers wrapping up two SMS conversations and a Voice call.
Let's walk through the example of a simple delivery service to understand how Proxy handles proxied numbers.
Different numbers in different countries will vary by capabilities; numbers which support multiple capabilities can have different conversation types in the same session.
We first create our Proxy service, and add two Twilio phone numbers to it:
Both of these numbers are voice and messaging capable.
A new delivery is created in our system, so we create a Proxy
session. Here are the steps Proxy runs through:
A second delivery is created in our system and we create a second Proxy
session. It's a different customer and different driver, so Proxy can re-use the number used in the first delivery.
From our first delivery session which is still ongoing:
For our second delivery session, the following happens:
Proxy can re-use the same Twilio number for this masked communication because it is still able to identify both participants uniquely.
A third delivery is created in our system, and now it is Customer C being paired with Driver X. Proxy knows that Driver X already has a
session ongoing (
Session 1) so it needs to be careful about number allocation.
Here's how Proxy manages this complexity:
Note how Driver X now has two different numbers assigned internally to the service. This abstraction makes it so that when Driver X makes/receives texts or calls originating from Customer C, they are from a separate number to his other customers (Customer A in this example).
Proxy thus manages the complexity of 3 deliveries across 3 customers with 2 drivers with only 2 phone numbers.
With Proxy, both participants in the
session don't have to use the same Proxy number. For example, if customer D is roaming on a UK phone number, and Driver Z is on a US phone number, the pairing may actually be:
This means that customer D won't have any trouble sending SMS messages to a UK number, but they will still be proxied through to reach Driver Z on a US number.
Proxy intelligently manages phone number allocation. Algorithmically, it attempts to optimize for many use cases and prioritizes:
When presented with an end users phone number, Proxy will only match that number to a Twilio number in the same country. This is to ensure that routing between an end user's number and a Twilio number will always succeed. Beyond that, Proxy allows a number of configuration options on the Service with the paramater GeoMatchLevel.
|Country||Default. End user numbers will only match with a same-country Twilio number. For example, if you have USA and UK users, the|
|AreaCode||Require numbers to match exactly to local area codes.|
|ExtendedAreaCode||Require numbers to match to extended area codes.|
Proxy provides two number selection "styles". These are configurable on the Service. The two settings are PreferSticky (default) and AvoidSticky.
PreferSticky means that Proxy will try and select the same number for a given participant if they have previous sessions but will select another number if that number cannot be used. This is useful for ridesharing like use cases, where there is low concurrent sessions, and you want drivers to see the same number when interacting with your service as much as possible.
AvoidSticky means that we will try to use different phone numbers as long as that is possible within a given pool rather than try and use the same. This is useful where you want users to see a different number when matched with different people as much as possible.
We have a whole page on that question, find that here: How many numbers do I need?