Skip to contentSkip to navigationSkip to topbar
On this page

Get a phone number and send your first SMS


(information)

Info

This example assumes that you already have a Twilio Account, have followed the setup instructions from the CLI Quickstart, and have a working CLI Profile to issue commands with.

If you have all of those prerequisites, please continue!

With the Twilio CLI installed, let's see how you can quickly go from not even having a Twilio telephone number to being able to do the following, all from the command line:

  • Purchase your first Twilio phone number
  • Send an SMS with Twilio
  • Level up your Twilio phone number to automatically respond to messages by connecting it to some TwiML
  • Get a customized list of all messages sent to your phone number
  • Get carrier details about one of those phone numbers

Send your first SMS

send-your-first-sms page anchor

List available phone numbers

list-available-phone-numbers page anchor

First, you'll need to figure out what Twilio phone numbers are available to purchase. We suggest getting a number with your local area code, but you can select any. Run the following command, substituting your own area code and country code(link takes you to an external page):

1
twilio api:core:available-phone-numbers:local:list \
2
--area-code 209 --country-code US

This command asks Twilio to list all Twilio phone numbers that are available for purchase. Since that's a pretty broad request, you're narrowing down the request by passing in two command line options(link takes you to an external page), which filter down the range of phone numbers to only those in the 209 area code of the United States. This will result in output like this:

1
Phone Number Region ISO Country Address Requirements
2
+12092645211 CA US none
3
+12095466138 CA US none
4
+12094081870 CA US none
5
+12093077478 CA US none
6
...
(information)

Info

Trying to find a Toll-Free phone number, so that you can test Twilio in the age of A2P10DLC? Replace the local part of your CLI command with toll-free, and remove the area-code parameter, like so:

1
twilio api:core:available-phone-numbers:toll-free:list \
2
--country-code=US

Purchase an available phone number

purchase-an-available-phone-number page anchor

Next, let's purchase a number. Select one of the available phone numbers from the previous results (don't forget to include the leading "+"), and run the following command but with that phone number in place of the one in this example:

1
twilio api:core:incoming-phone-numbers:create \
2
--phone-number "+12092645211"

When the command is successful, you'll see similar output to this:

1
SID Phone Number Friendly Name
2
PN5358fexxxxxxxxxxxxxxxxxxxxxxxxxx +12092645211 (209) 264-5211
(information)

Info

Save the SID value that you receive! It will be used in later examples.

Now for the magic to really happen. Copy the following command, replace the from value with your Twilio phone number, and to's value with your personal phone number (and the body, if you'd like). Then, run the command.

1
twilio api:core:messages:create \
2
--to +12127363100 \
3
--from +12092645211 \
4
--body "Ahoy"

You'll see a similar table of output once the SMS is on its way:

1
SID From To Status Direction Date Sent
2
SM980f... +12092645211 +1209....... queued outbound-api null

Congratulations! After a brief delay, you'll receive a text message from your Twilio phone number.


Being able to send SMS with Twilio is just touching the surface of what you can accomplish. Sending SMS is great, but let's take this a step further and make your Twilio phone number capable of responding to incoming messages as well.

Have your phone number respond to incoming SMS

have-your-phone-number-respond-to-incoming-sms page anchor

In order for a Twilio Phone number to respond to incoming SMS, you will need to provide your phone number with TwiML (XML-like instructions for how to respond) whenever a message comes in by defining a webhook (a URL that Twilio can send a request to that returns TwiML). Explaining all of that is beyond the scope of this CLI example, so please refer to the links to learn more about TwiML and webhooks.

To get your phone number responding to messages, copy the following command, substitute the value for sid with the SID value that you received when purchasing your number earlier, keep the sms-url value the same, and run the resulting command:

1
twilio api:core:incoming-phone-numbers:update \
2
--sid PN5358fexxxxxxxxxxxxxxxxxxxxxxxxxx \
3
--sms-url "https://www.twilio.com/docs/twiml-snippet/twilio-cli"

Feel free to copy that URL and visit it with your browser. You should see the following TwiML:

1
<Response>
2
<Message>Thanks for trying out twilio-cli!</Message>
3
</Response>

