Twilio Add-ons

Add-ons are pre-integrated partner technologies that let developers do more with the Twilio API. They make it possible to quickly build rich communications experiences by combining Twilio and 3rd-party capabilities by giving you the ability to choose the right technology for your needs without having to learn, test, and manage different platforms.

Add-ons are available through the Twilio Marketplace; you can choose from a list of verified Add-ons and install them in a single click. Once installed, they enhance Twilio APIs to deliver the partner capability, such as returning the spam score of a phone number or providing sentiment analysis for a message.

Supported Products

Add-ons are currently available for Programmable SMS, Programmable Voice - Calls & Recordings, and Lookups.

They process the content that Twilio provides from these products by tapping into the Add-on Provider’s data sources or using their technology to analyze the it, and provide their results back to you as a JSON dictionary, added to the existing Twilio APIs you use today.

Examples of Add-ons include Phone number based queries for demographic & marketing data, Number fraud/spam blacklist, Recordings Transcription, Message sentiment analysis, etc.

The following Twilio content is available for Add-ons to enhance: Phone Numbers, Incoming Message body, Call recordings.

Add-on Type Products that support this type of Add-on Data available to Add-on Consumption Mode
Phone Number Add-on Lookups, Programmable SMS, Programmable Voice - Calls Phone Numbers Synchronous
Message Analysis Add-on Programmable SMS Phone Numbers, Message Body Synchronous
Recording Analysis Add-on Programmable Voice - Recordings Audio File (single & dual channel) Asynchronous

Terms of Service & Data Storage

Add-ons are provided and supported by Add-on providers in the Twilio Marketplace. As a part of the Add-on installation process, you will be required to accept the Add-on provider’s Terms of Service. Note that the Add-on is provided under the Partner’s Terms of Service & Privacy policy.

Configuration & Identifiers

Installing an Add-on creates an Instance of that Add-on that is tied to your account. The Add-on Instance holds the configuration information required to operate the Add-on. This includes the following:

Configuration Information
(available in Console)
What is it User Configurable
Enabled Twilio Products A list of Twilio products that this Add-on supports and is enabled on. Yes
Configuration Parameters Add-on specific configuration parameters. Yes
Add-on Unique Name Human readable unique identifier used to invoke specific Add-ons and consume their results in the Twilio APIs.

Example : twilio_caller_identity
Yes (Suffix only)
Add-on Install Sid Unique Identifier for this Add-on Instance. Used for debugging and billing queries, and required for support requests when you are communicating with the Add-on provider.

Example : MC000003333333333345678901234566
No

For Add-ons that support Configuration Parameters, you can create additional Instances, each with a different set of Enabled Twilio Products and Configuration Parameters. This allows you to create & invoke different configurations of an Add-on, for example, to analyze English and French language text. Refer to the specific Add-on’s documentation for information about the Twilio Products & Configuration Parameters it supports.

NOTE : Add-ons are currently installed and enabled at an Account level. In other words, when you enable an Add-on for a specific product such as Incoming SMS, it will be invoked for every incoming SMS. Some Twilio products (such as Lookups) may require that you specify the Add-on’s unique name to invoke that Add-on, in addition to enabling them for that product via the Console.

Consuming Add-On Data

See Using Add-ons

Pricing & Billing

The Marketplace allows Partners to set their own pricing for their Add-ons and invokes the Twilio Billing system for usage-based billing. Use of an Add-on will be metered by Twilio and deducted from the developers account.

The following billing models are supported by the Marketplace for an Add-on:

  • Pay-per-use

  • Pay-per-minute : For Recording Analysis Add-ons

  • Subscription (coming soon)

  • Installation (coming soon)

You can check pricing for Add-ons in the Marketplace catalog, and usage inside the Usage page in the Console.

Add-On Support

Add-ons are provided and supported by Add-on Partners in the Twilio Marketplace. Support information for Add-on Partners (Phone numbers, support email, expected resolution times and process) varies from Add-on to Add-on, and is documented in the Add-on detail page.

The following table outlines when to contact Twilio for Add-on related issues and when you need to reach out to the Add-on Partner.

Issue Support provided by
I don’t see AddOns parameter in my callbacks Twilio
Error Codes 61000, 61003, 61006, 61009 Twilio
Error Codes 61001, 61002, 61004, 61005, 61007, 61008, Add-on Partner
Error Codes other than those specified above Twilio
Add-on results are not accurate or as per expectations specified in the Add-ons documentation Add-on Partner

