Guide to using the Twilio Virtual Phone

The Twilio Virtual Phone is a simulated mobile device that can be used by Twilio customers to explore and test sending and receiving messages through the Programmable Messaging API in place of your own mobile device. The Virtual Phone interface will display messages sent to the Twilio Virtual Phone Number, when sent from the UI experience or outside of the Console via API. You can send messages to the Virtual Phone without registering your sender.

The Twilio Virtual Phone is powered by a Twilio-owned, verified Toll Free number: (877) 780-4236. Note: Any account can send messages to the Virtual Phone, however the messages displayed in the Console are filtered on an account basis; other users will not be able see messages you send to the Virtual Phone.

The Virtual Phone can serve different kinds of users:

1. People who want to find out how the Programmable Messaging API works
2. People who want to begin serious prototyping while still in Free Trial
3. People with paid/upgraded accounts who want to prototype using an unverified TF number
4. People with paid/upgraded accounts and verified TF numbers (or A2P-registered 10DLC numbers) who prefer to prototype via the Console rather than with their physical mobile device.

Any user who signs up for a Twilio Free Trial account is provisioned (upon request, in the Trial workflow) with a free Toll-free number. This number can be used immediately for non-SMS purposes, for example sending an automated voice message to your own personal mobile device. However for Messaging, this new Toll-Free number cannot be used to send SMS messages to personal numbers within the U.S. until after a verification application has been submitted. For US users who have not yet decided to submit a TF Verification application, or who do not have the necessary business use case to do so, Twilio has created the Virtual Phone. This can be found at any point during or after a Free Trial period in the Messaging section of the Twilio Console: at Messaging > Try it out > Send an SMS:

Expand image

After you have exited the initial Free Trial workflow, but while you are still in your Free Trial account, you can find the Virtual Phone again by navigating to the Messaging section of the Twilio Console, then to Try it out > Send an SMS.

The screen you see will have the elements at the top as indicated in the screenshot below. On the right is the Virtual Phone itself. On the left is the Step 1: Recipients and Senders box. In this first scenario, you have not yet submitted a verification application for the toll-free number you received on Trial sign-up, which means that with this number you are not yet allowed to send messages to numbers over the carrier networks (in the United States or Canada; this restriction does not apply elsewhere). Therefore, the Recipient To and To phone number are read-only values here: at this time it is only possible to send messages to the Virtual Phone, which do not go over the carrier networks, though in other respects they use exactly the same Twilio API calls as other messaging would. The Twilio Virtual phone has a single, fixed phone number as shown here.

Below the Recipient information we have Sender From and From Phone number. While you will only have a single Twilio phone number to send from at this point, you might also have created a Messaging Service to place this number in (to learn how to create a Messaging Service, please see this guide). The From dropdown thus allows you to select either Phone Number or Messaging Service as values. If you select Phone number, the following dropdown will display any phone numbers available to you as senders.

Expand image

Here is the From phone number dropdown with available options shown:

Expand image

The 855 number shown here is the Toll-Free number you were provisioned upon signing up for Free Trial. This is your only available number at this point, and while we see the "Buy a Number" link displayed as well, if you clicked this you would be told that, before you could purchase additional numbers, it would be necessary to Upgrade to a paid account. For now, the one Toll-free number is the only allowed number for the sender.

If you instead selected Messaging Service in the From dropdown, the second box label would change to Select a Messaging Service. In the next screenshot, we have not yet created a Messaging Service, so the only dropdown entry is "No results found."

Expand image

However, if you were to follow the directions in this guide to create a Messaging Service, and then added your toll-free number to this service as a sender, the same dropdown would now give you the option of selecting that Messaging Service as the sender for this test message:

Expand image

Either way, at this point you will have established both the Recipient of the test message (the Virtual Phone, with its unique number (877) 780-4236) and the Sender of the message (either your toll-free number or a Messaging Service with that number added as sender). What remains is to specify the message text (or body) itself, and to decide whether you want to send that message directly from the Console or instead from your own CLI or another application.

Immediately beneath the To and From box on this screen, then, we have the Step 2: Sending Messages box.

Expand image

As shown, we have two options here, and we will begin by considering the second option: sending your message from the Twilio console itself. Here you would type your message text (aka message body) into the Message field, and press the blue Send test SMS button. This message will then appear within the window of the Virtual Phone, just as it would in the window of a physical device:

Expand image

What if you were to then send a second message from the same number? The Virtual Phone would display the second message as well, and any subsequent messages sent from the same number. As with a physical phone, the screen will scroll once the initial screen space has been filled up:

Expand image

