Add-on Management API
This guide describes the APIs you can use to retrieve available and installed Add-ons. You can also use it to install specific Add-ons, and to manage any extensions they have. This API complements the Add-on capabilities exposed in the Console.
This API is currently in Developer Preview.
The Add-on Management API only supports Add-ons that are in General Availability (GA) or Beta state. Add-ons that are labeled as Coming Soon or Developer Preview are not accessible via the API and must be managed in the Console.
While this API is in Developer Preview, it should be accessed via the following base domain:
https://preview.twilio.com
The API may also be accessed via Next-gen helper libraries.
The Available Add-ons API
The Available Add-ons API provides detailed descriptions of the Add-ons currently available to be installed by an Account. This API does not allow you to mutate any of the records.
URIs
/marketplace/AvailableAddOns
/marketplace/AvailableAddOns/{AddOnSid}
Properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the AvailableAddOn resource. |
friendly_name
|
The string that you assigned to describe the resource. |
description
|
A short description of the Add-on's functionality. |
pricing_type
|
How customers are charged for using this Add-on. |
configuration_schema
|
The JSON object with the configuration that must be provided when installing a given Add-on. |
url
|
The absolute URL of the resource. |
links
|
The URLs of related resources. |
Available Add-on Instance resource
HTTP GET
Returns a single instance of an Available Add-on resource.
The Available Add-on Extensions API
The Available Add-on Extension subresource details where a given Available Add-on can be invoked.
URIs
/marketplace/AvailableAddOns/{AddOnSid}/Extensions
Properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the AvailableAddOnExtension resource. |
available_add_on_sid
|
The SID of the AvailableAddOn resource to which this extension applies. |
friendly_name
|
The string that you assigned to describe the resource. |
product_name
|
The name of the Product this Extension is used within. |
unique_name
|
An application-defined string that uniquely identifies the resource. |
url
|
The absolute URL of the resource. |
Available Add-on Extensions List resource
HTTP GET
Returns a list of Extension resources that detail the invocation points for the Available Add-on.
The Installed Add-ons API
The Installed Add-ons API allows you to install, configure, and manage Add-ons for an account. An Add-on may be installed multiple times on a given account, each with a different Add-on configuration. Upon installation, the Add-on is identified by an AddOnConfigurationSid property.
URIs
/marketplace/InstalledAddOns
/marketplace/InstalledAddOns/{AddOnConfigurationSid}
Properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the InstalledAddOn resource. This Sid can also be found in the Console on that specific Add-ons page as the 'Available Add-on Sid'. |
account_sid
|
The SID of the Account that created the InstalledAddOn resource. |
friendly_name
|
The string that you assigned to describe the resource. |
description
|
A short description of the Add-on's functionality. |
configuration
|
The JSON object that represents the current configuration of installed Add-on. |
unique_name
|
An application-defined string that uniquely identifies the resource. |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
url
|
The absolute URL of the resource. |
links
|
The URLs of related resources. |
Installed Add-ons List resource
HTTP GET
Returns a list of Installed Add-ons associated with the given account.
Installed Add-on Instance resource
HTTP GET
Returns a single instance of an Installed Add-on associated with the given account.
| Parameters in REST API format | |
|---|---|
available_add_on_sid
Required
|
The SID of the AvaliableAddOn to install. |
accept_terms_of_service
Required
|
Whether the Terms of Service were accepted. |
configuration
Optional
|
The JSON object that represents the configuration of the new Add-on being installed. |
unique_name
Optional
|
An application-defined string that uniquely identifies the resource. This value must be unique within the Account. |
HTTP POST
Allows you to update an Installed Add-on’s configuration by supplying a JSON object that uses the schema exposed by the Available Add-on.
| Parameters in REST API format | |
|---|---|
sid
Path
|
The SID of the InstalledAddOn resource to update. |
configuration
Optional
|
Valid JSON object that conform to the configuration schema exposed by the associated AvailableAddOn resource. This is only required by Add-ons that need to be configured |
unique_name
Optional
|
An application-defined string that uniquely identifies the resource. This value must be unique within the Account. |
HTTP DELETE
Uninstalls the Add-on from the account. If the Add-on is currently assigned to an Incoming Phone Number, the API will return a 400 error to inform the user that they must first remove the assignment. Successful responses will return no content.
The Installed Add-on Extensions API
An Extension identifies a Twilio product, or an integration point in a Twilio product, where the Add-on is invoked. Examples of Extensions include Record Verb, Dial Verb, the Lookup API, Incoming Voice Call, Incoming SMS, etc.
The Installed Add-on Extensions API provides you with the ability to view and configure when an Installed Add-on is invoked.
To allow you to control the roll-out of Add-ons, by default all Extensions will be disabled. This means you will need to make additional API requests to enable Extensions before they can use the installed Add-on. This will give you the opportunity to first associate an Installed Add-on with an Incoming Phone Number before enabling any Extensions.
The following table lists the currently supported Extensions. Each Add-on typically supports a subset of these Extensions.
| Product Name | Friendly Name | Unique Name |
|---|---|---|
| Lookup | Lookups | lookup-api |
| Programmable SMS | Incoming SMS Message | sms-incoming |
| TaskRouter | Create TaskRouter Tasks | taskrouter-create-task |
| Programmable Voice | Incoming Voice Call | voice-incoming |
| Programmable Voice | Record Verb Recordings | recording-verb |
| Programmable Voice | Outgoing Call (API) Recordings | recording-api |
| Programmable Voice | Conference Recordings | recording-conference |
| Programmable Voice | Dial Verb Recordings | recording-dial |
URIs
/marketplace/InstalledAddOns/{AddOnConfigurationSid}/Extensions
/marketplace/InstalledAddOns/{AddOnConfigurationSid}/Extensions/{AddOnExtensionSid}
Properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the InstalledAddOn Extension resource. |
installed_add_on_sid
|
The SID of the InstalledAddOn resource to which this extension applies. |
friendly_name
|
The string that you assigned to describe the resource. |
product_name
|
The name of the Product this Extension is used within. |
unique_name
|
An application-defined string that uniquely identifies the resource. |
enabled
|
Whether the Extension will be invoked. |
url
|
The absolute URL of the resource. |
Installed Add-on Extensions List resource
HTTP GET
Returns a list of Extensions where the Add-on can be invoked.
Installed Add-on Extension Instance resource
HTTP GET
Returns a single instance of an Add-on Extension resource.
HTTP POST
Allows you to activate or deactivate an Extension associated with the Installed Add-on.
Required parameters
| Parameters in REST API format | |
|---|---|
installed_add_on_sid
Path
|
The SID of the InstalledAddOn resource with the extension to update. |
sid
Path
|
The SID of the InstalledAddOn Extension resource to update. |
enabled
Required
|
Whether the Extension should be invoked. |
The Incoming Phone Number Assigned Add-ons API
The Incoming Phone Number Assigned Add-ons subresource details which Add-ons have been assigned to a given Twilio phone number. Assigning an Add-on to a specific Twilio phone number limits the invocation of that Add-on to Calls or Messages on that particular phone number.
Add-ons enabled for Recordings and TaskRouter do not support phone number assignments.
URIs
/2010-04-01/IncomingPhoneNumbers/{PhoneNumberSid}/AssignedAddOns
/2010-04-01/IncomingPhoneNumbers/{PhoneNumberSid}/AssignedAddOns/{AddOnConfigurationSid}
/2010-04-01/IncomingPhoneNumbers/{PhoneNumberSid}/AssignedAddOns/{AddOnConfigurationSid}/Extensions
Properties
As a subresource, this API will expose the same properties as the Installed Add Ons API.
Phone Number Assigned Add-on List resource
HTTP GET
Returns of a list of the Installed Add-ons assigned to the given Incoming Phone Number.
Phone Number Assigned Add-on Instance resource
HTTP GET
Returns a single instance of an Installed Add-on assigned to a given Incoming Phone Number.
HTTP POST
Allows you to assign an Installed Add-on to an Incoming Phone Number. The Add-on will only be invoked for the associated Incoming Phone Number.
Required parameters
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that will create the resource. |
resource_sid
Path
|
The SID of the Phone Number to assign the Add-on. |
installed_add_on_sid
Required
|
The SID that identifies the Add-on installation. |
HTTP DELETE
Deleting an Assigned Add-on instance resource will remove the binding between the Add-on and the Incoming Phone Number. Successful responses will return no content.
Phone Number Assigned Add-on Extensions
Properties
As a subresource, this API will expose the same properties in the Installed Add-ons Extension API.
Assigned Add-on Extension List Resource
HTTP GET
Returns a list of the Extensions for the Installed Add-on assigned to the given Incoming Phone Number.
Assigned Add-on Extension Instance resource
HTTP GET
Returns a single Extension for the Installed Add-on assigned to the given Incoming Phone Number.
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
