Share
Twilio Setup Guide

Twilio is a cloud communications platform that allows users to programmatically make and receive phone calls, and exchange text messages.

Hevo uses the Twilio REST API to replicate the data present in your Twilio account into the desired Destination database or data warehouses for scalable analysis. You must provide the Twilio API key, which is a combination of the API string identifier (SID) and the API Secret, to allow Hevo to access the Twilio data.

Prerequisites

Creating the Twilio API Key

You require an API key to authenticate Hevo on your Twilio account.

  1. Log in to the Twilio console.

  2. Click the Admin drop-down and select Account management.

    Account management

  3. In the left navigation pane, under Keys & Credentials, click API keys & tokens.

    API key for Hevo

  4. On the API keys & tokens page, click Create API key.

    Create API key

  5. On the Create new API key page, provide the following credentials:

    • Friendly name: A name for your API key.

    • Region: The region where your Twilio data is stored.

    • Key type: The type of API key. This can be: Standard or Main. You must select the Main key type, so that Hevo can access the data in your accounts and sub-accounts. Read API Key Resource to know more about the two key types.

  6. Click Create.

    Create

  7. On the Copy secret key page, copy the API SID and Secret and save them securely like any other password. You can use these credentials while configuring your Hevo Pipeline.

  8. Select the confirmation check box below, and click Done.

    Copy API key and API SID

    You can view the API key that you created on the API keys and tokens page.

    Your API key

Configuring Twilio as a Source

Perform the following steps to configure Twilio as the Source in your Pipeline:

  1. Click PIPELINES in the Navigation Bar.

  2. Click + CREATE PIPELINE in the Pipelines List View.

  3. On the Select Source Type page, select Twilio.

  4. On the Configure your Twilio Source page, specify the following:

    Configure your Twilio Source

    • Pipeline Name: A unique name for your Pipeline, not exceeding 255 characters.

    • API SID: The string identifier (SID) for your API key.

    • API Secret: The secret for your API key, retrieved from your Twilio account.

    • Historical Sync Duration: The duration for which you want to ingest the existing data from the Source. Default duration: 6 Months.

      Note: If you select All Available Data, Hevo ingests all the data available in your Twilio account since March 13, 2008.

  5. Click TEST & CONTINUE.

  6. Proceed to configuring the data ingestion and setting up the Destination.

Data Replication

For Teams Created Default Ingestion Frequency Minimum Ingestion Frequency Maximum Ingestion Frequency Custom Frequency Range (in Hrs)
Before Release 2.21 6 Hrs 1 Hr 24 Hrs 1-24
After Release 2.21 6 Hrs 30 Mins 24 Hrs 1-24

Note: The custom frequency must be set in hours as an integer value. For example, 1, 2, or 3 but not 1.5 or 1.75.

  • Historical Data: In the first run of the Pipeline, Hevo ingests historical data for the Usage Records object on the basis of the historical sync duration selected at the time of creating the Pipeline and loads it to the Destination. Default duration: 6 Months.

  • Incremental Data: Once the historical load is complete, all new and updated records for the object, Usage Records are synchronized with your Destination according to the Pipeline frequency.

Schema and Primary Keys

Hevo uses the following schema to upload the records in the Destination:

Data Model

The following is the list of tables (objects) that are created at the Destination when you run the Pipeline:

Note: All objects other than Usage Records are Full Load objects.

Object Description
Accounts Contains the details about your Twilio account and sub-accounts. These details are stored according to the API SID and API Secret provided by the user. It is the topmost entity and acts as a parent for all the other objects.
Addresses Contains your and your customer’s physical location within a country.
Calls Contains the list of incoming and outgoing calls made to all the phone numbers available for an account.
Conferences Contains the details about conferences in your Twilio account.
Conversation Services Contains the details about conversations in your Twilio account. It also contains the child objects, Conversations, Conversation Roles, and Conversation Users.
Conversations Contains the list of the current participants in a conversation, and the messages that they have sent amongst each other.
Conversation Users Contains the details about all the users in a conversation. Users are participants in a conversation with privileges such as the ability to edit and delete messages.
Conversation Roles Contains the details about the roles that participants have been assigned in a conversation. This determines what they are able to do within a particular conversation, such as invite participants to be members of the conversation, post messages, and remove other participants from the conversation.
Flows Contains the individual workflows that you create. Workflows control how tasks are prioritized and arranged into queues, and how they should move across queues over time.
Incoming Phone Numbers Contains the phone numbers provisioned from Twilio and ported or hosted to Twilio.
Messages Contains the details about an inbound or outbound message.
Outgoing Caller IDs Contains the list of an account’s verified phone numbers. An Outgoing Caller ID represents a single verified number that may be used as a caller ID for making outgoing calls.
Trunks Contains the details of Session Initiation Protocol (SIP) Trunks in your Twilio account. SIP Trunks are used to create cloud-based solutions for providing IP-based communications.
Usage Records Contains the details about the actions, such as calls made and messages exchanged, by your Twilio account during any time period and by any usage category. This information makes it easy to build reporting and analytics tools for your application.

Limitations

  • Hevo does not load an Event into the Destination table if its size exceeds 128 MB, which may lead to discrepancies between your Source and Destination data. To avoid such a scenario, ensure that each row in your Source objects contains less than 100 MB of data.

Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Jan-07-2025 NA Added a limitation about Event size.
Nov-05-2024 NA Updated section, Creating the Twilio API Key as per the latest Twilio UI.
Mar-05-2024 2.21 Updated the ingestion frequency table in the Data Replication section.
Apr-04-2023 NA Updated section, Configuring Twilio as a Source to update the information about historical sync duration.
May-24-2022 1.89 New document.
Last updated on Jan 07, 2025

Tell us what went wrong

Skip to the section