What if you instead wanted to send a message from your CLI (Command Line Interface)? You would only do this if you were generally comfortable with CLIs and with the Twilio CLI in particular. But you would still need to know the specific code to use in sending this message. It's important to understand that you will be sending exactly the same message as you would via the blue button in the Console. So as with that button, you will first need to select your toll-free number as the sender, and specify some Message text. Now, click the API View button in the upper right corner of this screen. The Virtual Phone graphic will disappear and be replaced by the following boxes.

As you can see, the code for this API call is available in a range of popular programming languages, accessible by tabbing across the top of the first box. We will stick with the default language, curl. But the call parameters would be the same in any language.

Expand image

To begin, any Twilio API call, such as this one, will require an Account SID and an Auth token; these values will be unique to your Twilio account and can be found in the account information accessible from the top of your Console. Beyond that, the three parameters specific to a send message API call are To (which as you see has been auto-populated with the number of our virtual phone), From (auto-populated with the toll-free number you were given at signup) and Body (the message body text, auto-populated from whatever you typed into the Message text box.

This code box is read-only; it is the API call that will be executed when you click the blue Send test SMS button under Option One in the present Console screen. The Response from that call will appear in the lower box. But if you instead wanted to copy the API call code, you could paste it (in the case of curl) into your CLI and run it from there, with identical effect. Or if you had a Java, Ruby, Python, C# or Node.js application, you could copy those versions of the code to create classes that you could run with identical effect. The call is made in that case from your computer or app to our public Messaging API, and from there to the specified recipient, which in this case is the number of the Virtual Phone, a number not associated with a carrier so it does not go over the carrier network. Whatever message you specify in the message body will appear in the Virtual Phone screen.

Note here that we have taken the simplest possible code example: a single call to the Twilio Messaging API to send a single SMS message to a single recipient with a single, hard-coded message body text. This is usually a good first step, but after this your code can become a great deal more elaborate while still using the Virtual Phone and, if you wish, still using the unverified Toll-Free number you received on Free Trial signup.

The final screen of the Free Trial signup workflow, which you can access at [link], pulls together a number of resources to help developers explore the possibilities of Twilio messaging, including code samples for a number of popular personal or business use cases. These code samples are hosted on CodeExchange. And unlike the code snippet we have just looked at, these samples are aimed at building out a complete, functional messaging application using the Twilio messaging API:

Expand image

The first, featured code sample has an accompanying Youtube-based video, and walks you through building a vacation rental site, where the host can confirm a reservation automatically via text message. Other code samples on this page include an SMS opt-in builder and an app for omnichannel two-factor authentication. From this page you can also browse the entirety of CodeExchange, or you can check out Twilio's Developer Docs, which include a wide range of quickstarts and tutorials (as well as API reference documentation) both for Messaging and for Twilio's other products.

Whatever programming avenue you chose to explore, as long as you specify the phone number of Twilio's Virtual Phone as your To/recipient your messaging will be routed to the Virtual Phone, meaning that it won't cross the mobile carrier network and thus won't be restricted by the limitations of your unverified toll-free number.

At some point, however, you will probably decide that it is worthwhile to at least get this first toll-free number verified, as this will unlock the possibility of cross-network traffic (including to your own personal cellphone) as well as other possibilities. But if you've found the Virtual Phone useful to this point, you can also choose to continue using it.

In Scenario 2, a user is still in their Trial account but has submitted an application for verifying the toll-free number received at signup. To submit this TFV application via the Twilio Console, see this guide. As soon as this verification application has been submitted, it will be in a PENDING state until it has either been approved or rejected by our TF ecosystem partners. In the period between Nov 8 and January 31, 2024, as soon as a TFV application is PENDING, the restriction on cross-network traffic is removed. Accordingly, users in Scenario 2 would be able to use their toll-free number to message either the Virtual Phone or their own mobile device (plus up to 4 other pre-designated mobile numbers).

Therefore, the user experience of the Messaging > Try it out > Send SMS screen in Scenario 2 will be very similar to that of Scenario 1, except that in the Recipients and Senders box we saw above, Recipient To and To phone number will not be read-only fields but dropdowns. To will allow you to select either the Virtual Phone or your own mobile number as the recipient:

Expand image

And if you select "Use my personal number" here, To phone number will allow you to select your own mobile device number (as part of Free Trial Signup you already consented to receive an OTP message on this device) or other phone numbers if you've added them to your Trial account:

Expand image

Note that if you do select "use my personal number" for your Recipient, the Virtual Phone graphic will disappear from this screen, and you will instead be shown only the "API view" we saw in Scenario 1. This is because the Virtual Phone is no longer the designated sender, and thus no longer relevant to this Scenario. Any SMS message you send at this point will instead travel to your own physical mobile device (or to a different mobile device if you've pre-approved others and designated that one as the recipient instead):

Expand image

But if you instead select Virtual Phone as the Recipient, the Virtual Phone will remain visible, and the remainder of the experience will be exactly the same as it was in Scenario 1 above.

If you have upgraded your account from its original Free Trial status to a Paid account, one benefit is that you can now send SMS traffic to US phone numbers beyond the 5 maximum that you were allowed to pre-designate as Receivers during your Trial. Nearly anyone using Twilio messaging in a true business capacity will need an Upgraded account if only for this reason, because virtually any business case will involve sending SMS notifications to a potentially unlimited pool of customers or end-users. Moreover, having a Paid account will allow you to purchase additional Twilio services, including the purchase of additional phone numbers that can be used (among other things) as messaging senders.

However, it remains the case that no Toll-Free number in your account, whether acquired via Free Trial or purchased subsequently, can be used to send SMS messages in the US across the mobile networks until that number has been verified (or at least until the verification application has been submitted). Moreover, the other most common type of Twilio sender phone number for smaller businesses in the US is a 10DLC phone number (10-digit-long-code: e.g. 414.123.4567, or what we would recognize as a 'local' number); and this sender type as well is governed by regulations in the US and cannot be used to send SMS messages across the mobile networks until it has been approved for A2P use, a separate application process that is detailed here. It's conceivable, then, that a user might want to try out the benefits of a Paid Account but still have one or more sender phone numbers that are not yet cleared to send SMS traffic across the network, in which case the Virtual Phone would still be useful.

In that scenario, the user experience of the Messaging > Try it out > Send SMS feature would be similar to either Scenario 1 or 2 above, depending on whether or not you had other phone numbers (e.g. toll-free or 10DLC) that were cleared to send SMS traffic in the US. If not, then your experience would be identical to Scenario 1: the Recipient To and To phone number fields would be read-only, because your only option would be to use the Virtual Phone as the recipient of your messaging (and for Sender your only options would be either your single unverified toll-free number, or a Messaging Service with that number added).

On the other hand, if for your account contained a mix of numbers, some restricted from cross-network use and others unrestricted, the Recipient To field would be a dropdown, as in Scenario 2, allowing you to select either the Virtual Phone or your personal mobile number as the Recipient. For the Sender fields, you would once again chose between a phone number and a messaging service, and if you chose phone number, the From phone number field would be a dropdown displaying all of the numbers currently in your account, as below:

Expand image

In this screenshot we have two numbers in the account, an 8XX or toll-free number and a 10DLC number. There's also again the option to "Buy a Number", and if we clicked on this it would not error, as in Scenario 1, but take us to the Buy a number page, because this is now a Paid account which allows purchase of additional Twilio services.

But can we actually use either of these existing phone numbers as senders? As it happens, the toll-free number shown here has not yet had a verification application submitted, and the 10DLC number has not yet completed the A2P application process. Therefore, if we selected either of these and had specified our personal mobile number as the receiver, we would once again receive an error as this would be disallowed cross-network traffic. In this scenario the Virtual Phone would be the only legitimate receiver, whichever sender we chose.

In this final scenario, you've both verified your original toll-free number and upgraded your Trial account to a paid account. At this point, you might still own other sender numbers-either additional toll-free numbers or 10DLC numbers-that have not yet been cleared for SMS traffic across the carrier network in the US. But this possibility has already been mentioned in Scenario 3 above. If you have a Paid account with multiple sender numbers, and all of them have been cleared for US messaging, is there any remaining use for the Virtual Phone?

There certainly could be. One advantage of the virtual phone over a physical device is that you can very rapidly toggle between a thread of messages sent from one sender number to the thread sent from another by flipping the From phone number value on the Try it Out > SMS screen from one number to another, which will immediately update the display to the new number's thread. Let's say you had one app that was updating user phones with minute to minute stock quotes; another sending sports score updates any time the score changed in a designated game or set of games; and a third app that was giving real-time weather updates. With a physical device you would need each time to back out of a given thread to the Messaging app home page, and choose one of your other test threads from there. With Virtual Phone you could skip a step, which might be especially useful if you were trying to monitor the accuracy of your update-message apps against web readouts of the same data. Of course in a testing situation like this, you might also be generating significant messaging throughput which, if sent to a physical cellphone, could translate into significant cost depending on your carrier plan. This is a non-issue because Virtual Phone does not rely on network traffic.

Beyond this, there is the potential convenience inherent in a web-based receiver phone simulator (two-way calling will be part of a subsequent release of Virtual Phone). What if your cellphone runs out of power, crashes, or God forbid, dies, at some crucial moment in testing or debugging a messaging app? What if you are somewhere with internet service but no cell service? What if your cellphone is in another room, and you're not interested in retrieving it before testing a new feature in your messaging app? As long as you are able to log into your Twilio account, and go to Messaging > Try it Out > SMS, the Virtual Phone will be waiting to display your messages.