When you contact Twilio or an Add-on Partner to request support for an Add-on, you should provide the following information to help identify and resolve your issue.

Identifier What is it Where to find it
Add-on Unique Name Human readable unique identifier used to invoke specific Add-ons and consume their results in the Twilio APIs.

Example : twilio_caller_identity
Available in the Console, under the Installed Add-ons section.
Request Sid The unique identifier of a particular Add-on request. Used for billing and debugging.

Example : XR000009775bb6d43d1cabc4955723fae1
This is available in the API response or callback you receive from Twilio that contains the Add-on results.
Add-on Install Sid A unique identifier for a developers install of an Add-on.

Example : MC000003333333333345678901234566
Available in the Console, under the Installed Add-ons section.

Examples

Note that Add-ons are supported in the Next gen Twilio helper libraries only.

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • JSON
# Download the Python helper library from twilio.com/docs/libraries/python
from twilio.rest import Client


# Get your Account SID and Auth Token from twilio.com/console
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
client = Client(account_sid, auth_token)

number = client.lookups \
               .phone_numbers("+16502530000") \
               .fetch(add_ons="payfone_tcpa_compliance",
                      add_ons_data={"payfone_tcpa_compliance.RightPartyContactedDate": "20160101"})

print(number.add_ons)
// Download the C# helper library from twilio.com/docs/libraries/csharp
using System;
using System.Collections.Generic;
using Twilio;
using Twilio.Rest.Lookups.V1;
using Twilio.Types;

namespace Example
{
    class MainClass
    {
        public static void Main(string[] args)
        {
            // Get your Account SID and Auth Token from twilio.com/console
            const string accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
            const string authToken = "your_auth_token";

            TwilioClient.Init(accountSid, authToken);

            var addOns = new List<string> { "payfone_tcpa_compliance" };
            var addOnsData = new Dictionary<string, object>
            {
                { "payfone_tcpa_compliance.RightPartyContactedDate", "20160101" }
            };

            var phoneNumberFetcher =
                PhoneNumberResource.Fetcher(new PhoneNumber("+16502530000"));
            phoneNumberFetcher.addOns = addOns;
            phoneNumberFetcher.addOnsData = addOnsData;

            var number = phoneNumberFetcher.Fetch();
            Console.WriteLine(number.addOns);
        }
    }
}
<?php

// Download the PHP helper library from twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php'; // Loads the library

use Twilio\Rest\Client;

// Get your Account SID and Auth Token from twilio.com/console
$accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$authToken = "your_auth_token";

$client = new Client($accountSid, $authToken);

$number = $client->lookups
    ->phoneNumbers("+16502530000")
    ->fetch(
        [
            "addOns" => "payfone_tcpa_compliance",
            "addOnsData" => [
                "payfone_tcpa_compliance.RightPartyContactedDate" => "20160101"
            ]
        ]
      );

print_r($number->addOns);
# Download the Ruby helper library from twilio.com/docs/libraries/ruby
require 'twilio-ruby'

# Get your Account SID and Auth Token from twilio.com/console
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

# Initialize Twilio Client
@client = Twilio::REST::Client.new(account_sid, auth_token)

number = @client.lookups.v1
                .phone_numbers('+16502530000') \
                .fetch(add_ons: 'payfone_tcpa_compliance',
                       add_ons_data: {
                         'payfone_tcpa_compliance.RightPartyContactedDate' => '20160101'
                       })

print(number.add_ons)
// Get your Account SID and Auth Token from twilio.com/console
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

// Download the Node.js helper library from twilio.com/docs/libraries/node
const client = require('twilio')(accountSid, authToken);

client.lookups.v1
  .phoneNumbers('+16502530000')
  .fetch({
    addOns: 'payfone_tcpa_compliance',
    addOnsData: {
      'payfone_tcpa_compliance.RightPartyContactedDate': '20160101',
    },
  })
  .then(number => console.log(number.addOns));
// Download the Java helper library from twilio.com/docs/libraries/java
import com.twilio.Twilio;
import com.twilio.rest.lookups.v1.PhoneNumber;

