In this article
| Table of Contents | ||
|---|---|---|
|
Overview
Use this Snap to retrieve data resources from Twilio's REST APIs.
Prerequisites
- Valid Twilio Account SID.
- Auth Token corresponding to the Account SID.
Support for Ultra Pipelines
...
None.
Snap Input and Output
| Input/Output | Type of View | Number of Views | Examples of Upstream and Downstream Snaps | Description |
|---|---|---|---|---|
| Input | Document |
|
| A document containing details of the entity or data object to read a Twilio entity. |
| Output | Document |
|
| A document containing the data retrieved as a Twilio entity. |
Snap Settings
| Parameter Name | Data Type | Description | Default Value | Example | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Label | String |
| Twilio Read | Twilio Read All Entities | ||||||||
| API object | String/Expression | Required. Select the API that you want to access in Twilio instance. This drop-down contains APIs (set of business objects) defined by Twilio. | Programmable SMS | Autopilot | ||||||||
| Entity | String/Expression/Suggestion | Required. Select an entity that belongs to the corresponding API object chosen above. For example, Messages entity belongs to the Programmable SMS API object. In this field, the available entities are dynamically populated in the suggestion drop-down list based on the selected API object. You can choose an entity from the suggestion list dynamically or enter a static value. | Messages | Assistant | ||||||||
| Entity SID | String/Expression | Specify a unique ID for the entity that determines one specific resource under the given entity type.
| None | SM191d7edflkj987enm236eee168 | ||||||||
| Required SIDs | Use this field set to | |||||||||||
define the parent entity String Identifiers (SIDs) necessary for accessing the requested resources, if any.
Click | |||||
This field set |
contains the following fields:
| ||||||
| SID name | String/Expression/Suggestion | Specify the name of the SID to call the API. | None | ServiceSID | ||
| SID value | String | Specify the SID value for the corresponding SID name chosen above. | None | UG12ab345acdeg9jkm345jkm765x | ||
| Filter parameters | Use this field set to define the names and values of query parameters for filtering the API responses. Click This field set comprises the following fields:
| |||||
| Field Name | String/Expression/Suggestion | Specify the parameter names to filter the results.
The available options are:
| None | DateSent | ||
| Operator | String/Expression | Select the operator from the drop-down list. The available options are:
| = | >= | ||
| Field Value | String/Expression | Specify the value for service operation fields. The data type of this field depends on the field name chosen which can be String, Integer, or DateTime. | None | 2020-03-10T10:00-20:00 | ||
| Output Fields Pagination Options | Use this field set to add advanced options to define the pagination parameters for API response. This field set comprises the following fields:
| |||||
Page size | Integer | Specify the number of records the Snap must get in each page. See 1693024394 for more information. | 200 | 500 | ||
Next URL | Expression/Drop-down list | Enter an expression | ||||
that will be evaluated on the output document to a URL that the Snap must use to get the next page. This property is used for the pagination feature. |
The Next URL has two components, which are structured as follows:
| None | "https://api.twilio.com/2010-04-01" + $next_page_uri" | ||
| Connection details | Use this field set to configure the network connection parameters. This field set comprises the following fields:
| |||
Connection timeout | Integer | Required. Specify the connection timeout duration in seconds. | 30 | 60 |
Maximum request attempts | Integer | Required. Specify the maximum number of connection attempts if the connection fails or is timed-out. | 3 | 6 |
Retry request interval | Integer | Required. Specify the time in seconds to wait before retrying the connection request. | 1 | 3 |
| Snap Execution | ||||
| Dropdown list | Specifies the execution type:
| Validate & Execute | Validate & Execute |
Troubleshooting
| Error | Reason | Resolution |
|---|---|---|
| The input entity does not exist. | An invalid entity has been entered. | Click the suggestion drop-down list and select a valid entity. |
| One or more Required SIDs are missing | The required SIDs are mandatory for this Endpoint. | Check your settings under the Required SID table. Ensure that you have entered SID names and values for all the entries. |
You have an empty value in the Key/Value field. | The Field name field and Field value must not be empty for the Filter parameters. | Enter a valid key/value parameters (Field name field and Field value) for Filter parameters. |
| The Entity SID is missing. | The Entity SID is mandatory for this Endpoint. | Provide an Entity SID. Refer to Twilio Read Snap Settings for information on how to provide Entity SIDs. |
| The next page URL is illegal. | The next page URL can only be obtained in the output document. | Provide an expression in the Next URL field that will be evaluated on the output document to an URL, that the Snap must use to get the next page. |
...
| Info | ||
|---|---|---|
If you want to extract the <Twilio_Host_URL> from an upstream document, you can assign the JSON path referring to the host URL to the '$original' node in an expression. For example, if you have the following JSON document as the input:
You can obtain the URL value by assigning the key "twilio_host_url" to the $original in the expression: $original.twilio_host_url+ "=" + $next_page_uri |
- The second part $<next_page_url_path> should be an expression pointing to the JSON path in the API response that contains the other half of the URL with a page token in the query parameters for getting the next page.
Examples
Reading Messages Sent Using Twilio Programmable SMS Service
In this example we use the Twilio Read Snap to retrieve messages sent with Programmable SMS services based on certain filter parameters and pagination options. This example assumes that you have configured and authorized a valid Twilio Account. See Twilio Account.
First, we configure the Twilio Read Snap as shown below to filter the messages on Phone number and Date sent. We also want to view these messages in two pages.
- API object: Programmable SMS
- Entity: Messages
- Filter criteria: Messages sent from <$Phone number> and messages sent on date 2020-03-10T10:00-20:00
- Page size: 2
- Next URL: $original.Host+$next_page_url
A successful validation of this Snap generates a JSON array containing each page as an independent JSON object, as shown below. Expand one of the JSON objects and observe 2 messages present in the $messages array as specified in the Page Size field.
Also, note that there are 5 pages in total, with their page indexes marked under the $page node. 
At this point we bifurcate the pages into two different output views - the first two pages to the first output view and the remaining pages to the the second output view. So, we configure the Router Snap as shown below:
Finally, we add the JSON and XML Formatter Snaps connecting to the Router Snap where the diverted output ends.
We write the two outputs into files in different formats (XML and JSON) using a File Writer Snap. On successful execution, we see two files with the corresponding names, in the Project space.
Downloads
...