Using Add-ons

Consuming Add-On Data

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 results returned as a JSON dictionary via the API specific to that product.

For some products (e.g. Lookup), you are also required to specify which Add-on you’d like to use, and any 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 Product How to use an enabled Add-on How to consume the Add-on results
Lookup Use AddOns parameter to specify the unique name of the Add-on to be invoked.

Supports AddOns.<unique_name>.<parameter_name> to specify additional run-time data if required by the Add-on,.
Add-on results are contained in the add_ons parameter in the response.
Programmable SMS All Add-ons enabled for this product inside the Console are automatically invoked for each incoming SMS.

Note: Add-ons are currently not supported for outbound SMS
Add-on results are contained in the AddOns parameter in the Incoming SMS webhook.

Note that they are only supported on POST callbacks due to URL length constraints in GET callbacks.
Programmable Voice - Calls All Add-ons enabled for this product inside the Console are automatically invoked for each incoming Voice call.

Note: Add-ons are currently not supported for outbound calls
Add-on results are contained in the AddOns parameter in the Incoming Voice TwiML callback.

Note that they are only supported on POST callbacks due to URL length constraints in GET callbacks.
Programmable Voice - Recordings All Add-ons enabled for this product inside the Console are automatically invoked for each Recording. Availability 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

Sync add-on flow

For Add-ons that are Synchronous in nature (such as most Lookup, Messaging, Incoming Voice Add-ons), results are returned to you within the relevant Twilio API, as a JSON dictionary with the following format:

Parameter Description
status successful or fail
code Error code if status = fail, else null. Add-on error codes are in the 61xxx range. See Error Reference page for explanations.
message Descriptive message that explains what went wrong. null if status was successful.
results JSON dictionary with the Add-on Unique Name as the key, and invocation results as the value:

The results field is a JSON dictionary with the Add-on Unique Name as the key, and Add-on results as the value:

Parameter Description
request_sid Unique identifier for this particular request made to the Add-on
status successful or fail
code Error code if status = fail, else null. Add-on error codes are in the 61xxx range. See Error Reference page for explanations.
message Descriptive message that explains what went wrong. null if status was successful.
result Add-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

Add-on Type SLA / Latency Size Limits
Phone Numbers & Message Analysis Add-ons Because this request is returned synchronously, in the flow of an Incoming Call, Lookup or SMS delivery, performance is key. 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. As a synchronous Add-on, this response for this is limited to a maximum of 64 KB. 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 Synchronous Add-on JSON response

Loading Code Samples...
Language
Format:
  • JSON
{
  "status": "successful",
  "message": null,
  "code": null,
  "results": {
    "provider1_phone_reputation": {
      "request_sid": "XRc1479687aadf64c62e6ab2b6e0077a1a",
      "status": "successful",
      "message": null,
      "code": null,
      "result": {
        ...
      }
    }, 
    "provider6_sentiment": {
      "request_sid": "XRb32a3b72dde3bb78af4d34416d4f14dc",
      "status": "successful",
      "message": null,
      "code": null,
      "result": {
        ...
        }
      }
    }
  }
}
{
  "status": "successful",
  "message": null,
  "code": null,
  "results": {
    "provider1_phone_reputation": {
      "request_sid": "XRc1479687aadf64c62e6ab2b6e0077a1a",
      "status": "successful",
      "message": null,
      "code": null,
      "result": {
        ...
      }
    }, 
    "provider6_sentiment": {
      "request_sid": "XRb32a3b72dde3bb78af4d34416d4f14dc",
      "status": "successful",
      "message": null,
      "code": null,
      "result": {
        ...
        }
      }
    }
  }
}
Applies to Add-ons for Lookup, Incoming Voice Calls, Incoming SMS and Taskrouter
Example of Synchronous Add-on response

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

Asynchronous Add-on Results

Async add-on flow

For Add-ons that are Asynchronous (for instance, all Recording Add-ons), the availability of Add-on result is notified via the Add-on Results Available Webhook as a POST request to the Callback URL specified in the Add-on Configuration Parameters.

Add-on Results Available Callback

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

Parameter Description
status successful or fail
code Error code if status = fail, else null. Add-on error codes are in the 61xxx range. See Error Reference page for explanations.
message Descriptive message that explains what went wrong. null if status was successful.
results JSON dictionary with the Add-on Unique Name as the key, and invocation results as the value

results field is a JSON dictionary with the Add-on Unique Name as the key, and Add-on results as the value:

Parameter Description
request_sid Unique identifier for this particular request made to the Add-on
status successful or fail
code Error code if status = fail, else null. See [link] for Error code explanations.
message Descriptive message that explains what went wrong. null if status was successful.
payload List of dictionaries containing URIs for the actual results.
links Dictionary containing URIs for reference media (ex. recordings) that was used to generate the results

payload dictionary format:

Parameter Description
content_type Mime type of the content returned by the Add-on (ex. application/json or audio/wav). See Add-on documentation for details of the content it returns.
url URL that contains the actual content. This is the Add-on Result Payload Data as outlined in the Add-on Results API here. Note: You will need to perform an authenticated GET using your Twilio credentials to retrieve this data.

links dictionary format:

Parameter Description
recording URL of the Recording Instance resource for the recording that generated the result
add_on_result URL of the Add-on Result instance metadata. See Add-on Results API here
payloads URL of the Add-on Result Payloads list metadata. See Add-on Results API here

Performance Considerations

Add-on Type SLA / Latency Size Limits
Recording Analysis Add-on Because this request is returned asynchronously, there are no hard requirements. These Add-ons are 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. As an asynchronous Add-on, this 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.

Example of Asynchronous Add-on Results available callback :

Loading Code Samples...
Language
Format:
  • JSON
{
    "status": "successful",
    "message": null,
    "code": null,
    "results": {
      "speech_to_text_addon": {
        "request_sid": "XR7b57f17eeae56053f034a8a819577e89",
        "status": "successful",
        "message": null,
        "code": null,
        "payload": [ 
          {
            "content_type":"application/json", 
            "url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000001/Data"
          },  
          {
            "content_type":"audio/wav", 
            "url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000002/Data"
          } 
        ],
        "links": {
          "add_on_result": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89",
          "payloads": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads",
          "recording": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx"
        }
      }
    }
}
{
    "status": "successful",
    "message": null,
    "code": null,
    "results": {
      "speech_to_text_addon": {
        "request_sid": "XR7b57f17eeae56053f034a8a819577e89",
        "status": "successful",
        "message": null,
        "code": null,
        "payload": [ 
          {
            "content_type":"application/json", 
            "url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000001/Data"
          },  
          {
            "content_type":"audio/wav", 
            "url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000002/Data"
          } 
        ],
        "links": {
          "add_on_result": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89",
          "payloads": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads",
          "recording": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx"
        }
      }
    }
}
Applies to callbacks received for Recording Analysis Add-ons. Note that this JSON is contained within the "AddOns" POST parameter.
Example of Asynchronous Add-on Results available callback

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

Add-on Results API

Results of Asynchronous Add-ons (such as Recording Add-ons) are also available via the Add-on Results API.

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 browsing the Twilio tag on Stack Overflow.

Loading Code Samples...
Format:
  • JSON
{
  "status": "successful",
  "message": null,
  "code": null,
  "results": {
    "provider1_phone_reputation": {
      "request_sid": "XRc1479687aadf64c62e6ab2b6e0077a1a",
      "status": "successful",
      "message": null,
      "code": null,
      "result": {
        ...
      }
    }, 
    "provider6_sentiment": {
      "request_sid": "XRb32a3b72dde3bb78af4d34416d4f14dc",
      "status": "successful",
      "message": null,
      "code": null,
      "result": {
        ...
        }
      }
    }
  }
}
{
  "status": "successful",
  "message": null,
  "code": null,
  "results": {
    "provider1_phone_reputation": {
      "request_sid": "XRc1479687aadf64c62e6ab2b6e0077a1a",
      "status": "successful",
      "message": null,
      "code": null,
      "result": {
        ...
      }
    }, 
    "provider6_sentiment": {
      "request_sid": "XRb32a3b72dde3bb78af4d34416d4f14dc",
      "status": "successful",
      "message": null,
      "code": null,
      "result": {
        ...
        }
      }
    }
  }
}
Format:
  • JSON
{
    "status": "successful",
    "message": null,
    "code": null,
    "results": {
      "speech_to_text_addon": {
        "request_sid": "XR7b57f17eeae56053f034a8a819577e89",
        "status": "successful",
        "message": null,
        "code": null,
        "payload": [ 
          {
            "content_type":"application/json", 
            "url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000001/Data"
          },  
          {
            "content_type":"audio/wav", 
            "url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000002/Data"
          } 
        ],
        "links": {
          "add_on_result": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89",
          "payloads": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads",
          "recording": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx"
        }
      }
    }
}
{
    "status": "successful",
    "message": null,
    "code": null,
    "results": {
      "speech_to_text_addon": {
        "request_sid": "XR7b57f17eeae56053f034a8a819577e89",
        "status": "successful",
        "message": null,
        "code": null,
        "payload": [ 
          {
            "content_type":"application/json", 
            "url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000001/Data"
          },  
          {
            "content_type":"audio/wav", 
            "url":"https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads/XH000002/Data"
          } 
        ],
        "links": {
          "add_on_result": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89",
          "payloads": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx/AddOnResults/XR7b57f17eeae56053f034a8a819577e89/Payloads",
          "recording": "https://api.twilio.com/2010-04-01/Accounts/AC05bxxx/Recordings/RE557cxxx"
        }
      }
    }
}