import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Example {

    // Get your Account SID and Auth Token from twilio.com/console
    public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    public static final String AUTH_TOKEN = "your_auth_token";

    public static void main(String[] args) {
        Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

        List<String> addOns = Arrays.asList("payfone_tcpa_compliance");
        Map<String, Object> addOnsData = new HashMap<String, Object>() {{
            put("payfone_tcpa_compliance.RightPartyContactedDate", "20160101");
        }};

        PhoneNumber number = PhoneNumber
                .fetcher(new com.twilio.type.PhoneNumber("+15108675309"))
                .setAddOns(addOns)
                .setAddOnsData(addOnsData)
                .fetch();

        System.out.println(number.getAddOns());
    }
}
{
  "code": null,
  "message": null,
  "results": {
    "payfone_tcpa_compliance": {
      "code": null,
      "message": null,
      "request_sid": "XRbf6b302b9ba37726eb04bf590e937d3c",
      "result": {
        "Description": "Success.",
        "RequestId": "XRbf6b302b9ba37726eb04bf590e937d3c",
        "Response": {
          "MSISDNType": "Landline",
          "NumberMatch": "I",
          "PayfoneAlias": null,
          "VerifyNumberTransactionId": "1154411284"
        },
        "Status": 0
      },
      "status": "successful"
    }
  },
  "status": "successful"
}
Use a helper library to make a Lookups API request using the Payfone TCPA Compliance add-on.
Lookups with Payfone TCPA Compliance Add-on

Use a helper library to make a Lookups API request using the Payfone TCPA Compliance add-on.

Loading Code Samples...
Language
Format:
  • JSON
$ curl -XGET https://lookups.twilio.com/v1/PhoneNumbers/+16502530000/?AddOns=provider_caller_identity \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
{
  "caller_name": null,
  "country_code": "US",
  "phone_number": "+16502530000",
  "national_format": "(650) 253-0000",
  "carrier": null,
  "add_ons": {
    "status": "successful",
    "message": null,
    "code": null,
    "results": {
      "provider_caller_identity": {
        "status": "successful",
        "message": null,
        "code": null,
        "result": {
          "results": [
            {
              "id": {
                "type": "Phone"
              },
              "line_type": "NonFixedVOIP",
              "belongs_to": [
                {
                  "id": {
                    "type": "Business"
                  },
                  "name": "Captura Mexico",
                  "locations": null,
                  "phones": null
                }
              ],
              "associated_locations": [
                {
                  "id": {
                    "type": "Location"
                  },
                  "type": "Address",
                  "valid_for": null,
                  "legal_entities_at": null,
                  "city": "Mountain View",
                  "postal_code": "94043",
                  "zip4": "1351",
                  "state_code": "CA",
                  "country_code": "US",
                  "usage": "Business",
                  "delivery_point": "SingleUnit",
                  "address_type": "Street",
                  "lat_long": {
                    "latitude": 37.42197,
                    "longitude": -122.084137,
                    "accuracy": "RoofTop"
                  },
                  "is_deliverable": true,
                  "standard_address_line1": "1600 Amphitheatre Pkwy",
                  "standard_address_line2": "",
                  "is_historical": false
                }
              ],
              "phone_number": "6502530000",
              "country_calling_code": "1",
            }
          ],
          "messages": []
        },
        "requestSid": "XR54a299cf993e4a243dffe355be134f91"
      }
    }
  },
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+16502530000"
}
Use cURL to make a Lookup API request with a specific add-on to use specified in the query string.
Lookup with provider_caller_identity Add-on

Use cURL to make a Lookup API request with a specific add-on to use specified in the query string.

Loading Code Samples...
Language
{
  "status":"successful",
  "message":null,
  "code":null,
  "results":{
     "provider1_natural_tcpa_optout_detection":{
        "request_sid":"XR7b57f17eeae56053f034a8a819577e89",
        "status":"successful",
        "message":null,
        "code":null,
        "result":{
           "probability":0
        }
     },
     "provider2_language_insights":{
        "request_sid":"XR424628481f74b64b709950f1311b2235",
        "status":"successful",
        "message":null,
        "code":null,
        "result":{
           "status":"OK",
           "language":"english",
           "keywords":[
              {
                 "text":"Hi",
                 "relevance":"0.976891",
                 "sentiment":{
                    "type":"positive",
                    "score":"0.57102"
                 }
              },
              {
                 "text":"new add-ons",
                 "relevance":"0.935276",
                 "sentiment":{
                    "type":"positive",
                    "score":"0.415215"
                 }
              },
              {
                 "text":"Twilio",
                 "relevance":"0.728652",
                 "sentiment":{
                    "type":"positive",
                    "score":"0.415215"
                 }
              }
           ],
           "concepts":[

           ],
           "entities":[
              {
                 "type":"Company",
                 "relevance":"0.77978",
                 "sentiment":{
                    "type":"positive",
                    "score":"0.415215"
                 },
                 "count":"1",
                 "text":"Twilio",
                 "disambiguated":{
                    "name":"Twilio",
                    "dbpedia":"http://dbpedia.org/resource/Twilio",
                    "freebase":"http://rdf.freebase.com/ns/m.0h1bs6j"
                 }
              }
           ]
        }
     }
  }
}
With add-ons enabled, SMS webhooks will receive a new POST parameter, a JSON-encoded string called "AddOns" - this is an example of formatted JSON you'd receive in that webhook request.
Incoming SMS with Add-ons enabled (Webhook JSON format)

