Proxy API

Twilio Proxy is a complete API for setting up and managing one to one masked communications across multiple channels. Proxy lets you build a communications experience for your users without exposing personal information - all with the ease and power you expect with the Twilio platform.

Proxy is now in beta.

For details of moving from the Proxy developer preview version to the beta version click here.

Key features of Twilio Proxy:

  • Session Management - Create and manage conversational sessions across multiple communications channels.
  • Automatic Proxying of Communications - Allow messages and voice to flow back and forth without the need to spin up a web server.
  • Phone Number Management - Automatically select appropriate Twilio phone numbers for proxied text and voice communications.
  • Easily Combine Voice and SMS - See a single combined view of communications history between participants across both voice and SMS.
  • Connect Multiple Channels (Coming Soon) - Setup sessions that span different channels such as SMS to Twilio Programmable Chat and SMS to Facebook Messenger.

Twilio Proxy Overview

Proxy Overview Graphic

Above is an overview of how Proxy works in a common scenario: masking communications between an employee or contractor and a customer.

A session is an instance of two individuals communicating; in this example it's a customer and a delivery driver communicating about an order. Using the Proxy REST API, we create a session, and then add two participants to the session which represent the customer and the driver. Once created with appropriate proxy numbers, Twilio routes communications between the two participants.

Note: Make sure you have consent from users before storing their communications

It is best practice, and also potentially required by law in certain jurisdictions, for you to have consent from your end users before using Proxy to manage communications between them. It is best practice to achieve consent from users that makes it clear that when using a service powered by Proxy they are not communicating directly with each other but that their communications are being proxied and recorded by you and your service provider (i.e. Twilio). You should respect your end users choice to not receive messages/calls whether via Proxy or any other Twilio product. It is also important to make sure your database is up to date. This is particularly important for number-based communications like SMS because over time phone numbers may be reassigned to different individuals. If your database is out of date, you could inadvertently initiate communications to someone who did not consent but were reassigned a phone number that was previously subscribed to your service by another person. Check out the Twilio Marketplace for Add-ons from our partners that can help you keep your database up to date.

Twilio recommends that you consult with your legal counsel to make sure that you are complying with all applicable laws in connection with communications you transmit using Twilio.

Getting Started

Visit our Quickstart where we have some sample code for various languages and example curl commands if you need to port to others.

You can create Services and view sessions through the Twilio console for Proxy, but usage of Proxy is best done through the REST API or using our Helper Libraries:

Getting Help

To send feedback and discuss implementation, please join our Google group and let us know how things are going!

Proxy Features Available Today

  • Phone number management
  • SMS and Voice support
  • TTL on Sessions
  • Intercept webhooks
  • OutOfSessionWebhooks

Coming Soon

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.