Skip to main content

Twilio

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable Self-Managed EnterpriseAvailable PyAirbyte
Support Level
Airbyte
Connector Version
0.17.10 (last updated 2 days ago)
Definition ID
b9dc6155-672e-42ea-b10d-9f1f1fb95ab1

This page contains the setup guide and reference information for the Twilio source connector.

Prerequisites​

Twilio HTTP requests to the REST API are protected with HTTP Basic authentication. In short, you will use your Twilio Account SID as the username and your Auth Token as the password for HTTP Basic authentication.

You can find your Account SID and Auth Token in the Twilio Console.

For more information, see the Twilio API authentication documentation.

Setup guide​

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. In the top-right corner, click +new source.
  3. On the Set up the source page, enter a name for the Twilio connector and select Twilio from the source type dropdown.
  4. Enter your Account ID (Twilio Account SID).
  5. Enter your Auth Token.
  6. Enter a Replication Start Date. Records created before this UTC date and time aren't synced. Use the format YYYY-MM-DDTHH:MM:SSZ (for example, 2020-10-01T00:00:00Z).
  7. Optionally, configure the following fields:
    • Lookback window: The number of minutes before the last cursor value to re-fetch on each incremental sync. Use this to catch late-arriving records. Defaults to 0.
    • Number of concurrent threads: The number of worker threads used during a sync. Defaults to 3. Maximum is 40.
    • Slice Step Duration: The time window size used for each slice of an incremental stream. See Tuning the slice step duration. Defaults to 1 Month (P1M).
  8. Click Set up source.

For Airbyte Open Source:

  1. Navigate to the Airbyte Open Source dashboard.
  2. Set a name for your source.
  3. Enter your Account ID (Twilio Account SID).
  4. Enter your Auth Token.
  5. Enter a Replication Start Date in the format YYYY-MM-DDTHH:MM:SSZ.
  6. Optionally, set the Lookback window, Number of concurrent threads, and Slice Step Duration. See the Cloud instructions above for details.
  7. Click Set up source.

Supported sync modes​

The Twilio source connector supports the following sync modes:

FeatureSupported?
Full Refresh SyncYes
Incremental SyncYes
Replicate Incremental DeletesNo
SSL connectionYes
NamespacesNo

Supported Streams​

Performance considerations​

The Twilio connector gracefully handles rate limits using the Retry-After header with an exponential backoff fallback. For more information, see Twilio's rate limit documentation.

Alerts pagination limit​

The Alerts API limits each request to 10,000 Alert resources. If the alerts stream fails because a time window contains more than 10,000 Alert records, reduce Slice Step Duration to sync fewer Alert records per request.

Tuning the slice step duration​

Incremental streams page the Twilio API in fixed-size time windows between the replication start date and now. The Slice Step Duration option controls the size of those windows and lets you trade request count against the amount of data each request returns.

OptionISO 8601 valueWhen to use
1 DayP1DVery high volume accounts where monthly or weekly windows trigger Twilio timeouts or exceed the result size Twilio returns.
1 WeekP1WHigh volume accounts that still time out with monthly windows.
1 MonthP1MDefault. Works well for most accounts and minimizes request count compared to shorter windows.
1 YearP1YLow volume accounts or short backfills where you want to minimize the number of slices per stream.

Smaller windows increase the number of API requests and are more likely to be rate limited, but they reduce the amount of data Twilio must return per request. Larger windows reduce request count but can time out on busy accounts. If syncs of the calls, messages, recordings, message_media, conference_participants, usage_records, or alerts streams fail with timeouts, lower the slice step duration.

Reference​

This connector uses REST APIs, including the https://api.twilio.com/2010-04-01, https://monitor.twilio.com/v1, https://conversations.twilio.com/v1, https://studio.twilio.com/v1, https://chat.twilio.com/v2, https://trunking.twilio.com/v1, and https://verify.twilio.com/v2 API endpoints.

For programmatic configuration, use these parameter names:

FieldRequiredDescription
account_sidYesAccount identifier used as the HTTP Basic authentication username.
auth_tokenYesAuth Token used as the HTTP Basic authentication password.
start_dateYesDate and time in YYYY-MM-DDTHH:MM:SSZ format. Records before this date aren't replicated.
lookback_windowNoNumber of minutes before the last cursor value to re-fetch on each incremental sync. Defaults to 0.
num_workerNoNumber of concurrent threads to use during a sync. Valid values are 1 through 40. Defaults to 3.
slice_step_durationNoTime window size for each incremental stream slice. Valid values are P1D, P1W, P1M, and P1Y. Defaults to P1M.

Reference​

Config fields reference

Field
Type
Property name
string
account_sid
string
auth_token
string
start_date
integer
lookback_window
integer
num_worker
string
slice_step_duration

Changelog​

