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

Using Add-ons



Consuming Add-On data

using page anchor

Add-ons are easy to use. After you install an Add-on and enable it for a specific Twilio product, all you have to do is consume the Add-on's results, which are returned as a JSON dictionary by the API specific to that product.

For some products — for example, Lookup — you are also required to specify which Add-on you'd like to use, and provide run-time data when you invoke the Twilio API. The table below summarizes how Add-ons are used and how to consume the Add-on results.

Twilio ProductHow to use an enabled Add-onHow to consume the Add-on results
LookupUse the AddOns parameter to specify the unique name of the Add-on to be invoked.Uses the format AddOns.<unique_name>.<parameter_name> to specify additional run-time data that may be required by the Add-on.Add-on results are contained in the add_ons parameter in the response
Programmable SMSAll Add-ons enabled for this product in the Console are automatically invoked for each incoming SMS.Add-ons are currently not supported for outbound SMSAdd-on results are contained in the AddOns parameter in the Incoming SMS webhook.Result delivery is only supported on POST callbacks due to URL length constraints in GET callbacks
Programmable Voice - CallsAll Add-ons enabled for this product in the Console are automatically invoked for each incoming call.Add-ons are currently not supported for outbound callsAdd-on results are contained in the AddOns parameter in the Incoming Voice TwiML callback.Result delivery is only supported on POST callbacks due to URL length constraints in GET callbacks
Programmable Voice - RecordingsAll Add-ons enabled for this product in the Console are automatically invoked for each RecordingAvailability of Add-on result is notified in the AddOns parameter in the callback to the URL specified in the Add-on Configuration Parameters

Synchronous Add-on results

synchronous-add-on-results page anchor
Sync add-on flow.

For Add-ons that are synchronous in nature, such as most Lookup, Messaging, and Incoming Voice Add-ons, results are returned to you by the relevant Twilio API. They are returned as a JSON dictionary with the following format:

ParameterDescription
statussuccessful or fail
codeAn error code if status is fail, else null. Add-on error codes are in the 61xxx range. See Error Reference page for details
messageA descriptive message that explains what went wrong, or null if status was successful
resultsA JSON dictionary with the Add-on Unique Name as the key, and invocation results as the value

results dictionary details

results-dictionary-details page anchor
ParameterDescription
request_sidA unique identifier for a particular request made to the Add-on
statussuccessful or fail
codeAn error code if status is fail, else null. Add-on error codes are in the 61xxx range. See Error Reference page for details
messageA descriptive message that explains what went wrong, or null if status was successful
resultAdd-on specific results as a JSON object. For details about the contents of this field, refer to the Add-on specific documentation that can be found in the Add-on detail page in the Console

Performance considerations

performance-considerations page anchor
Add-on TypeSLA/LatencySize Limits
Phone Numbers and Message Analysis Add-onsBecause this request is returned synchronously, in the flow of an Incoming Call, Lookup or SMS delivery, performance is key. Any request taking longer than 2000ms will be failed by Twilio, an error payload will be sent, and the developer will not be billedAs a synchronous Add-on, the 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

Example of a synchronous Add-on JSON response

example-of-a-synchronous-add-on-json-response page anchor

Applies to Add-ons for Lookup, Incoming Voice Calls, Incoming SMS and Taskrouter


_26
{
_26
"status": "successful",
_26
"message": null,
_26
"code": null,
_26
"results": {
_26
"provider1_phone_reputation": {
_26
"request_sid": "XRc1479687aadf64c62e6ab2b6e0077a1a",
_26
"status": "successful",
_26
"message": null,
_26
"code": null,
_26
"result": {
_26
...
_26
}
_26
},
_26
"provider6_sentiment": {
_26
"request_sid": "XRb32a3b72dde3bb78af4d34416d4f14dc",
_26
"status": "successful",
_26
"message": null,
_26
"code": null,
_26
"result": {
_26
...
_26
}
_26
}
_26
}
_26
}
_26
}


Asynchronous Add-on results

asynchronous-add-on-results page anchor
Async add-on flow.

For Add-ons that are asynchronous, such as all Recording Add-ons, the availability of an Add-on result is indicated by an Add-on Results Available webhook issued as a POST request POST request to the Callback URL specified in the Add-on Configuration Parameters.

Add-on Results Available callback

add-on-results-available-callback page anchor

The Add-on Results Available webhook body contains an AddOns parameter with a JSON dictionary in the following format:

ParameterDescription
statussuccessful or fail
codeAn error code if status is fail, else null. Add-on error codes are in the 61xxx range. See Error Reference page for details
messageA descriptive message that explains what went wrong, or null if status was successful
resultsA JSON dictionary with the Add-on Unique Name as the key, and the invocation results as the value
ParameterDescription
request_sidA unique identifier for a particular request made to the Add-on
statussuccessful or fail
codeAn error code if status is fail, else null. Add-on error codes are in the 61xxx range. See Error Reference page for details
messageA descriptive message that explains what went wrong, or null if status was successful
payloadA list of dictionaries containing URIs for the actual results
linksA dictionary containing URIs for reference media, e.g., recordings, that was used to generate the results

payload dictionary format

payload-dictionary-format page anchor
ParameterDescription
content_typeThe Mime type of the content returned by the Add-on, such as application/json or audio/wav. See the Add-on documentation for details of the content it returns
urlA URL at which you can access the content itself. This is the Add-on Result Payload Data as outlined in the Add-on Results API. You will need to perform an authenticated GET using your Twilio credentials to retrieve this data
Add-on TypeSLA/LatencySize Limits
Recording Analysis Add-onBecause this request is returned asynchronously, there are no hard performance requirements. These Add-ons should 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 billedAs an an asynchronous Add-on, this 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

Example of an asynchronous Add-on Results Available callback

example-of-an-asynchronous-add-on-results-available-callback page anchor

Applies to callbacks received for Recording Analysis Add-ons. Note that this JSON is contained within the 'AddOns' POST parameter.


_28
{
_28
"status": "successful",
_28
"message": null,
_28
"code": null,
_28
"results": {
_28
"speech_to_text_addon": {
_28
"request_sid": "XR7b57f17eeae56053f034a8a819577e89",
_28
"status": "successful",
_28
"message": null,
_28
"code": null,
_28
"payload": [
_28
{
_28
"content_type":"application/json",
_28
"url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000001/Data"
_28
},
_28
{
_28
"content_type":"audio/wav",
_28
"url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000002/Data"
_28
}
_28
],
_28
"links": {
_28
"add_on_result": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89",
_28
"payloads": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads",
_28
"recording": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx"
_28
}
_28
}
_28
}
_28
}

Results retention period

results-retention-period page anchor

The results produced by Asynchronous Add-ons, such as Recording Add-ons, are only available for 30 days. They can be access using the Add-on Results API.


Rate this page: