How to Register a Twilio Phone Number and Send an SMS Using the Twilio CLI

May 14, 2021
Written by
Maciej Treder
Contributor
Opinions expressed by Twilio contributors are their own
Reviewed by

There are over 4.5 billion text-enabled devices. This creates a huge opportunity to notify people about upcoming appointments, special events, breaking news, or commercial promotions via SMS. Sending SMS messages programmatically enables reaching many people almost simultaneously. With Twilio Programmable SMS, you can register your own virtual phone number and send SMS messages across the world.

This tutorial will show you how to set up Twilio CLI, register a phone number and send an SMS using .the new number

Important compliance note: There are rules for using SMS messaging and they vary between countries. Familiarize yourself with the countries’ rules  in which you’ll be sending messages with the Twilio Regulatory Guidelines for SMS.

Prerequisites

To complete the project described in this tutorial you will need the following tools and resources:

  • Twilio account – Sign up for free using this link and receive an additional $10 account credit when you upgrade to a regular account.
  • Twilio CLI – The Twilio command-line interface requires Node.js and npm, which is installed with Node.js.

Get a Twilio Phone Number

Twilio SMS messages are sent using Twilio phone numbers, which provide instant access to local, national, mobile, and toll-free phone numbers in more than 100 countries with a developer-friendly API. You can get a Twilio phone number for free as part of your trial account.

Once you’ve created a Twilio account, you can use the Twilio CLI to get a phone number.

Note: If you’ve previously installed the CLI, be sure you have the latest version by executing the following command:

npm install -g twilio-cli

If you’ve stored your Twilio credentials as environment variables, the Twilio CLI will use them automatically. Otherwise you’ll have to login by using the following command:

twilio login

This command will prompt you for your Account SID and Auth Token, both of which are available on the Twilio Console.

To list the phone numbers available for registration, use the following command, substituting the appropriate ISO 3166 alpha-2 country code for “US”, if necessary:

twilio api:core:available-phone-numbers:local:list --country-code US

You should see a list similar to the below output:

Phone Number  Region  ISO Country  Address Requirements
+13852101305  UT      US           none                
+14077922414  FL      US           none                
+16033712156  NH      US           none                
+16036367116  NH      US           none                
+18312751816  CA      US           none                
+14693316717  TX      US           none                
+18312751822  CA      US           none    

Copy one of the numbers from the list and register it to your Twilio account by using:

twilio api:core:incoming-phone-numbers:create --phone-number="+13852101305"

If your registration attempt is successful, you should see:

SID                                 Phone Number  Friendly Name 
PN3ef900000000000000000000000000d9  +13852101305  (385) 210-1305

Once registered, the phone number is available for your use (until you release it using the CLI or Twilio Console). Note that the SID associated with the phone number is a user secret and should be handled securely.

To verify the number has been successfully added to your account, you can use the Twilio CLI to send a test message. Run the following command, taking care to replace the placeholder values with your Twilio phone number and your personal SMS-enabled number, in E.164 format:

twilio api:core:messages:create --from <your-twilio-phone-number> --to <SMS-receiver-phone-number> --body "Hello world"

Note: With a trial account you can only send messages to phone numbers you’ve previously registered to your account. The SMS-enabled phone number you used to sign up for your Twilio account is the first number you’ve registered.

The API will return a response similar to the below output to indicate the SMS message has been successfully received and is queued to be sent:

SID                                 From          To            Status  Direction     Date Sent
SM4a447328e80a43ceb8e61dda9f3d4cb6  +13852101305  +16463974810  queued  outbound-api  null  

Within a short time you should receive an SMS message on your phone:

Mobile phone lock screen with SMS message

You can check the status of the message creation request using the following CLI command:

twilio api:core:messages:fetch --sid SM4a447328e80a43ceb8e61dda9f3d4cb6

You will see a response similar to the following:

SID                                 From          To            Status     Direction     Date Sent                    
SM4a447328e80a43ceb8e61dda9f3d4cb6  +13852101305  +16463974810  delivered  outbound-api  Mar 13 2020 14:17:20 GMT+0100

If your message isn’t delivered you can use the status logs in the Twilio console to help you identify the problem. If you’re using a Twilio trial account, be sure you’re sending to a registered phone number.

Summary

In this post you’ve learned how to install and set up Twilio CLI and how to obtain a Twilio Phone number. This number is necessary to work with some of the Twilio products like Programmable SMS. You’ve also learned how to send SMS to any SMS-enabled number around the world with Twilio CLI.

Additional resources

Maciej Treder is a Senior Software Development Engineer at Akamai Technologies. He is also an international conference speaker and the author of @ng-toolkit. You can learn more about him at https://www.maciejtreder.com. You can also contact him at: contact@maciejtreder.com or @maciejtreder on GitHub, Twitter, StackOverflow, and LinkedIn.

Gabriela Rogowska contributed to this post.