With add-ons enabled, SMS webhooks will receive a new POST parameter, a JSON-encoded string called "AddOns" - this is an example of formatted JSON you'd receive in that webhook request.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

1 / 1
Loading Code Samples...
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • JSON
# Download the Python helper library from twilio.com/docs/libraries/python
from twilio.rest import Client


# Get your Account SID and Auth Token from twilio.com/console
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
client = Client(account_sid, auth_token)

number = client.lookups \
               .phone_numbers("+16502530000") \
               .fetch(add_ons="payfone_tcpa_compliance",
                      add_ons_data={"payfone_tcpa_compliance.RightPartyContactedDate": "20160101"})

print(number.add_ons)
// Download the C# helper library from twilio.com/docs/libraries/csharp
using System;
using System.Collections.Generic;
using Twilio;
using Twilio.Rest.Lookups.V1;
using Twilio.Types;

namespace Example
{
    class MainClass
    {
        public static void Main(string[] args)
        {
            // Get your Account SID and Auth Token from twilio.com/console
            const string accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
            const string authToken = "your_auth_token";

            TwilioClient.Init(accountSid, authToken);

            var addOns = new List<string> { "payfone_tcpa_compliance" };
            var addOnsData = new Dictionary<string, object>
            {
                { "payfone_tcpa_compliance.RightPartyContactedDate", "20160101" }
            };

            var phoneNumberFetcher =
                PhoneNumberResource.Fetcher(new PhoneNumber("+16502530000"));
            phoneNumberFetcher.addOns = addOns;
            phoneNumberFetcher.addOnsData = addOnsData;

            var number = phoneNumberFetcher.Fetch();
            Console.WriteLine(number.addOns);
        }
    }
}
<?php

// Download the PHP helper library from twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php'; // Loads the library

use Twilio\Rest\Client;

// Get your Account SID and Auth Token from twilio.com/console
$accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$authToken = "your_auth_token";

$client = new Client($accountSid, $authToken);

$number = $client->lookups
    ->phoneNumbers("+16502530000")
    ->fetch(
        [
            "addOns" => "payfone_tcpa_compliance",
            "addOnsData" => [
                "payfone_tcpa_compliance.RightPartyContactedDate" => "20160101"
            ]
        ]
      );

print_r($number->addOns);
# Download the Ruby helper library from twilio.com/docs/libraries/ruby
require 'twilio-ruby'

# Get your Account SID and Auth Token from twilio.com/console
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

# Initialize Twilio Client
@client = Twilio::REST::Client.new(account_sid, auth_token)

number = @client.lookups.v1
                .phone_numbers('+16502530000') \
                .fetch(add_ons: 'payfone_tcpa_compliance',
                       add_ons_data: {
                         'payfone_tcpa_compliance.RightPartyContactedDate' => '20160101'
                       })

print(number.add_ons)
// Get your Account SID and Auth Token from twilio.com/console
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

// Download the Node.js helper library from twilio.com/docs/libraries/node
const client = require('twilio')(accountSid, authToken);

client.lookups.v1
  .phoneNumbers('+16502530000')
  .fetch({
    addOns: 'payfone_tcpa_compliance',
    addOnsData: {
      'payfone_tcpa_compliance.RightPartyContactedDate': '20160101',
    },
  })
  .then(number => console.log(number.addOns));
// Download the Java helper library from twilio.com/docs/libraries/java
import com.twilio.Twilio;
import com.twilio.rest.lookups.v1.PhoneNumber;

import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Example {

    // Get your Account SID and Auth Token from twilio.com/console
    public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    public static final String AUTH_TOKEN = "your_auth_token";

    public static void main(String[] args) {
        Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

        List<String> addOns = Arrays.asList("payfone_tcpa_compliance");
        Map<String, Object> addOnsData = new HashMap<String, Object>() {{
            put("payfone_tcpa_compliance.RightPartyContactedDate", "20160101");
        }};

        PhoneNumber number = PhoneNumber
                .fetcher(new com.twilio.type.PhoneNumber("+15108675309"))
                .setAddOns(addOns)
                .setAddOnsData(addOnsData)
                .fetch();

        System.out.println(number.getAddOns());
    }
}
{
  "code": null,
  "message": null,
  "results": {
    "payfone_tcpa_compliance": {
      "code": null,
      "message": null,
      "request_sid": "XRbf6b302b9ba37726eb04bf590e937d3c",
      "result": {
        "Description": "Success.",
        "RequestId": "XRbf6b302b9ba37726eb04bf590e937d3c",
        "Response": {
          "MSISDNType": "Landline",
          "NumberMatch": "I",
          "PayfoneAlias": null,
          "VerifyNumberTransactionId": "1154411284"
        },
        "Status": 0
      },
      "status": "successful"
    }
  },
  "status": "successful"
}
Format:
  • JSON
$ curl -XGET https://lookups.twilio.com/v1/PhoneNumbers/+16502530000/?AddOns=provider_caller_identity \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
{
  "caller_name": null,
  "country_code": "US",
  "phone_number": "+16502530000",
  "national_format": "(650) 253-0000",
  "carrier": null,
  "add_ons": {
    "status": "successful",
    "message": null,
    "code": null,
    "results": {
      "provider_caller_identity": {
        "status": "successful",
        "message": null,
        "code": null,
        "result": {
          "results": [
            {
              "id": {
                "type": "Phone"
              },
              "line_type": "NonFixedVOIP",
              "belongs_to": [
                {
                  "id": {
                    "type": "Business"
                  },
                  "name": "Captura Mexico",
                  "locations": null,
                  "phones": null
                }
              ],
              "associated_locations": [
                {
                  "id": {
                    "type": "Location"
                  },
                  "type": "Address",
                  "valid_for": null,
                  "legal_entities_at": null,
                  "city": "Mountain View",
                  "postal_code": "94043",
                  "zip4": "1351",
                  "state_code": "CA",
                  "country_code": "US",
                  "usage": "Business",
                  "delivery_point": "SingleUnit",
                  "address_type": "Street",
                  "lat_long": {
                    "latitude": 37.42197,
                    "longitude": -122.084137,
                    "accuracy": "RoofTop"
                  },
                  "is_deliverable": true,
                  "standard_address_line1": "1600 Amphitheatre Pkwy",
                  "standard_address_line2": "",
                  "is_historical": false
                }
              ],
              "phone_number": "6502530000",
              "country_calling_code": "1",
            }
          ],
          "messages": []
        },
        "requestSid": "XR54a299cf993e4a243dffe355be134f91"
      }
    }
  },
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+16502530000"
}
{
  "status":"successful",
  "message":null,
  "code":null,
  "results":{
     "provider1_natural_tcpa_optout_detection":{
        "request_sid":"XR7b57f17eeae56053f034a8a819577e89",
        "status":"successful",
        "message":null,
        "code":null,
        "result":{
           "probability":0
        }
     },
     "provider2_language_insights":{
        "request_sid":"XR424628481f74b64b709950f1311b2235",
        "status":"successful",
        "message":null,
        "code":null,
        "result":{
           "status":"OK",
           "language":"english",
           "keywords":[
              {
                 "text":"Hi",
                 "relevance":"0.976891",
                 "sentiment":{
                    "type":"positive",
                    "score":"0.57102"
                 }
              },
              {
                 "text":"new add-ons",
                 "relevance":"0.935276",
                 "sentiment":{
                    "type":"positive",
                    "score":"0.415215"
                 }
              },
              {
                 "text":"Twilio",
                 "relevance":"0.728652",
                 "sentiment":{
                    "type":"positive",
                    "score":"0.415215"
                 }
              }
           ],
           "concepts":[

           ],
           "entities":[
              {
                 "type":"Company",
                 "relevance":"0.77978",
                 "sentiment":{
                    "type":"positive",
                    "score":"0.415215"
                 },
                 "count":"1",
                 "text":"Twilio",
                 "disambiguated":{
                    "name":"Twilio",
                    "dbpedia":"http://dbpedia.org/resource/Twilio",
                    "freebase":"http://rdf.freebase.com/ns/m.0h1bs6j"
                 }
              }
           ]
        }
     }
  }
}