Business Productivity

Mask user phone numbers using Amazon Chime proxy phone sessions

On April 6, we released Amazon Chime proxy phone sessions. Developers can now easily enable two users to call or text for up to twelve hours, without requiring users to share their personal phone numbers. Instead of reaching each other using personal phone numbers, they use a number provided on demand by Amazon Chime proxy phone sessions.

Amazon Chime proxy phone sessions are ideal for the on-demand economy such as ride-sharing apps, delivery services, vacation rental services, or telehealth services.  When users call or message the provided phone number, they are connected to the other party and their personal phone numbers are replaced with the provided number in Caller ID. This practice, which Amazon Chime proxy phone sessions uses, is often called number masking.

This post gives an overview of Amazon Chime proxy phone sessions and provides a walk-through of a demo application. This demo shows a use case that connects a delivery driver to a customer via a simple web application.

When you should use Amazon Chime proxy phone sessions

As a developer, you may require phone communication because your users prefer the familiarity and reliability of phone communication. With calling and texting, users connect via native phone interfaces. They don’t have to worry about an unreliable internet connection, and can even be reached if they aren’t signed into an application. For cases where direct phone communication is needed, you should consider proxy phone sessions.

Often the most direct way to enable phone communication is to allow users to contact each other directly using their personal phone numbers. However, users may not want to share their contact information with others that they don’t know personally. Additionally, encouraging your users to contact each other outside of your service can lead to external transactions. This can lead to lost revenue, difficulty confirming when users contacted each other, and trouble resolving disputes.

Amazon Chime proxy phone sessions provides your users the reliability and familiarity of phone communication without disclosing personal phone numbers. Communication can be enabled for up to 12 hours and comes with call detail records (CDRs).

Why you should choose Amazon Chime proxy phone sessions

Ease of implementation

Amazon Chime proxy phone sessions are designed to make it easy to implement and maintain masked phone calls for users. As is demonstrated in the Getting Started section of this blog post, creating your first session can be completed in just three AWS CLI commands. This is different from common alternatives, which require far more steps including provisioning of numbers.  Obtaining numbers for specific area codes, choosing whether to reuse numbers or not, setting a customer support line to gracefully handle calls made after sessions end, and setting the length of sessions require the use of a few options. These options are all defined in our developer guide.

Cost savings

Amazon Chime proxy phone sessions offer cost savings by starting with a low per-session rate, low per minute call rates, and low rates for messaging. On top of that, you can get phone numbers whenever you need them. This saves you from having to build complex logic to provision phone numbers, which is a process often required by alternative services. Additionally, it saves you from manually selecting phone numbers for each customer interaction. Automatic phone number provisioning and selection saves you time and resources on implementation and maintenance, as well as on overall costs.

Availability and reliability

Amazon Chime proxy phone sessions make it simple to set up a highly available service. By creating and configuring an Amazon Chime Voice Connector in US-East (Virginia) or US-West (Oregon), you can fail over from one region to another at any time. This is helpful in the event your preferred region becomes unavailable. Should failover be needed, the sessions you created in your preferred region and the associated numbers are available in the new region.

Because Amazon Chime provides phone numbers on demand, you have phone numbers whenever you need them, preventing service disruption for your users. Unlike alternatives, this is available without the cost of buying and managing numbers and without spending engineering resources on building logic to manage number provisioning or selection.


Amazon Chime proxy phone sessions provide call detail records (CDRs), and can stream phone call audio in real-time with Amazon Kinesis Video Streams. CDRs enable detailed analysis of the number of contacts for each session, the type of contact, and the length of contact. Where appropriate, audio streams can be sent to AWS AI/ML services to build recording, compliance monitoring, and analytics solutions. For example, you can record and transcribe calls using Amazon Transcribe and do sentiment analysis using Amazon Comprehend. This analysis provides a better understanding of the quality of service and customer sentiment and can help resolve disputes.

Getting started

To get started with Amazon Chime proxy phone sessions, all you need is an AWS account.

Once you have an AWS account, you’ll run three simple commands using the AWS CLI. Using the following three commands, you will:

  • Create an Amazon Chime Voice Connector in the us-west-2 Region.
  • Configure it for Amazon Chime proxy phone sessions.
  • Create your first session with an expiration time of 5 minutes.

You need to enter your actual Voice Connector ID and the phone numbers you want to include in the session.

1.     Create an Amazon Chime Voice Connector in the US-East (Virginia) or US-West (Oregon) Regions

aws chime create-voice-connector \
--name newVoiceConnector \
--aws-region us-west-2 \

2.     Configure the new Voice Connector for proxy phone sessions

aws chime put-voice-connector-proxy \
--voice-connector-id <value> \
--default-session-expiry-minutes 5 \
--phone-number-pool-countries US

3.     Create a proxy session

aws chime create-proxy-session \
--voice-connector-id <value> \
--participant-phone-numbers <value> \
--name ExampleSession \
--capabilities Voice SMS

You can optionally adjust the values to increase the session length up to 12 hours, choose the us-east-1 Region, or choose your own names for the Voice Connector and Session. There is no need to purchase phone numbers ahead of time. If you want a number in a specific area code, simply indicate the US area code that you want. Numbers are available in area codes across all 50 states. If you select an area code that we do not have, you can retry creating the session with a new area code, or change the —geo-match-level option to ‘US’ to return a number from any US area code.

You can also name each session to associate sessions with an internal identifier like an order ID. Additionally, you can select if you want to reuse phone numbers or not, using the PreferSticky and AvoidSticky options. When you use the PreferSticky option, Amazon Chime reuses the phone number selected for the same participants in the last session if it is available. When AvoidSticky is chosen, Amazon Chime avoids using the same phone number again. More detail is available in our documentation for create-proxy-session.

If you have a customer support line, you can use the –fall-back-phone-number option when you configure the new Voice Connector for Proxy Phone sessions. This makes sure any out-of-session calls are redirected to your support team.

Delivery Driver Application Demo

Amazon Chime proxy phone sessions can be integrated into the user experience in different ways. We have put together a demo application for a common use case. This demo walks through the use case of a hypothetical delivery driver.  In this case, the delivery driver accepts an order, and is then assigned a phone number used to contact the customer by phone.

This demo uses the Serverless framework to deploy a simple web application in AWS. The application is served through and endpoint on Amazon API Gateway, calls Amazon Chime proxy phone session APIs using AWS Lambda, and stores the session data in Amazon DynamoDB tables.

To keep the demo simple, creation of orders happens through a simple form rather than through a customer-facing delivery flow.

Follow the ReadMe on the GitHub repository to deploy the application in your AWS account.

After you have deployed the application, you can create a session.

  1. Register for an account, making sure to enter your real phone number. This is your delivery driver account.
  2. Create an order, entering a name and a different phone number used in the session as the customer’s phone number.
  3. Navigate to the Deliveries page and select the order you created, then choose the Accept Order button.
  4. After you have accepted, the list of orders is updated and a phone number assigned to each order.

Note: When you call this number from your real phone number you registered, the call is forwarded to the other number you entered when creating the order. Your ‘customer’ sees the number assigned to the proxy phone session in caller ID and can call or text you back for the duration of the 15-minute session.

You can optionally add a customer service number to your Voice Connector configuration for proxy phone sessions. Then, call the assigned number after the session has expired. When you call after the session has expired, you will be redirected to your designated customer service number.


This blog post gives an overview of Amazon Chime proxy phone sessions. With Amazon Chime proxy phone sessions, you help developers enable phone communication for users without revealing private phone numbers. This post also provides a walkthrough of the delivery driver demo application, which connects a delivery driver to a customer via a simple web application.

Proxy phone sessions are available in the US-East (N. Virginia) Region and US-West (Oregon) Regions, at low pay-as-you go pricing. To get started with proxy number sessions, read our developer guide.

Ryan McHarg

Ryan McHarg

Ryan is a Senior Product Manager for the Amazon Chime SDK, a set of real-time communications components that developers can use to quickly add messaging, audio, video, and screen sharing capabilities to their web or mobile applications. Ryan has worked for Amazon Web Services since 2016.