Using the Reserved Numbers and Auto-Create functionalities to support the “online directory” scenarios

(error)

Proxy Public Beta is not available to new customers

Proxy Public Beta is currently closed for new customers. Please consider using Twilio Conversations and Programmable Voice directly if you are building your masking application.

Note that this does not have any impact on Twilio Flex customers.

(warning)

Public Beta for customers already using Proxy

Twilio's Proxy API is currently available as a Public Beta product. Some features are not yet implemented and others may be changed before the product is declared as Generally Available.

Public Beta products are not covered by a Twilio SLA.

The auto-create functionality of the Out Of Session callback webhook and the Reserved functionality for the Phone Numbers can be used in conjunction to implement a solution for the special - but rather frequent - use cases where businesses need to display a Phone Number forwarding all incoming calls/texts to a specific person and don't know who will contact it. In the typical Proxy scenarios, you know in advance who both the Participants of your Proxy Session will be. In this case, you only have half of the needed information; you have the destination endpoint, but you still don't know who will be the customer calling in.

Let's use the example below to show how the auto-create functionality of the Out Of Session callback webhook and the Reserved functionality for the Phone Numbers.

Let's assume there is a site called ShoppingPlace.com where people can post items for sale and other people can purchase them. One feature that the seller wants is for the two parties to be able to correspond by text or call without giving out personal Phone Numbers. At the same time, sellers might want their customers to always use the same Phone Number to contact them. Here's what ShoppingPlace.com should do.

Create a Proxy Service and mark a set of Phone Numbers from the pool as "reserved". More specifically, as many Phone Numbers as the number of Sellers on the platform.
Within their internal system, record the association between each Seller and a specific Reserved Phone Number.
- Let's assume that there are two Sellers:
  1. Tom (private Phone Number +1 415-234-5555) - with reserved Phone Number +1 415-111-1111
  2. Beth (private Phone Number +1 209-987-6666) - with reserved Phone Number +1 209-222-2222
Publish the reserved Phone Numbers (+1 415-111-1111 and +1 209-222-2222) on the platform so that buyers can text or call those Phone Numbers to enquire about items with Tom or Beth.
Specify an Out of Session Callback Url in their Proxy Service's configuration to tell Proxy what to do in case no Sessions are found when a new call/text is hitting a Proxy Phone Number. The Out of Session Callback Url should point to a service owned by ShoppingPlace.com which, when hit with a POST request, will return an auto-create JSON response payload to tell Proxy what to do.
In this case, ShoppingPlace.com doesn't know in advance which buyers will be interested and cannot create the session before the buyer texts in. For this reason, ShoppingPlace.com wants Proxy to automatically create a Session with any new buyers reaching out to the Proxy Numbers +1 415-111-1111 / +1 209-222-2222 and Tom / Beth respectively.
Let's assume a new buyer (+1 415-111-5555) for Tom is calling in +1 415-111-1111. Proxy figures out that the buyer and Tom are not in a session. Proxy hits the Out of Session Callback Url configured on the Proxy Service. The Out of Session JSON payload returned would look something like the example below.

Sample auto-create session JSON for Proxy

1{
2  "uniqueName": "autoCreatedSession23423",
3  "ttl": 3360,
4  "mode": "voice-and-message",
5  "participantIdentifier": "+14152345555"
6}

This tells Proxy to:

Create a voice and message capable Session named "autoCreatedSession23423" that will expire in 3360 seconds (or 3360 seconds after the last interaction between the seller and buyer).
Add the buyer as a Participant to the Session (Proxy has the buyer's Phone Number because they initiated the interaction) with the Proxy Identifier as the Reserved Phone Number +1 415-111-1111 (which is the Proxy Phone Number published on the website and associated to Tom).
Add Tom as the second Participant using Tom's private number (+1 415-234-5555) as the Identifier and allowing Proxy to select an unreserved Phone Number from the Proxy pool as the seller's Proxy Identifier.

Note that mapping (recorded into ShoppingPlace.com database) between Tom and the reserved Proxy Phone Number +1 415-111-1111 doesn't mean that Tom's Proxy Identifier is +1 415-111-1111.

Now that Proxy has created the Session with the desired Participants, it can forward the message or call just as it would have if the Session had been pre-created. Now that there is a Session with the correct Participants, the buyer and seller can go on corresponding via masked communication.