# Guide: Using Twilio with Databox (Custom API Integration)

## Overview

Twilio is a customer engagement platform used by businesses and developers worldwide to build unique, personalized experiences for their customers.

The Twilio integration is designed for more tech-savvy users, as it syncs data through a Custom API integration. In order to create Twilio metrics in Databox, you'll need to use the Metric Builder. Learn more about the basics of Metric Builder for Custom API Integrations [here](/master-overview-custom-api-integrations).

If you'd like us to help you get set up with Twilio in Databox, please fill out this request form or book a call with one of our product experts: - Free Databox users (or potential users) book a call here - Paying Databox customers book a call here

## Integration basics

| Integration status | Beta |
|  --- | --- |
| Type of Account access needed | Administrator (permission to create key or just use created key with Main permissions)  NOTE: Only Administrator account access can generate the “Main” key type that is needed to create a successful data connection. |
| Authorization type | Basic |
| Available endpoints | All REST endpoints |
| Available requests | All GET requests |
| Needed permissions (scopes) | / |
| Allowed API versions | All currently active API versions. Example: You can use a v1 of an API or v4, as long as they are both still supported. Deprecated APIs normally stop returning data. |
| Timezone | UTC |
| Dynamic date range support | Yes |
| Pagination support | Yes |
| Type of Pagination supported | Next-page |
| Rate Limits | Yes |
| Official documentation | - [https://www.twilio.com/docs/usage/api](https://www.twilio.com/docs/usage/api) - [https://www.twilio.com/docs/usage/api/keys](https://www.twilio.com/docs/usage/api/keys) - [https://www.twilio.com/docs/usage/requests-to-twilio](https://www.twilio.com/docs/usage/requests-to-twilio)

 |
| Follow the status of the API on the official changelog | - [https://www.twilio.com/docs/voice/sdks/javascript/changelog](https://www.twilio.com/docs/voice/sdks/javascript/changelog)

 |


## How to connect Twilio to Databox

![](/assets/guide-using-twilio-with-databox-custom-api-integration_1.5e43e012a799321627c2a4a0d7e675232d245b4552f4726c933ba43cca024dd4.4783b0ec.gif)

To connect a Twilio Account in Databox, go to  **Data Manager > + New connection.** Type**Twilio** in the search bar and click on the **Connect**button. Next, click the green **Connect now** button.

This will open the  **Authorization** window, which is where you will be prompted to enter your **Account SID**, **API Key (SID)**and **API Key Secret** to authorize the Databox app. Learn how to access these [here](/guide-using-twilio-with-databox-custom-api-integration).

![](/assets/guide-using-twilio-with-databox-custom-api-integration_2.0b3240aabcd818901325a86476111d71a63abb4462be06674b7ea30dbe472633.4783b0ec.png)

## How to access your API key, access token / API key secret?

To successfully connect your Twilio with Databox, you will need to use your  **Account SID, API Key (SID) and API Key Secret** in the connect process.

To access the **Account****SID** in your Twilio Account follow the steps below:

1. Login to your Twilio Account.
2. To find your Account SID, navigate to **Account > General Settings**.
3. Copy your **Account SID**and paste it in the Databox's **Activate Twilio**Window.


![](/assets/guide-using-twilio-with-databox-custom-api-integration_3.9be5b6158c2ab6c2192c2a2ef29edc58258a233164000f4b938205bab281e8e7.4783b0ec.jpg)

To find your **API Key and API Key Secret** in your Twilio Account, follow the steps below:

1. Login to your Twilio Account
2. Navigate to **Account > API keys & tokens**
3. Click on the  **Create API Key** button on the right-hand side
4. Add the required information in the **Create new API key** window and from the **Key type drop-down**, select **Main**. Click on the **Create API Key**button.


![](/assets/guide-using-twilio-with-databox-custom-api-integration_4.b5f7e59ab4c0804d79bed0830e3e2367f79e40a3d73d4ff92ea67b8a5554a037.4783b0ec.png)

1. Copy your **API Key (SID)**and the **API Key Secret** and paste them in the Databox's **Activate Twilio** Window.


The API Key Secret above is only shown once so make sure you copy it.

![](/assets/guide-using-twilio-with-databox-custom-api-integration_5.e49de1f08cd81f9f0e41f181f0da3d7df726c6234e406edb683e3d0017d3a326.4783b0ec.jpg)

1. Once you have pasted the**Account SID, API Key (SID)** and**API Key Secret**in Databox's **Activate Twilio**Window, click the green **Activate** button to authorize the Databox app.


Only accounts you have access to, can be used to connect your data sources.

## What's the maximum amount of historical data initially available when you use a new Twilio Data Source Metric in Databox?

The amount of historical data available in Databox is dependent on the custom metric setup, API limitations, pagination limitations, and the user's Databox plan:

- Custom Metric Setup: When a user creates a metric using an endpoint that supports date time parameters in the API request, those date time parameters determine the amount of historical data that will be pulled for the given metric. You can learn more about the date time parameters [here](/master-overview-custom-api-integrations).
- API Limitations: APIs may have limits set by the system itself on the amount of historical data that is stored/ can be accessed.
- Pagination Limitations: The pagination limit is set to 100 pages, which means that pagination will stop when the 100th page is reached. In cases where the metric is using pagination, of course, the interplay of date time parameters and pagination can have an impact on how much of the historical data the user can pull for a given metric. Learn more [here](/master-overview-custom-api-integrations).
- Databox Plan: The amount of historical data you're able to access in Databox is dependent on your Databox plan. Learn more [here](/choose-a-subscription-plan).


In order to start syncing data for a Metric, you can add it to your Metrics screen, use it in a Scorecard, set a Goal around it, create an Alert for it, or add it to a Databoard. Learn more [here](/data-sync-storage-security-in-databox).

## What time zone does Twilio data sync in?

Twilio data is synced in UTC. Currently, the API only supports dynamic dates on the GET [/v3/subscribers](https://developers.convertkit.com/#subscribers) endpoint.

## What type of pagination is supported by Twilio Integration

Pagination is only applicable for the GET [/v3/subscribers](https://developers.convertkit.com/#subscribers) and GET [/v3/purchases](https://developers.convertkit.com/#purchases) endpoints. The pagination limit is set to 100 pages, which means the pagination will stop when the 100th page is reached. The default amount of items that the API returns are 100.

Learn more about pagination [here](/master-overview-custom-api-integrations).

## How to access pre-built Twilio Metrics

1. Navigate to **Metrics > Metric Library**.
2. In the  **Browse by Data Source**section, click the Data Source dropdown and search for **Twilio**. This will filter out pre-built Twilio Metrics.


## How to create custom Twilio Metrics

Let's walk through how to create a Custom Metric for Twilio.

In order to prepare API requests, you should reference API-specific documentation that can be found in the Databox app through the **API Docs** link in the top right of the **Prepare API Request** page. Or, use this [direct link](https://www.twilio.com/docs/usage/api/keys).

1. Navigate to **Metrics > Custom Metrics** to access the Metric Builder for Twilio.
2. Click the green + **New Custom Metric** button and select your connected Twilio Account from the **Data Source** drop-down list.
3. Open the **API documentation for Twilio** to find the **endpoint** that will return the data needed for the given custom metric you wish to create.
4. Click the drop-down to select **GET**or **POST**as the HTTP Method. This is dependent on the information you found in the API documentation.
5. The Base URL is already predefined, you will need to copy the **missing part**of your chosen endpoint to sync the appropriate data.
6. Add **Parameters**based on your HTTP Method. Parameters limit the records returned for the API request.
  1. If you're creating a GET request, define the Key and Value pair(s). The API documentation provides information on endpoints for a field/ argument, which will be the Key. The condition (i.e., an ID, true/ false, etc.) will be the Value.
If the API documentation for Twilio states that the Integration supports dynamic date ranges, you will be able to click the  **calendar**icon to add datetime parameters.
  2. If you're creating a POST request, define the relevant JSON body.
Click on the  **calendar** icon to add datetime parameters.
  3. Pro Tip: You can choose multiple Keys and Values for one Custom Metric. You can add an additional Key and Value by clicking on “+”.
7. You can add Headers that include Key and Value pairs if the API needs this to successfully return data.
8. If the endpoint supports pagination, we recommend you select the appropriate method using the **Pagination Method**dropdown.
9. Once you have the basic setup, click on the green **Continue** button. You will be directed to the **Select value** step.
10. In the **Select value**step, select a property that includes the metric value you'd like to track in your Custom Metric. A metric value must be purely numeric.
11. Once you have selected the value, click on the green **Continue** button.
12. The **Segment by dimension**step is optional. This step will be taken into account only when you are trying to create a dimensional metric. If you'd like to segment your metric by multiple dimensions, choose one to complete during this set up, then begin again and select a different dimension until each desired metric is created.
  1. To skip this step, select **None**.
13. The **Select date** step is optional as well.
  1. **Use current time of storing data (Dynamic)**: Select this option if you don't want to select a date field
  2. **Use a field from response (optional)**: Select this if you want to select a date in order to see your data in predefined intervals.
14. In the **Preview & Customize**step, you can see the JSONata expression that has been created based on your selection of properties.
  1. You can customize the JSONata expression (optional) in the right editor panel.
15. To continue, click on the **Preview data** button to validate the expression and returned data.
16. Once you have previewed your data, click on the green **Continue**button to proceed to the last step of setting up your Custom Metric.
17. In the **Describe metric**step, you can set up the following:
  1. Name your metric: Enter a name for your custom metric.
  2. Data Aggregation: These selections determine how your data is handled. This especially impacts the way data is grouped and displayed for longer Date Ranges. Learn more [here](https://developers.databox.com/metric-definition/#aggregation-functions).
  3. Favourable trend: You can select when "Trending UP is positive" or "Trending DOWN is positive," since some metrics are better (positive) when the value is lower (like Bounce rate, Churn rate, etc.). This will affect how comparison values and goal comparisons are calculated and calculated.
18. Once you completed the **Describe metric** step, click the green **Continue**button to finish the Custom metric setup.


## Integration Limitations

- Databox limits the use of its integrations to GET requests. This is because our integration only reads your data.
- **Rate limits**: Learn more about Twilio API's Rate limits [here](https://www.twilio.com/docs/usage/rest-api-best-practices#know-your-limits)


If specific scopes of an integration allow you to create, change, delete or manipulate data in any other way, using such API calls can result in unexpected behavior. Databox is in no way liable for such API calls.