Add-on Publisher Guide

Twilio Marketplace is an API-enabled platform for 3rd parties to offer products and services that are built on or complementary to Twilio’s products, for sale to Twilio’s massive developer community.

Developers discover & install complementary, API driven services via a central self-serve marketplace experience and invoke them in a standard manner as part of the core Twilio API. Twilio manages the listing, configuration, developer facing API points, billing and partner payment.

This Guide is designed for 3rd party Partners who wish to integrate their services into the Twilio Marketplace. It provides an overview of marketplace offerings and API requirements.


Add-Ons Overview

The first type of product available in the Marketplace is an Add-on.

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; developers 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.

At a functional level, Add-ons package Partner APIs, and annotate the content that Twilio provides by tapping into the Partner’s data sources or using Partner’s technology to analyze the content. Examples include Phone number based queries for demographic & marketing data, Number fraud/spam blacklist, Recordings Transcription, Message sentiment analysis, etc.

Currently, the following Twilio content is available for Add-on partners to build with : Phone Numbers, Incoming Message body, Call recordings.

Add-on Type Available Integration Point(s) for Customers Data available to Partners Consumption Mode
Phone Number Add-on Lookups, Incoming SMS, Incoming Voice Phone Number (single, to, from) Synchronous
Message Analysis Add-on Incoming SMS Phone Numbers, Message Body Synchronous
Recording Analysis Add-on Recordings Audio File (single channel) Asynchronous

Developers select an Add-on and configure it for their account, making it available for use. They can then specify that they want it invoked when using a supporting Twilio API.

Add-on Flow

image alt text

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 a partner’s Add-on will be metered by Twilio and deducted from the developers account. The amount billed will be distributed to partners at regular intervals, less a transaction fee, via an invoice.

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

  • Pay-per-use

  • Pay-per-success (TBD) : Conditional billing subject to absence of certain JSON elements in the response and HTTP status codes.

  • Pay-per-minute : For Transcription / Recording Add-ons

Packaging Partner Service into Add-ons

Partners can offer one or more Add-ons in the marketplace. They can choose to package 1 service/API into one Add-on, or deliver 1 service/API as multiple Add-ons, each with a specific use case and associated pricing. Examples of the latter include different kinds of data sets (Business vs Consumer information) or Transcription for different languages.

Partner Accounts

Currently, Twilio supports one ‘master’ account per Partner offering, and will use that to make all API requests.

Example

Let’s say you have an web service that takes a phone number and returns all the english mnemonics you can spell with it. You’d like to let any Twilio customer dip your service via the Twilio Lookup API to see potential results, and you want to charge $0.0001 per lookup.

Assume that this is delivered by the following API (ignoring credentials for the time being):

https://www.example.com/twilio_phone_number_example  -d "e164=+18778894546"

Results in the following JSON response :

{
"anagrams": ["+18778TWILIO", ]
}

You would deliver this service as a marketplace Add-on -- ‘Anagram’, which contains all the marking and documentation collateral, as well as configuration pointing at the URL for a web service that confirms to Twilio's specification for phone number lookup services. A Twilio developer finds and installs this service on their account. They now would have the ability to use the Anagram Add-on in the Lookup API, when buying/provisioning phone numbers, receiving incoming calls or messages, or making outgoing calls or messages, if appropriate.

curl -X GET https://lookups.twilio.com/v1/PhoneNumbers/18778894546\
-d "AddOns=partner_anagrams" -u "{TwilioAccountSid}:{TwilioAuthToken}"

Would result in a 200 OK response with the body:

{
    "country_code": "US",
    "phone_number": "+18778894546",
    "national_format": "1 (877) 889-4546",
    "url": "https://lookups.twilio.com/v1/PhoneNumber/+551155256325",    
    "add_ons": {  
           "status": "successful",
           "message": null,
           "code": null,
           "results": {      
                    "partner_anagrams": {
                           "request_sid": "XRc1479687aadf64c62e6ab2b6e0077a1a",
                           "status": "successful",
                           "message": null,
                           "code": null,
                           "result": {
                                   "anagrams": ["+18778TWILIO"]
                           }                           
                    }
            }
    }
}

When invoked, Twilio will call out to your HTTP service and post the requested phone number. Upon receiving the results, it will take the JSON body of those results and included them in the response payload along with the other types requested.

Discovery & Usage

Developers will discover and install your Add-on using the Marketplace inside the Console. For more information on this process please refer to the Add-ons Overview documentation.

Add-On API Requirements

These specifications will detail how Twilio will make requests to your service, what fields you can expect for each supported Add-on type, how their success and error responses must be formatted and returned.

For most Add-on types, the interface is a simple RESTful HTTP protocol. For Add-ons such as phone number lookup, a synchronous request/response model is used, where Twilio POSTs data to the partner in a specified format and they reply with a valid result set or error in the response body.

For other Add-ons, such as recording analysis, an asynchronous model is used, where Twilio POSTs data to the partner and expects a 202 Accepted response back. The partner would then post back to a REST API exposed by Twilio to report results back some time later. In this model, Twilio will ask the developer for a callback URL at configuration time, and take responsibility for relaying any async results back to them.

Partner API Requirements - Requests

Twilio will be directly consuming partner's JSON/REST API, and transforming the returned data and error codes to a format compatible with the Twilio API style and format.

API Parameters

Twilio supports passing vendor-specific fields, template fields and constants to your API via one or more of the following parameters:

API Parameter Request Type
Querystring Parameters GET, POST
JSON Dictionary POST
www-form-encoded POST
HTTP Headers GET, POST

You can provide us with the parameters in your API that should be filled with the available template fields for the type of Add-on (refer to the sections below for list of available fields). You should request only those Template Fields that you absolutely require, so that Twilio can enable your Add-on across the widest possible range of Integration Points.

You can also tell us which parameters are user configurable, which ones should be hard-coded to specific values and which ones should be specified by the developer at request time.

Note that request time parameters are only supported for Lookup at this time.

Common Template Fields

The following table lists the Common Template Fields available to you.

Template Field Provided by Integration Points Add-on Type Description
CONSTANT All All Vendor specific constant data that you require us to hard code as an API parameter.
This value will be passed by Twilio for every call to the Vendor API.
{{request_sid}} All All Alphanumeric Unique identifier for every request. Use if you need a unique identifier in your API.
{{vendor defined runtime field}} Lookup - Any Vendor specific data beyond the ones in this list.
This parameter will have to be passed explicitly by the user in the API call and is not automatically filled in by Twilio.
{{custom configuration field}} All All Any Vendor specific data beyond the ones in this list.
This parameter will be configured by the user in the Console and is not automatically filled in by Twilio.

Add-on Type Specific Template Fields

See Requirements for Specific Add-on Types section for additional template fields that you can use.

Custom Configuration Template Fields

For instances where you may need additional parameters to be passed to your API, you can define custom fields that can be configured by the user in the Console. Once configured, Twilio will pass these parameters to your API just like other template fields.

User configurable parameters are specified as a JSON schema, provided in the "Configuration JSON Schema". These parameters are mapped into the corresponding UI elements inside console, and the configured values are made available to the Add-on as template fields.

Configuration JSON Schema supports the following JSON elements:

Type-specific Keywords:
  • string (presented as a text field in the UI)
  • number & integer (presented as text field in UI with number validation)
  • boolean (presented as checkbox in UI)

Note : object and array keywords are not supported

Generic keywords :
  • enum (presented as a dropdown list)
  • name (used to render the field label in the UI)
  • _help (used to render a tooltip next to the field in the UI)
  • element_name in the schema is used to define the template variable name.
Combining Schemas and Regular expressions :
  • Supported for input validation and the relevant error message shall be displayed when the input does not validate against the configuration schema.

