How to Publish Add-ons

The Twilio Marketplace is an API-enabled platform for third 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 can discover and install API-driven services through a central self-serve experience, and invoke them in a standard manner as part of the core Twilio API. Twilio manages the listing, configuration, developer-facing API endpoints, billing, and publisher payment for its third-party offerings.

This guide is designed for publishers who wish to integrate their services into the Twilio Marketplace in the form of an Add-on. It provides an overview of marketplace offerings and API requirements.

Add-Ons overview

At a functional level, Add-ons package publisher APIs, and annotate the content that Twilio provides by tapping into the publisher’s data sources or using a publisher’s technology to analyze the content. Examples include phone number based queries for demographic and marketing data, number fraud/spam blocklists, recording transcriptions, and message sentiment analysis.

Currently, the following Twilio content is available for Add-on publishers to build with: phone numbers, incoming message bodies, and call recordings.

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.

The figure below illustrates the timeline and flow of information between a developer, Twilio, and a publisher’s Add-on. If a developer sets up a recording Add-on to respond to voice calls, the voice call will be accepted by Twilio and sent to the developer’s webhook. Afterwards, the call could be recorded and the information sent back to Twilio. Twilio would then give the data to the recording Add-on for processing, and once the Add-on returns the relevant data to Twilio, Twilio sends the data to the developer.

Pricing and billing

The Twilio Marketplace allows publishers to share their Add-ons with developers. Add-on publishers set their own pricing scheme and then invoke the Twilio Billing System, which meters usage of Add-ons by developers and deducts credit from their accounts. Finally, the billed amounts are distributed to Add-on publishers, by invoice, after Twilio levies a transaction fee.

Publishers can choose to package one service/API into one Add-on, or deliver a service/API as multiple Add-ons. Delivering a service as multiple Add-ons may allow developers to adjust their expenses in accordance with their usage or the extent to which they need an Add-on.

Since Add-on publishers set their own pricing, billing models may be different between Add-ons. The following billing models are supported by the Add-on Marketplace:

• Pay-per-use.
• Pay-per-minute: For rranscription/recording Add-ons.
• Pay-per-success: Conditional billing subject to the absence of certain JSON elements in the response and HTTP status codes.

Publisher accounts

Twilio supports one ‘source’ account per publisher offering, and will use that to make all API requests.

To illustrate this, here’s an example of how your account will make API requests, and how that will function as an Add-on. Let’s say you have a web service that takes a phone number and returns all the English words you can spell with it. You’d like to let any Twilio customer access 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?e164=+18778894546"

This results in the following JSON response:

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

You deliver this service as a Marketplace Add-on, ‘Anagram’. A Twilio developer finds and installs this service on their account. They now 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. Afterwards, they would be able to make the following curl request:

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

This 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": {      
      "publisher_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 include them in the response payload along with the other types requested.

Discovery and 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, and 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 publisher 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. This time, Twilio POSTs data to the publisher and expects a 202 Accepted response back. The publisher will then post results back to a REST API exposed by Twilio some time later. In this model, Twilio will ask the developer for a callback URL at configuration time and take responsibility for relaying any asynchronous results back to them.

Publisher API requirements: requests

Twilio will be directly consuming publisher’s JSON/REST API, and transforming the returned data and error codes into a form 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:

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.

Common template fields

The following table lists the common template fields available to you.

Add-on type-specific template fields

See the 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 the Console, and the configured values are made available to the Add-on as template fields.

The 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 the UI with number validation).
• boolean (presented as checkbox in the UI).

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 the template fields {{language}}, {{combine_tracks}}, {{keywords}}, and {{phone_number}} available to your API.

Authentication

Since Twilio currently only supports one account per Publisher offering, it follows that there will be one set of authentication credentials for the publisher’s service supported per Add-on. The Publisher 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 publisher API that may be used for security and debugging purposes if the publisher so desires.

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

• JSON Schema Specification and Examples
• JSON Schema Validator

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

Publisher 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 publisher 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 publisher misconfiguration, or outage, will be logged in the error reporting system and will count against the publisher'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. Publishers should expect retries, using the request_sid as an idempotency token.

For async requests, the publisher 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 minimum 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 (paste in JSON form field).
2. Delete all the fields from the result that are not required
3. 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

• What is JSON Path
• Tools to get JSON Path: JSON Path Tool, Chrome Extension
• Tools to test your JSON Path: Paste your API response and JSON Path into the JSONPath Tool

Requirements for specific Add-on types

Phone Number Add-on

The Phone Number Lookup Add-on is used to expose 3rd party data publishers 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 publisher API.

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 50KB. 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 publisher API.

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 200msand 99% under 1500ms. Any request taking longer than 2000ms 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 64KB. 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 publishers 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 publisher API.

This request is asynchronous. A 202 or 204 response with no body is expected upon receiving this request. After processing the audio, publishers 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 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 100MB. 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 and privacy requirements

It is important to secure communication between Twilio and publishers, for both Twilio’s security as well as the publisher’s. Because publishers are opening up an HTTP endpoint to the public Internet, all efforts should be made to make certain the endpoint doesn’t expose the publisher 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 set up to only come from specific IPs. Twilio will contact publishers 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 publisher’s shared secret key. Publishers 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. Publishers 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) further protects publishers from replay attacks.