This is the TwiML that this webhook URL provides, and that your phone number will use to respond to any incoming messages. Go ahead and send an SMS to your Twilio phone number. You will receive the message "Thanks for trying out twilio-cli!".

If you want to customize your response, you'll need to craft your own TwiML and host it at another webhook URL. Check out the Messaging Docs on TwiML to learn about all of your options.

List the messages your number has received

list-the-messages-your-number-has-received page anchor

Assuming you or others have been sending messages to this new Twilio phone number of yours, Twilio maintains logs with information such as the phone numbers involved (both the sender and the recipient), the body of the message, the SMS' status, and more. To access this list, run the following command in your terminal:

twilio api:core:messages:list --to "+12092645211"

You'll receive a list like this, containing a set of predetermined columns including the SID of each message, the phone numbers involved, etc:

1
SID From To Status Direction Date Sent
2
SM6e5... +1206....... +12092645211 received inbound Oct 12 2022 ...
3
SMf1a... +1206....... +12092645211 received inbound Oct 13 2022 ...

Suppose you're only interested in the SID, what number the message came from, and would like to see the contents of each message. You can tell the Twilio CLI which specific properties you would like to see, and omit all others, by defining the properties option like so:

1
twilio api:core:messages:list \
2
--to="+12092645211" \
3
--properties="sid,from,body"

You'll now receive a much more tailored list of results:

1
SID From Body
2
SM6e5... +1206... Hello to you, too
3
SMf1a... +1206... Are we best friends?

These tables are great for quick inspection of data, but perhaps you want these results in another format that's easier to parse with a programming language or compatible with spreadsheet software. In that case, you can also specify alternative output formats, such as JSON or TSV with the -o option.

TSV output can be configured with the --properties option as you would expect, however, the CLI will return all possible data if JSON is requested. You'll need to then use a tool like jq(link takes you to an external page) to do filtering. For example:

1
twilio phone-numbers:list -o json \
2
| jq '.[] | {sid, phoneNumber, smsUrl, voiceUrl}'

This command will output:

1
{
2
"sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3
"phoneNumber": "+1209242XXXX",
4
"smsUrl": "https://very-secret.ngrok.io/sms",
5
"voiceUrl": "https://very-secret.ngrok.io/answer"
6
}
7
{
8
"sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
9
"phoneNumber": "+1646887XXXX",
10
"smsUrl": "https://handler.twilio.com/twiml/EHxxxx",
11
"voiceUrl": "https://demo.twilio.com/welcome/voice/"
12
}
13
{
14
"sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
15
"phoneNumber": "+1209337XXXX",
16
"smsUrl": "",
17
"voiceUrl": ""
18
}

Work with other Twilio APIs

work-with-other-twilio-apis page anchor

So far these examples have just been concerned with your Twilio phone number, but the CLI allows you to work with all of Twilio's APIs! One such API is that of Lookup.

Look up a phone number's carrier and caller name

look-up-a-phone-numbers-carrier-and-caller-name page anchor

Similar to how you previously interacted with Twilio's core API to get a phone number and send messages, you can also call various resources and provide options to configure your request.

Suppose your new Twilio phone number has been receiving repeat messages from a particular number, and you're curious to learn more about that number. You can call the Lookup API like so, providing the phone number as well as arguments that define your request and desired response output:

1
twilio api:lookups:v1:phone-numbers:fetch \
2
--phone-number +12127363100 \
3
--type carrier \
4
--type caller-name \
5
-o json

You will receive some JSON, such as this:

1
[
2
{
3
"callerName": {
4
"caller_name": null,
5
"caller_type": "UNDETERMINED",
6
"error_code": null
7
},
8
"countryCode": "US",
9
"phoneNumber": "+12127363100",
10
"nationalFormat": "(212) 736-3100",
11
"carrier": {
12
"mobile_country_code": "311",
13
"mobile_network_code": "489",
14
"name": "Verizon Wireless",
15
"type": "mobile",
16
"error_code": null
17
},
18
"addOns": null,
19
"url": "https://lookups.sydney.us1.twilio.com/v1/PhoneNumbers/+12127363100?Type=carrier&Type=caller-name"
20
}
21
]

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.