Example schema :

{
  "title": "Config schema",
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "name": "Language",
      "_help": "Select the language for your recordings : US English (en_US), UK English (en_UK), Spanish (es)",
      "enum": ["en_US","en_UK","es"]
    },
    "combine_tracks": {
      "type": "boolean",
      "name": "Combine Audio Tracks",
      "_help": "Combine transcriptions from different tracks into one list or keep them separated"
    },
    "keywords": {
      "type": "string",
      "name": "Keywords to detect",
      "_help": "Identify the presence and timestamps for these keywords (Comma separated) in the audio"
    },
    "phone_number": {
      "type": "string",
      "name": "Phone Number",
      "_help": "E164 formatted phone numbers. Only +1 prefixes allowed",
      "pattern": "^\\+(1)+[0-9]*$"
    }
  },
  "required": [
    "language"
  ]
}

This schema generates the following UI, and makes these template fields: {{language}}, {{combine_tracks}}, {{keywords}} and {{phone_number}} available to your API.

addon configuration in console

Authentication

Since Twilio currently only supports one account per Partner offering, it follows that there will be one set of authentication credentials for the Partner’s service supported per Add-on. The Partner can choose to use a single set of credentials across all their offerings if so desired.

Following authentication schemes are supported:

  • Passing credentials in the URL query string

  • Passing credentials in the POST request body (WWW-form-encoded or JSON encoded)

  • HTTP header based authentication (Basic, Bearer)

Default HTTP Headers

Twilio will always pass the following set of headers along with the GET/POST request to the Partner API that may be used for security and debugging purposes if the partner so desires.

Header Name Value
X-Twilio-VendorAccountSid The Account Sid of the partner (your) account.

Example : AC05b3911315a1322d1dede66eed740000
X-Twilio-Signature The signature of this request, signed by the partner’s account, and used to verify the request came from Twilio unmodified. See the "Validating Requests are coming from Twilio" section here for details of signature algorithm : https://www.twilio.com/docs/api/security

Example : 0FqS203W44/lM2UEM+51hRzwat4=
X-Twilio-RequestSid The unique identifier of this particular partner request. Used for billing and debugging.

Example : MR000009775bb6d43d1cabc4955723fae1
X-Twilio-AddOnSid The unique identifier for the Add-on being invoked.

Use this to identify which of your Add-ons is generating this request.
ex. XBc6dc06ce91d566fae284bc2bf36218a4
X-Twilio-AddOnVersionSid The unique identifier of the Add-on version being used by the developer.

Use it to identify if the developer is using an older version of your Add-on.
ex. XC2ad3d7d6478a2ca72f224d817a241586
X-Twilio-AddOnInstallSid The unique identifier for a developers install of an Add-on.

Use this to distinguish between developers using this particular Add-on.
ex. XDe2767c53b3d7be099a825252c6cf4e59
X-Twilio-AddOnConfigurationSid The unique identifier for an instance of the installed Add-on.
ex. XEbee2b4cf26384f0b88ad98a25530c338

Request Validation Schema

If you desire, Twilio can validate the Add-on request using a Request Validation JSON Schema prior to invoking your API. This is typically useful in cases where your service cannot fulfill certain requests, and you wish to avoid a degraded customer experience or limit the load on your system.

When an Add-on request fails to validate, Twilio will return Error 61003 : "Requirements to invoke Add-ons have not been met" to the user and will not count it against your SLA.

The Request Validation Schema will be applied to a JSON dictionary containing the Template Fields specified above.

JSON Schema Tools

Example Schema

Use this to limit the Add-on to specific phone number prefixes. This example limits Vendor Add-on to phone numbers with +91 or +1 prefixes only.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "primary_address": {
      "type": "string",
      "pattern": "^\\+(91|1)+[0-9]*$"
    }
  },
  "required": [
    "primary_address"
  ]
}

Test the validity of the schema using the schema validator with the Input JSON field set to {"primary_address" : "+12345678901"}|

