Twilio Read
- Kalpana Malladi
- Gouri Bhagchandani
- Ankur Parekh
In this article
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
Works in Ultra Pipelines.
Limitations and Known Issues
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 | Specify a name for the Snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your pipeline. | 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. Twilio's API designs follow a hierarchical pattern to indicate relationships among entities. For example, you can build an autopilot assistant to answer incoming calls with a task model. In this case, the Task entity is considered as a parameter of Assistant entity. Each assistant has a unique SID, and one assistant can have multiple tasks associated with it. To retrieve the record for one of the tasks, you must provide the task's parent assistant SID in the Required SIDs table. Click
| |||
| 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:
For certain entities, you can provide Language or Date as the filter parameters; the input value format for these parameters should follow these standards:
| |||
| Field Name | String/Expression/Suggestion | Specify the parameter names to filter the results. You must enter only allowed parameters in this field. Use the suggestion list to identify the allowed parameters. The available options are:
| None | DateSent |
| Operator | String/Expression | Select the operator from the drop-down list. The available options are:
The operators ">=" and "<=" are applicable only for sequential properties, such as the date and time-related parameters. for example, DateSent, DateCreated, StartTime, and EndTime. | = | >= |
| 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 Twilio Read#Pagination 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. |
Pagination
By default, if no pagination parameters are provided, the Twilio API retrieves all the records under the given entity during batch reading. In the Read Snap, you can use the Page size field to limit the number of returned records in a single response. By default the Page size is set to 200. If the total amount of the target resources exceed the input Page size, the rest of the records are separated into the next pages of the designated size.
To get all the paginated records recursively, enter an expression in the Next URL field. The Next URL field of this Snap follows a similar format of the same field (Next URL) in Rest Get Snap, which should be structured as follows:
"<Twilio_Host_URL>" + $<next_page_url_path>,
- The first part of the Next URL <Twilio_Host_URL> should be the Twilio URL host of your required API Object, such as https://autopilot.twilio.com/ or https://lookup.twilio.com/.
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:
[
{
"twilioHostUrl": "https://api.twilio.com"
}
]
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
Important Steps to Successfully Reuse Pipelines
- Download and import the Pipeline into SnapLogic.
- Configure Snap accounts as applicable.
- Provide Pipeline parameters as applicable.
Snap Pack History
See Also
Have feedback? Email documentation@snaplogic.com | Ask a question in the SnapLogic Community
© 2017-2024 SnapLogic, Inc.