How to Register a Twilio Phone Number and Send an SMS Using the Twilio CLI
Time to read: 3 minutes
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.
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.
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 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:
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.
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.
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: firstname.lastname@example.org or @maciejtreder on GitHub, Twitter, StackOverflow, and LinkedIn.
Gabriela Rogowska contributed to this post.
From APIs to SDKs to sample apps
API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
The latest ebooks, industry reports, and webinars
Learn from customer engagement experts to improve your own communication.
Twilio's developer community hub
Best practices, code samples, and inspiration to build communications and digital engagement experiences.