Partner API Requirements - Responses

Both success and error responses are expected to be in a standard JSON object format. The server is expected to return a 2xx response for all requests, even error requests. This is to disambiguate partner errors that may affect SLA from legitimately rejected requests due to misconfiguration or other. For successfully synchronous Add-on requests, a 200 OK response is expected, with a content-type application/json and a JSON object returned in the body. For successful asynchronous Add-on requests, a 202 Accepted response is expected, with no body returned. For both sync and async cases error cases, a 200 OK is expected with a content-type application/json and a JSON object describing the error condition.

Any 4xx or 5xx errors returned will be considered partner misconfiguration, or outage, will be logged in the error reporting system and will count against the partner's SLA. For 4xx errors, Twilio will fail the request immediately. For 5xx errors, Twilio will retry up to N times, or until the TTL has passed. Partners should expect retries, using the request_sid as an idempotency token.

For async requests, the partner is responsible for POSTing back the JSON object body to Twilio once the async task is completed. This JSON body will be the same format as above, for both success or failure.

Response Validation Schema

If specified, the Response Validation Schema ensures your response contains at least certain specific fields for it to be considered valid, and therefore, billed to the user.

To build a Response Validation Schema: 1. Paste your API response into the JSON schema generator : http://jsonschema.net/ (paste in JSON form field)

  1. Delete all the fields from the result that are not required

  2. Test Schema generated using the schema validator : http://www.jsonschemavalidator.net/ (Paste generated Schema from Code View and the full response from your API and ensure it validates)

Example Schema

For instance, If you wanted to validate that your API response (below) always contains the args.e164 parameter to be considered valid.

Example API Response

{
  "args": {
    "e164": "+13233633791",
    "test": "1"
  },
  "origin": "184.73.170.150",
}

JSON Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "args": {
      "type": "object",
      "properties": {
        "e164": {
          "type": "string"
        }
      },
      "required": [
        "e164"
      ]
    }
  },
  "required": [
    "args"
  ]
}

Response Cleaning

Use Response Cleaning JSON Paths to ask Twilio to delete specific elements from your Response. This typically includes API Keys (if they are returned), Usage counters, Vendor specific resource URIs, etc.

You can specify one or more JSON elements to remove using JSON Path

Requirements for Specific Add-on Types

Phone Number Add-on

The Phone Number Lookup Add-on is used to expose 3rd party data partners that use an e164 phone number as their query parameter. Examples of these are carrier dips, CNAM caller ID lookups, GPS lookups, demographic database queries, and so forth.

Add-on Request Fields

When invoked, Twilio can supply the following fields to the partner API.

Template Field Provided by Integration Points Description
{{primary_address}} Incoming SMS, Incoming Voice call, Lookup The phone number being dipped, in e164 format +<country code><phone number>
{{secondary_address}} Incoming SMS, Incoming Voice call To number, in e164 format +<country code><phone number>

This request will be synchronous. Twilio will expect a 200 OK with a valid response body.

Add-on SLA

Because this request is returned synchronously, either as part of a lookup API request or in the flow of a call or SMS setup, performance is key. A service exposing this should return in a median time of approx 200ms and 99% under 1500 ms. Any request taking longer than 2000 ms will be failed by Twilio, an error payload will be sent, and the developer will not be billed.

Add-on Response Size Limit

As a synchronous Add-on, this response for this is limited to a maximum of 50 KBytes. Any response larger than this maximum will be failed by Twilio, an error payload will be sent, and the developer will not be billed.

Message Analysis Add-on

The Message Analysis Add-on passes a message body to a 3rd party for content analysis. Possible use cases are translation or intent analysis.

Add-on Request Fields

When invoked, Twilio can supply the following fields to the partner API.

Template Field Provided by Integration Points Description
{{primary_address}} Incoming SMS The phone number being dipped, in e164 format +<country code><phone number>
{{secondary_address}} Incoming SMS To number, in e164 format +<country code><phone number>
{{body}} Incoming SMS The utf-8 body of the SMS Message

This request will be synchronous. Twilio will expect a 200 OK with a valid response body.

Add-on SLA

Because this request is returned synchronously, in the flow of the SMS delivery, performance is key. A service exposing this should return in a median time of approx 200ms and 99% under 1500 ms. Any request taking longer than 2000 ms will be failed by Twilio, an error payload will be sent, and the developer will not be billed.

Add-on Response Size Limit

As a synchronous Add-on, this response for this is limited to a maximum of 64 KBytes. Any response larger than this maximum will be failed by Twilio, an error payload will be sent, and the developer will not be billed.

Recording Analysis Add-on

The Recording Analysis Add-on Type is used to expose 3rd party partners who can analyze audio and return results as structured data. Examples of this are audio transcription, sentiment analysis services, audio indexing services, etc.

Add-on Request Fields

When invoked, Twilio can supply the following fields to the partner API.

Template Field Provided by Integration Points Description
{{audio_data}} Recordings Audio file binary bytestream*
{{callback_url}} Recordings One time use URL to be used to provide Analysis results
{{channels}} Recordings Number of channels contained in audio
{{duration}} Recordings Duration of the audio in milliseconds
{{format}} Recordings Audio Mimetype. Default recording format is audio/x-wav
{{media_sid}} Recordings Recording SID
{{size}} Recordings Size of the audio in bytes

*The audio data binary bytestream is provided in either 1) HTTP request body (POST/PUT) or 2) HTTP multipart request (POST/PUT) as a part with a name you specify.

This request is asynchronous. A 202 or 204 response with no body is expected upon receiving this request. After processing the audio, partners are expected to POST the JSON results to the Callback URL within the request timeout agreed upon. After the timeout expires, the request will be considered failed, and the developer will not be billed.

Add-on Callback Authentication

To authenticate the Callback HTTP request containing the audio analysis, we ask that you use basic authentication with the Account SID and Auth Token or an API Key (https://www.twilio.com/console/dev-tools/api-keys) created from the vendor account that the Add-on belongs to.

Add-on Callback SLA

Because this request is returned asynchronously, there are no hard requirements. A service exposing this is recommended to return in a median time of 3x audio duration and a 99% under 5x audio duration. Any request taking longer than 10x duration will be failed by Twilio, an error payload will be sent, and the developer will not be billed.

Add-on Callback Size Limit

As an asynchronous Add-on, the response for this is limited to a maximum of 100 MB. Any response larger than this maximum will be failed by Twilio, an error payload will be sent, and the developer will not be billed.

Security & Privacy Requirements

It is important to secure communication between Twilio and partners, for both Twilio's security as well as the partners. Because partners are opening up an HTTP endpoint to the public internet, all efforts should be made to make certain that endpoint does not expose the partner to fraud or attack. To ensure this, a number of mechanisms will be in place

  1. Twilio only supports HTTPS/TLSv1.2.

  2. To help mitigate any DDOS attack exposure, Twilio requests can be setup to only come from specific IPs. Twilio will contact partners before adding any IPs to this range. If you require such a setup, let us know. The default behavior is that they will not come from specific IPs.

    1. 174.129.222.33

    2. 174.129.222.200

    3. 184.73.170.150

    4. 23.21.226.67

  3. Twilio signs every request with the partner's shared secret. Partners are strongly encouraged to validate the signature of the requests they receive to confirm they're coming from their Twilio account.

  4. Twilio sends a unique request SID with each invocation. Partners are encouraged to treat this as an idempotency token, allowing them to thwart replay attacks.

  5. Twilio also sends an invocation date (UTC) and TTL as part of each signed payload. Checking this TTL (with a reasonable accommodation for clock-skew) allows partners to thwart replay attack.

Add-On Collateral Requirements

This section has moved. See Collateral Requirements for details.