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

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

offerings page anchor

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.

Add-on TypeAvailable Integration Point(s) for CustomersData available to PublishersConsumption Mode
Phone Number Add-onLookups, Incoming SMS, Incoming VoicePhone Number (single, to, from)Synchronous
Message Analysis Add-onIncoming SMSPhone Numbers, Message BodySynchronous
Recording Analysis Add-onRecordingsAudio 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.

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.

Add-Ons Overview.

Pricing and billing

pricing-and-billing page anchor

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.

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):


_10
https://www.example.com/twilio_phone_number_example?e164=+18778894546"

This results in the following JSON response:


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

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:


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

This would result in a 200 OK response with the body:


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

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

discovery page anchor

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

api-requirements page anchor

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

publisher-api-requirements-requests page anchor

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

api-parameters page anchor

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

API ParameterRequest Type
Querystring ParametersGET, POST
JSON DictionaryPOST
www-form-encodedPOST
HTTP HeadersGET, 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.

(warning)

Warning

Request time parameters are only supported for Lookup at this time.

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

Template FieldProvided by Integration PointsAdd-on TypeDescription
CONSTANTAllAllVendor 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}}AllAllAlphanumeric Unique identifier for every request. Use if you need a unique identifier in your API
{{vendor defined runtime field}}LookupAny 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}}AllAllAny 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
{{SHA256:template_field}}AllAllA SHA256 hash of any field, e.g., {{SHA256:primary_address}} for a SHA256 hash of {{primary_address}} template field in Phone Number integration
{{unix_timestamp}}AllAllA Unix timestamp

Add-on type-specific template fields

add-on-type-specific-template-fields page anchor

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

Custom configuration template fields

custom-configuration-template-fields page anchor

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(link takes you to an external page), 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(link takes you to an external page)
type-specific-keywords page anchor
  • 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).
(warning)

Warning

Object and array keywords are not supported.

  • 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.
  • Supported for input validation and the relevant error message shall be displayed when the input does not validate against the configuration schema.

Example schema:


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

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

addon configuration in console.

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).

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.

Header NameValue
X-Twilio-VendorAccountSidThe Account Sid of the publisher (your) account. Example: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Twilio-SignatureThe signature of this request, signed by the publisher's account, and used to verify the request came from Twilio unmodified. See the 'Validating Requests are coming from Twilio' section of the API security docs for details of the signature algorithms used. Example: 0FqS203W44/lM2UEM+51hRzwat4=
X-Twilio-RequestSidThe unique identifier of this particular publisher request. Used for billing and debugging. Example: MRxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Twilio-AddOnSidThe unique identifier for the Add-on being invoked. Use this to identify which of your Add-ons is generating this request. Example: XBxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Twilio-AddOnVersionSidThe 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. Example: XCxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Twilio-AddOnInstallSidThe unique identifier for a developers install of an Add-on. Use this to distinguish between developers using this particular Add-on. Example: XDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Twilio-AddOnConfigurationSidThe unique identifier for an instance of the installed Add-on. Example: XExxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request Validation Schema

request-validation-schema page anchor

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.

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.


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

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

Publisher API requirements: responses

publisher-api-requirements-responses page anchor

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

response-validation-schema page anchor

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(link takes you to an external page) (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/(link takes you to an external page) (Paste generated Schema from Code View and the full response from your API and ensure it validates)

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


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


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

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

add-on-specific-requirements page anchor

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.

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

Template FieldProvided by Integration PointsDescription
{{primary_address}}Incoming SMS, Incoming Voice call, LookupThe phone number being dipped, in E.164 format: +<country code><phone number>
{{secondary_address}}Incoming SMS, Incoming Voice callTo number, in E.164 format: +<country code><phone number>

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

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
add-on-response-size-limit page anchor

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.

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

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

Template FieldProvided by Integration PointsDescription
{{primary_address}}Incoming SMSThe phone number being dipped, in E.164 format: +<country code><phone number>
{{secondary_address}}Incoming SMSTo number, in E.164 format +<country code><phone number>
{{body}}Incoming SMSThe UTF-8 body of the SMS Message

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

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.

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

recording-analysis-add-on page anchor

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.

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

Template FieldProvided by Integration PointsDescription
{{audio_data}}RecordingsAudio file binary bytestream, in HTTP request body or HTTP multipart request (POST/PUT) with a name you specify
{{callback_url}}RecordingsOne time use URL to be used to provide Analysis results
{{channels}}RecordingsNumber of channels contained in audio
{{duration}}RecordingsDuration of the audio in milliseconds
{{format}}RecordingsAudio Mimetype. Default recording format is audio/x-wav
{{media_sid}}RecordingsRecording SID
{{size}}RecordingsSize of the audio in bytes

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

add-on-callback-authentication page anchor

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.

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

add-on-callback-size-limit page anchor

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

security-and-privacy-requirements page anchor

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.

Rate this page: