Rate this page:

Proxy Quickstart

With just a few lines of code, you can have a text and/or voice conversations between two cloaked participants.

In this Quickstart, you will learn how to:

  1. Purchase a Twilio phone number
  2. Gather your account information
  3. Set up your development environment
  4. Create a Proxy service
  5. Add a phone number to your service
  6. Create a session
  7. Create participants
  8. Send a text message
  9. Make a voice call

To test this quickstart, make sure you have two phone numbers you wish to connect ready to go (perhaps two cell phones?).

I'm ready to do this!

Purchase a Twilio phone number

The first thing you need in order to set up a proxied session is a Twilio-powered phone number. You can grab one to use in the console here.

Make sure that it has SMS and/or Voice enabled for the purposes of this quickstart. Note that in many countries, numbers will only have either Voice or SMS capability; to test both features you will need both types in your number pool. US and Canadian numbers will have both capabilities.

Notify SMS Quickstart - buy a Twilio Phone Number

Take a note of the Twilio string identifier (SID) of the number. You'll need it for this quickstart; here's where you find the Phone Number SID:

Phone Number ID

You'll want at least two phone numbers in your Proxy pool.

Got my numbers! What's next?

Gather your account information

You can find these in the Twilio Console.

  • Account SID - Used to authenticate REST API requests
  • Auth Token - Used to authenticate REST API requests

Twilio Account Summary section of the console

For all of our code snippets and curl examples, you will need to authenticate with the Account SID and Auth Token.

OK, account credentials are in hand...

Set up your development environment

The next steps will involve writing some code. We've provided examples in multiple languages, but you will need a working development environment in at least one of them. Here are some guides we've written to help you get your Twilio development environment up and running:

We also provide examples for the curl command line which should work from a Linux or macOS terminal.

I'm ready to write some code...

Create a service

Note: You can also create Services via the console for Proxy.
Let's create a service that will contain our sessions:


        Take a note of the service SID (KSxxxx) that you get as a response.

        OK, Service is created!

        Add a phone number to your service

        We need to associate the number(s) we bought with our newly created service. The phone numbers you add will be added to the anonymous number pool for your proxied communications.


              This adds a single number to the Proxy pool. Repeat for each of your Twilio phone numbers

              Phone number(s) have been added!

              Create a session

              A session is a conversation between two people. This code will create a new session in your Proxy service.


                    Note the session SID (KCxxxx) from the response you get.

                    OK, I've got a session, now what?

                    Create participants

                    You can't have a good conversation without participants, so let's add some.


                          Run it again with a second participant (a different phone number for another proxied user, and a different 'Friendly Name').

                          For each participant, you'll receive a response with the participants assigned Proxy number, which will come from the pool of numbers you've added. Depending on the capabilities of the phone number, next either send a text message in the conversation or make a voice call.

                          Let's have a conversation!

                          Send a text message

                          If your number has text messaging capabilities, you're ready to roll! If you're looking at a voice proxy, skip to the next section.

                          Let's send a message from one of the assigned Proxy numbers to one of the participants. Execute the following for one of the participants (the participant you'd like to receive this initial message):


                                And with that, the Proxy text conversation can continue!

                                Voice conversations too?

                                Make a voice call

                                If your Twilio Phone Numbers are voice capable, you're now ready for a proxied voice conversation. Following the names from the previous steps, get Alice to make a call to her Proxy Identifier number. Twilio's Proxy service will then make a call from Bob's Proxy Number to his real number and connect the two calls.

                                Now you're talking anonymously!

                                You now know how to create text and/or voice conversations between two masked participants. To learn more about how Proxy works check out the guide to Phone Number Management or dive into the REST API reference.

                                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 by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.


                                      Thank you for your feedback!

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

                                      Sending your feedback...
                                      🎉 Thank you for your feedback!
                                      Something went wrong. Please try again.

                                      Thanks for your feedback!

                                      Refer us and get $10 in 3 simple steps!

                                      Step 1

                                      Get link

                                      Get a free personal referral link here

                                      Step 2

                                      Give $10

                                      Your user signs up and upgrade using link

                                      Step 3

                                      Get $10

                                      1,250 free SMSes
                                      OR 1,000 free voice mins
                                      OR 12,000 chats
                                      OR more