Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Add-ons Quickstart


In this guide we'll highlight a few of the key features of Add-ons and set you up to use them today. Let's dive in.


Installing an Add-on

installing-an-add-on page anchor

Add-ons are enabled through the Twilio Console, and once installed, they enhance specific Twilio APIs, such as Twilio Voice(link takes you to an external page) and Twilio SMS(link takes you to an external page). Two popular features from Add-ons are extracting information about a phone number's current owner, and ensuring a number is compliant with Telephone Consumer Protection Act (TCPA) regulations.

Let's first take a look at how to get the information about a phone number's current owner by enabling an Add-on for SMS called Ekata Reverse Phone. Inside the new Add-on catalog you can see all of the available API Add-ons. Select Ekata Reverse Phone from the catalog, on the first row.

Add-ons Catalog — Ekata Reverse Phone.
Add-ons Ekata Reverse Phone — Information.

Clicking on the Add-on gives you additional information, including a description and access to the product's documentation. The two things you need to know about on this screen are:

  1. What APIs this will be enabled on — listed under Supported Products
  2. Whether or not the Add-on is Installed

Go ahead and click Install . You can view all installed Add-ons by clicking on Add-ons > Installed .

Ekata Reverse Phone add-on Lookup checked.

Since we're interested in Lookups on a phone number in this scenario, check the Lookups box under the Configure tab.

Using the Ekata Add-on

using-the-ekata-add-on page anchor

The Ekata Reverse Phone Add-on is now enabled for Lookups, so we will use the Twilio Lookups API in order to get data about a target phone number. Here is the code:

Phone Number Information Retrieval with the Ekata Reverse Phone Add-on

phone-number-information-retrieval-with-the-ekata-reverse-phone-add-on page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v1.phoneNumbers('+16502530000')
_10
.fetch({addOns: ['Ekata_Reverse_Phone'], type: ['carrier']})
_10
.then(phone_number => console.log(phone_number.addOns));

Output

_62
{
_62
"caller_name": {
_62
"caller_name": "EMPIRE STATE BUILDING",
_62
"caller_type": "BUSINESS",
_62
"error_code": null
_62
},
_62
"country_code": "US",
_62
"phone_number": "+16502530000",
_62
"national_format": "(212) 736-3100",
_62
"carrier": null,
_62
"add_ons": {
_62
"status": "successful",
_62
"message": null,
_62
"code": null,
_62
"results": {
_62
"whitepages_pro_caller_id": {
_62
"status": "successful",
_62
"request_sid": "XR28b8f152ae12345605b0b3cc34123456",
_62
"message": null,
_62
"code": null,
_62
"result": {
_62
"phone_number": "2127363100",
_62
"warnings": [],
_62
"historical_addresses": [],
_62
"alternate_phones": [],
_62
"error": null,
_62
"is_commercial": true,
_62
"associated_people": [],
_62
"country_calling_code": "1",
_62
"belongs_to": [],
_62
"is_valid": true,
_62
"line_type": "NonFixedVOIP",
_62
"carrier": "Level 3 Communications",
_62
"current_addresses": [
_62
{
_62
"city": "New York",
_62
"lat_long": {
_62
"latitude": 40.748731,
_62
"longitude": -73.986413,
_62
"accuracy": "RoofTop"
_62
},
_62
"is_active": null,
_62
"location_type": "Address",
_62
"street_line_2": null,
_62
"link_to_person_start_date": "2018-08-28",
_62
"street_line_1": "350 5th Ave",
_62
"postal_code": "10118",
_62
"delivery_point": "MultiUnit",
_62
"country_code": "US",
_62
"state_code": "NY",
_62
"id": "Location.4e81b857-1234-5678-31d29a3301e1",
_62
"zip4": "0110"
_62
}
_62
],
_62
"id": "Phone.f8396fef-1234-5678-bc7128b6fd99",
_62
"is_prepaid": false
_62
}
_62
}
_62
}
_62
},
_62
"url": "https://lookups.twilio.com/v1/PhoneNumbers/+12127363100"
_62
}

Looking at the JSON response, we can see that the Lookup returned basic information about the phone number that we queried. Depending on the type of phone number found, different subsets of information may be returned, though these results are wrapped into a dictionary for you to access. More information on all the potential return values and dictionary keys can be found within the Add-ons marketplace.


Using the Prove TCPA Compliance Lookups Add-on

using-the-prove-tcpa-compliance-lookups-add-on page anchor

Another Add-on, Prove, protects your business from hefty fines levied under TCPA regulations for texting the wrong number. The Prove TCPA Compliance Add-on can quickly tell you if the number you are about to send an SMS to is active and still owned by your customer, with 100% reliability.

To use this Add-on we'll need to install it just like we did with Ekata Reverse Phone. Go to your Add-on catalog(link takes you to an external page), locate and click on Prove TCPA Compliance, and click Install.

Add-ons Prove TCPA Compliance.

Since we want to leverage the Twilio Lookups API to find the TCPA Compliance information for a phone number, check the Lookups box under the Configure tab of the Prove TCPA Compliance Add-on. Afterwards, we are ready to query the TCPA Compliance information on our target phone number. Here is the code:

Deterministic TCPA Compliance with the Prove Add-on

deterministic-tcpa-compliance-with-the-prove-add-on page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_12
// Download the helper library from https://www.twilio.com/docs/node/install
_12
// Find your Account SID and Auth Token at twilio.com/console
_12
// and set the environment variables. See http://twil.io/secure
_12
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12
const authToken = process.env.TWILIO_AUTH_TOKEN;
_12
const client = require('twilio')(accountSid, authToken);
_12
_12
client.lookups.v1.phoneNumbers('+16502530000')
_12
.fetch({addOns: ['prove_tcpa_compliance'], addOnsData: {
_12
'prove_tcpa_compliance.RightPartyContactedDate': '20220101'
_12
}, type: ['carrier']})
_12
.then(phone_number => console.log(phone_number.addOns));

Output

_37
{
_37
"caller_name": null,
_37
"country_code": "US",
_37
"phone_number": "+16502530000",
_37
"national_format": "(650) 253-0000",
_37
"carrier": {
_37
"mobile_country_code": null,
_37
"mobile_network_code": null,
_37
"name": "Level 3 Communications, LLC",
_37
"type": "landline",
_37
"error_code": null
_37
},
_37
"add_ons": {
_37
"status": "successful",
_37
"message": null,
_37
"code": null,
_37
"results": {
_37
"payfone_tcpa_compliance": {
_37
"status": "successful",
_37
"request_sid": "XRd3a2991c9108bde3ca9589ed84d31463",
_37
"message": null,
_37
"code": null,
_37
"result": {
_37
"Status": 0,
_37
"Response": {
_37
"MSISDNType": "NonFixedVoIP",
_37
"NumberMatch": "I",
_37
"VerifyNumberTransactionId": "2019459819"
_37
},
_37
"RequestId": "XRd3a2991c9108bde3ca9589ed84d31463",
_37
"Description": "Success."
_37
}
_37
}
_37
}
_37
},
_37
"url": "https://lookups.twilio.com/v1/PhoneNumbers/+16502530000"
_37
}

The results from the TCPA Compliance Lookup are wrapped into a dictionary, which contains the key NumberMatch, indicating Y for a compliant number, N for a non-compliant number, and I for an indeterminate number. The dictionary also has some keys related to the identification of the device claiming ownership of the number. If you're looking for demographic and carrier information, you can access it with the Ekata Reverse Phone Add-on.

To learn more about using Add-ons check-out the Add-ons Reference.


Rate this page: