# How to Use Marketplace Listings This guide provides instructions on how to install, set up, and use No-code Partner and Add-on Listings from Twilio Marketplace. ## No-code Partner Listings ### Installation Installing a No-code Partner Listing makes it available to configure and use on the Listing publisher's platform. To install, follow these steps: 1. Navigate to the [Marketplace Catalog in Twilio Console](https://console.twilio.com/us1/develop/add-ons/catalog) and choose a No-code Partner Listing. 2. Select the **Install** button on the Listing details page. 3. Accept the Listing publisher's Terms of Service and Privacy Policy. ### Configuration After installation, the **Configure** tab becomes selectable from the Listing details page. To access the Listing details, visit the [Installed Modules page in Console](https://console.twilio.com/us1/develop/add-ons/installed) and select the Listing. The **Configure** tab details what next step you'll need to take with the Listing publisher. Select the button under the tab to complete the onboarding process on the publisher's platform. ## Add-on Listings ### Installation Installing an Add-on Listing makes it available to configure and use on your Twilio Account. To install, follow these steps: 1. Navigate to the [Marketplace Catalog in Twilio Console](https://console.twilio.com/us1/develop/add-ons/catalog) and choose an Add-on Listing. 2. Select the **Install** button on the Listing details page. 3. Accept the Listing publisher's Terms of Service and Privacy Policy. ### Configuration After installation, the **Configure** tab becomes selectable from the Listing details page. To access the Listing details, visit the [Installed Modules page in Console](https://console.twilio.com/us1/develop/add-ons/installed) and select the Listing. In the **Configure** tab, you can set up the Listing for integration with your Twilio products. This involves selecting the appropriate usage points and providing any additional configuration details required by the Listing. The table below details some of the configuration fields you can expect to see: | Configuration field | Description | User Configurable? | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | | Installed Add-on SID | Unique identifier for the Listing instance. Used for debugging, billing queries, and support requests when communicating with the Listing publisher. Example: `XBxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` | No | | Unique name | A human-readable unique identifier used to invoke specific Listings and to consume their results. Example: `twilio_caller_identity` | Yes (suffix only) | | Use in | A list of Twilio product usage points that this Listing supports and is enabled for | Yes | | Configuration parameters | Listing specific configuration parameters | Yes | The **Configure** tab also includes an **Add Another Instance** button. This feature allows you to add more instances of the same Add-on Listing, each with different configuration parameters. This can be useful in scenarios where you need different configurations of the same Listing, such as text analysis in various languages. For more information about the supported Twilio Products and configuration parameters of a specific Listing, please refer to the **Documentation** tab on its Listing details page. ### Invocation Once you've installed and set up your Listing, its invocation depends on the Twilio product you're integrating it with. The following table outlines how the usage of an Add-on Listing is triggered based on the specific Twilio product its being used in: | Twilio product | How to invoke Listing | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Lookup](/docs/lookup) | Use the `AddOns` parameter to specify the unique name of the Listing to be invoked. Use the format `AddOns..` to specify any additional run-time data required by the Listing. | | [Programmable SMS](/docs/messaging) | All installed and configured Listings are automatically invoked for each incoming SMS. Add-on Listings are currently not supported for outbound SMS. | | [Programmable Voice - Calls](/docs/voice) | All installed and configured Listings are automatically invoked for each incoming call. Add-on Listings are currently not supported for outbound calls. | | [Programmable Voice - Recordings](/docs/voice) | All installed and configured Listings are automatically invoked for each Recording. | ### Results The results from an Add-on Listing are delivered as a JSON object through the API of the Twilio product that the Listing is integrated with. | Twilio product | How to view Listing results | Synchronous results? | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | Lookup | Results are in the `add_ons` parameter in the API response. | Yes | | Programmable SMS | Results are in the `AddOns` parameter of the Incoming SMS webhook. `POST` callbacks only due to URL length constraints in `GET` callbacks. | Yes | | Programmable Voice - Calls | Results are in the `AddOns` parameter of the Incoming Voice TwiML callback. `POST` callbacks only due to URL length constraints in `GET` callbacks. | Yes | | Programmable Voice - Recordings | Results availability is in the `AddOns` parameter of the callback to the URL specified in the Listing's configuration parameters. | No | #### Synchronous results Listings that return results synchronously have the following development considerations: * SLA/Latency: Requests taking longer than 2000 ms are failed by Twilio and an error payload is sent. The developer is not billed. * Size limit: Listing result responses larger than 64 KB are failed by Twilio and an error payload is sent. The developer is not billed. Synchronous results are returned immediately as a JSON object by the relevant Twilio API. ```json title="Sample synchronous results response" { "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": { ... } } } } ``` The following tables detail the JSON object structure of the synchronous results response. | Key | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | `successful` or `fail`. | | `message` | Only present if `status` is `fail`, otherwise `null`. A descriptive message that explains what went wrong. | | `code` | Only present if `status` is `fail`, otherwise `null`. Marketplace error codes are in the 61xxx range, see [Error and Warning Dictionary](/docs/api/errors) for details on specific codes. | | `results` | A JSON object with the Listing's unique name as the key, and the result for that Listing instance as the value. See the `results` object details in the table below. | ##### `results` object details | Key | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request_sid` | The unique identifier for the request made with the Listing. | | `status` | `successful` or `fail`. | | `message` | Only present if `status` is `fail`, otherwise `null`. A descriptive message that explains what went wrong. | | `code` | Only present if `status` is `fail`, otherwise `null`. Marketplace error codes are in the 61xxx range, see [Error and Warning Dictionary](/docs/api/errors) for details on specific codes. | | `result` | A Listing instance's results as a JSON object. For details about the contents of this field, refer to the **Documentation** tab of the Add-on Listing's details page in [Console](https://console.twilio.com/us1/develop/add-ons/installed) | #### Asynchronous results Add-ons that return results asynchronously have the following development considerations: * SLA/Latency: Results should be returned in a median time of three times of the audio duration and 99% under five times of the duration. Any request taking longer than ten times of the duration is failed by Twilio and an error payload is sent. The developer is not billed. * Size limit: Result responses larger than 100 MB are failed by Twilio and an error payload is sent. The developer is not billed. * Retention period: Results are only available to retrieve for 30 days. They can be accessed using the [Add-on Results API](/docs/marketplace/api/recording-add-on-results). When an Add-on Listing's results are ready, they are sent as a JSON object to the callback URL that was specified during the Listing's setup. The example below illustrates the structure of the nested JSON object that is included within the `AddOns` key of the callback. ```json title="Sample asynchronous results callback for a Recording Analysis Add-on Listing"" { "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" } } } } ``` The following tables detail the JSON object structure of the asynchronous results response. | Key | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | `successful` or `fail`. | | `message` | Only present if `status` is `fail`, otherwise `null`. A descriptive message that explains what went wrong. | | `code` | Only present if `status` is `fail`, otherwise `null`. Marketplace error codes are in the 61xxx range, see [Error and Warning Dictionary](/docs/api/errors) for details on specific codes. | | `results` | A JSON object with the Listing's unique name as the key, and the results for that instance as the value. See the `results` object details in the table below. | ##### `results` object details | Key | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request_sid` | The unique identifier for the request made with the Listing. | | `status` | `successful` or `fail`. | | `message` | Only present if `status` is `fail`, otherwise `null`. A descriptive message that explains what went wrong. | | `code` | Only present if `status` is `fail`, otherwise `null`. Marketplace error codes are in the 61xxx range, see [Error and Warning Dictionary](/docs/api/errors) for details on specific codes. | | `payload` | An array of objects containing URLs for the actual results. See the `payload` object details in the table below. | | `links` | An object containing URLs for reference media, e.g. recordings, that were used to generate the results. See the `links` object details in the table below. | ##### `payload` object details | Key | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `content_type` | The MIME type of the content returned by the Listing, such as `application/json` or `audio/wav`. For details about the returned content, refer to the **Documentation** tab of the Add-on Listing's details page in [Console](https://console.twilio.com/us1/develop/add-ons/installed). | | `url` | A URL to access the payload content using the [Add-on Results Payload Data subresource](/docs/marketplace/api/recording-add-on-results-payloads). Perform a `GET` request using your authenticated Twilio credentials to retrieve this data. | ##### `links` object details | Key | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `recording` | The URL of the [Recording Instance resource](/docs/voice/api/recording) for the recording that generated the result. | | `add_on_result` | The URL of the Listing instance's result metadata. See the [Add-on Results subresource](/docs/marketplace/api/recording-add-on-results-payloads) for details. | | `payloads` | The URL of the Listing instance's result payload metadata. See the [Add-on Results Payload subresource](/docs/marketplace/api/recording-add-on-results-payloads) for details. |