Expand to review
VersionDatePull RequestSubject
0.17.102026-05-1277988Improve the Twilio Alerts pagination-limit error message.
0.17.92026-04-3077593Fix usage_records start_date schema format from date-time to date to prevent null primary key in Iceberg destination
0.17.82026-04-2877453Update dependencies
0.17.72026-04-2272494Add configurable slice step duration (default: 1 month)
0.17.62026-04-2176801Update dependencies
0.17.52026-04-1376276Rename "concurrent workers" to "concurrent threads" in connector spec
0.17.42026-01-2272260Update CDK version from 7.0.1 to 7.6.5
0.17.32025-11-1468680Handle 404 errors gracefully for date ranges with no data
0.17.22025-10-2268591Add suggestedStreams
0.17.12025-09-1566090Update to CDK v7
0.17.02025-09-0565955Promoting release candidate 0.17.0-rc.2 to a main version.
0.17.0-rc.22025-09-0465936Fix lookback window
0.17.0-rc.12025-08-2565072Migrate to manifest-only
0.16.02025-08-2865593Promoting release candidate 0.16.0-rc.1 to a main version.
0.16.0-rc.12025-08-2565072Migrate incremental streams
0.15.02025-08-1965085Promoting release candidate 0.15.0-rc.1 to a main version.
0.15.0-rc.12025-08-1864918Migrate nested full refresh streams
0.14.02025-08-1865066Promoting release candidate 0.14.0-rc.1 to a main version.
0.14.0-rc.12025-08-1464880Migrated all full refresh streams that have no parent streams
0.13.02025-08-1464929Promoting release candidate 0.13.0-rc.1 to a main version.
0.13.0-rc.12025-08-1164877Update CDK to v6
0.12.12025-06-1556258Update dependencies
0.12.02025-05-1349097Fix per partition states for nested streams
0.11.172025-02-2254486Update dependencies
0.11.162025-01-2252089Fix typo to fix pagination for TwilioStream class
0.11.152025-01-1851966Update dependencies
0.11.142024-12-2850803Update dependencies
0.11.132024-11-2543769Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
0.11.122024-08-0343132Update dependencies
0.11.112024-07-2742593Update dependencies
0.11.102024-07-2042177Update dependencies
0.11.92024-07-1341845Update dependencies
0.11.82024-07-1041478Update dependencies
0.11.72024-06-2640527Update dependencies
0.11.62024-06-2240030Update dependencies
0.11.52024-06-0639252[autopull] Upgrade base image to v1.2.2
0.11.42024-05-2238564Migrate authenticator to requests_native_auth package
0.11.32024-05-2038262Replace AirbyteLogger with logging.Logger
0.11.22024-04-1936666Updating to 0.80.0 CDK
0.11.12024-04-1236666Schema descriptions
0.11.02024-03-1936267Pin airbyte-cdk version to ^0
0.10.22024-02-1235153Manage dependencies with Poetry
0.10.12023-11-2132718Base image migration: remove Dockerfile and use the python-connector-base image
0.10.02023-07-2827323Add new stream Step
0.9.02023-06-2727221Add new stream UserConversations with parent Users
0.8.12023-07-1228216Add property channel_metadata to ConversationMessages schema
0.8.02023-06-1127231Add new stream VerifyServices
0.7.02023-05-0325781Add new stream Trunks
0.6.02023-05-0325783Add new stream Roles with parent Services
0.5.02023-03-2123995Add new stream Conversation Participants
0.4.02023-03-1823995Add new stream Conversation Messages
0.3.02023-03-1822874Add new stream Executions with parent Flows
0.2.02023-03-1624114Add Conversations stream
0.1.162023-02-1022825Specified date formatting in specification
0.1.152023-01-2722025Set AvailabilityStrategy for streams explicitly to None
0.1.142022-11-1619479Fix date range slicing
0.1.132022-10-2518423Implement datetime slicing for streams supporting incremental syncs
0.1.112022-09-3017478Add lookback_window parameters
0.1.102022-09-2917410Migrate to per-stream states
0.1.92022-09-2617134Add test data for Message Media and Conferences
0.1.82022-08-2916110Add state checkpoint interval
0.1.72022-08-2615972Shift start date for stream if it exceeds 400 days
0.1.62022-06-2214000Update Records stream schema and align tests with connectors' best practices
0.1.52022-06-2213896Add lookback window parameters to fetch messages with a rolling window and catch status updates
0.1.42022-04-2212157Use Retry-After header for backoff
0.1.32022-04-2012183Add new subresource on the call stream + declare a valid primary key for conference_participants stream
0.1.22021-12-239092Correct specification doc URL
0.1.12021-10-187034Update schemas and transform data types according to the API schema
0.1.02021-07-024070Native Twilio connector implemented
Was this page helpful?