Determine carrier, phone number type, and caller info

Twilio Lookup allows you to get information about phone numbers programmatically. This information can include the name of the phone number's carrier, their type (landline, mobile, VoIP, etc.), the name of the caller, and far more than this example page can cover.

All this data can be indispensable in making your applications dynamic and able to handle different carriers. The following examples illustrate a small sample of what Lookup can enable in Twilio Functions, and we can't wait to see what else you will build.

To get started, use the following instructions to create a Function to host your code.

Create and host a Function

Before you run any of the examples on this page, create a Function and paste the example code into it. You can create a Function in the Twilio Console or by using the Serverless Toolkit.

ConsoleServerless Toolkit

If you prefer a UI-driven approach, complete these steps in the Twilio Console:

Log in to the Twilio Console and navigate to Develop > Functions & Assets. If you're using the legacy Console, open the Functions tab.
Functions are contained within Services. Click Create Service to create a new Service.
Click Add + and select Add Function from the dropdown.
The Console creates a new protected Function that you can rename. The filename becomes the URL path of the Function.
Copy one of the example code snippets from this page and paste the code into your newly created Function. You can switch examples by using the dropdown menu in the code rail.
Click Save.
Click Deploy All to build and deploy the Function. After deployment, you can access your Function at https://<service-name>-<random-characters>-<optional-domain-suffix>.twil.io/<function-path>
For example: test-function-3548.twil.io/hello-world.

You can now invoke your Function with HTTP requests, configure it as the webhook for a Twilio phone number, call it from a Twilio Studio Run Function Widget, and more.

Identify a phone number's carrier and type

The core functionality of Lookup is determining the carrier and type of a phone number. For example, the following Function code returns true for incoming calls from landline or mobile callers, and false for calls from VoIP callers. An application could use this information to filter out unsupported call types in a Studio Flow if called by a Run Function widget, or simply called as a REST API by your application.

Lookup with an E.164 Formatted Number

1exports.handler = async (context, event, callback) => {
2  // The pre-initialized Twilio client is available from the `context` object
3  const client = context.getTwilioClient();
4
5  // Grab the incoming phone number from a call/message webhook via event.From
6  // If invoked by a REST API call or Studio Run Function widget, it may be a
7  // parameter such as phoneNumber
8  // Example: https://x.x.x.x/<path>?phoneNumber=%2b15105550100
9  const phoneNumber = event.From || event.phoneNumber || '+15105550100';
10
11  try {
12    // Discover the phone number's carrier and type using the Lookup API with
13    // the `type: 'carrier'` argument
14    const result = await client.lookups
15      .phoneNumbers(phoneNumber)
16      .fetch({ type: 'carrier' });
17
18    console.log('Carrier name: ', result.carrier.name);
19    // 'Carrier name: AT&T'
20    console.log('Carrier type: ', result.carrier.type);
21    // 'Carrier type: mobile'
22
23    // Reject calls from VoIP numbers, and allow all others
24    return callback(null, result.carrier.type !== 'voip');
25  } catch (error) {
26    console.error(error);
27    return callback(error, null);
28  }
29};

Get a name associated with a phone number

Lookup can also retrieve the name of the individual or business associated with a phone number. Expanding on the previous example, convert the type argument to an array, and add 'caller-name' after 'carrier'.

If available, the response will include a name for the phone number and whether the name is for a business or consumer.

(warning)

Warning

Keep in mind that not all numbers will have names available.

You can then use this information to adjust application logic, format responses to use names to add personalization, and more.

For this example, the code attempts to format the caller's name and use it in a response, falling back to referencing the carrier name if the caller's name isn't accessible. To test this code out, paste the code into your existing Function, and set it as the A Call Comes In webhook handler for the Twilio phone number you wish to test. The following instructions will show you how to do so.

Lookup caller name and type

1// lodash is a default dependency for deployed Functions, so it can be imported
2// with no changes on your end
3const { startCase } = require('lodash');
4
5exports.handler = async (context, event, callback) => {
6  // The pre-initialized Twilio client is available from the `context` object
7  const client = context.getTwilioClient();
8
9  // Grab the incoming phone number from a call webhook via event.From
10  const phoneNumber = event.From;
11
12  try {
13    // Create a new voice response object
14    const twiml = new Twilio.twiml.VoiceResponse();
15    // Discover the phone number's name (if possible) by converting type
16    // to an array and appending 'caller-name' to the type argument
17    const result = await client.lookups
18      .phoneNumbers(phoneNumber)
19      .fetch({ type: ['carrier', 'caller-name'] });
20
21    console.log('Carrier name: ', result.carrier.name);
22    // 'Carrier name: AT&T'
23    console.log('Carrier type: ', result.carrier.type);
24    // 'Carrier type: mobile'
25    console.log('Caller name: ', result.callerName.caller_name);
26    // 'Caller name: DOE,JOHN'
27    console.log('Caller type: ', result.callerName.caller_type);
28    // Caller type: CONSUMER'
29
30    if (result.callerName.caller_name) {
31      // Attempt to nicely format the users name in a response, if it exists
32      const [lastName, firstName] = result.callerName.caller_name
33        .toLowerCase()
34        .split(',');
35      const properName = startCase(`${firstName} ${lastName}`);
36      twiml.say(`Great to hear from you, ${properName}!`);
37    } else {
38      // If we don't have a name, fallback to reference the carrier instead
39      twiml.say(`We love hearing from ${result.carrier.name} customers!`);
40    }
41
42    return callback(null, twiml);
43  } catch (error) {
44    console.error(error);
45    return callback(error, null);
46  }
47};

Set a Function as a webhook

For your Function to react to incoming SMS or voice calls, it must be set as a webhook for your Twilio number. There are a variety of methods to set a Function as a webhook:

Twilio ConsoleLegacy Twilio ConsoleTwilio CLITwilio server-side SDKs

Use the Twilio Console UI to connect your Function as a webhook:

Go to Products & Services > Numbers & Senders > Phone Numbers.
Select the phone number you'd like to connect to your Function.
Go to the Configuration Details tab.

To configure Messaging, choose Edit details in the Messaging section.
To configure Voice calls, choose Edit details in the Voice and emergency calling section.

Select the webhook method and provide your webhook URL. Select an HTTP method to handle responses.
Optional: Configure a secondary webhook in case the primary webhook fails.
Click the Save button.

In the legacy Twilio Console, connect your Function as a webhook:

Log in to the Twilio Console's Phone Numbers page.
Click on the phone number you'd like to have connected to your Function.
If you want the Function to respond to incoming SMS, find the A Message Comes In option under Messaging. If you want the Function to respond to Voice, find the A Call Comes In option under Voice & Fax.
Select Function from the A Message Comes In or A Call Comes In dropdown.
Select the Service that you are using, then the Environment (this will default to ui unless you have created custom domains ), and finally Function Path of your Function from the respective dropdown menus.

Alternatively, you could select Webhook instead of Function, and directly paste in the full URL of the Function.

Click the Save button.

You can also use the Twilio CLI to assign the Function as the webhook of your phone number.

Prerequisites

Twilio CLI installed and executable from your terminal.
Either the E.164 formatted value of your Twilio phone number (+1234567890), or its SID (PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX).
The full URL of your Function (https://test-1337.twil.io/my-test-function)

Once you have the CLI installed and the necessary information, run the following to connect the Function to respond to incoming SMS:

1twilio phone-numbers:update +1234567890 \
2  --sms-url https://test-1337.twil.io/my-test-function

If you prefer to have the Function respond to incoming calls instead, run:

1twilio phone-numbers:update +1234567890 \
2  --voice-url https://test-1337.twil.io/my-test-function

You may also use the SID of your Twilio phone number instead of the E.164 formatted phone number:

1twilio phone-numbers:update PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
2  --sms-url https://test-1337.twil.io/my-test-function

You can also use any of the available Twilio SDKs to assign the Function as the webhook of your phone number.