Get a phone number and send your first SMS

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:

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, 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
...

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

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

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.

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.

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 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
}

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.

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
]