Twilio Reference

Twilio API key

To sync your Twilio data to your Sequin database, you'll provide Sequin with a Twilio API key, which you can generate here.

Twilio database schema

Your Sequin database will contain Twilio data for the following entities:

  • Call
  • Message
  • Recording
  • Conference
  • Transcription

More about each below:

Call (`call`)

A Call is a voice call and represents calls with a `direction` of either `inbound` or `outbound`.

Call data expires after 1 year

Note that we are only able to backfill Call data for the past 12 months. So, if today is September 15th 2021, we can backfill calls all the way back to September 1st 2020. But calls on August 31st 2020 and earlier will be missing.

We can backfill Recordings indefinitely. Because a Recording references a Call (see below), we'll create a "deleted row" for each Call older than one year. In Sequin, deleted rows contain the `id` of the entity, the `deleted` field set to `true`, and `null` for all other columns.

Message (`message`)

A Message is an SMS message and represents messages with a `direction` of either `inbound` or `outbound`.

Recording (`recording`)

A Recording is a recording of a phone call, stored as an audio file. The URL for the audio file is stored in the column `mp3_url` and `wav_url`, for MP3 files and WAV files, respectively. (More about these encodings in Twilio's docs.)

Note that Twilio's URLs for Recordings are not protected by an API key by default. Per their docs:

Because the URLs that host individual recordings are useful for many external applications, they are public and do not require HTTP Basic Auth to access. This allows you to embed the recording URL in a web application without revealing your Twilio API credentials.

Twilio's recording URLs are quite long and difficult to guess, so the contents of the recordings should be reasonably private unless you distribute the URL. For added security, you can enforce HTTP basic auth to access media using your AccountSid and Authentication token via the voice settings page in the console.

Primary references

  • `call_id`: The Call to which the Recording corresponds. Note that if the Recording is more than a year old, the Call it references may be a "deleted row" (see above).

Conference (`conference`)

A Conference is a multi-party voice call.

Transcription (`transcription`)

A Transcription represents the transcribed text and metadata from a transcribed Recording of a voice Call. You can find the transcription inside `transcription_text`.

The syncing process

Sequin workers first backfill your database with all your Twilio data by paginating through all Twilio API endpoints. (Note that the backfill process for the Call resource is limited.)

Then, after the backfill, Sequin workers poll each of the five resource endpoints at an average rate of once per second per resource. This polling process ensures that Sequin ingests any creates or updates from Twilio in just a couple seconds.


Your Sequin database is read-only.

We advocate for a one-way data flow: read from your Sequin database, write to Twilio's API. Any changes will flow down to your Sequin database for you to read again.

Sometimes, you want to make sure that changes that you just wrote have been synced to your database. We call this scenario a read-after-write.

To do so, you can call our wait endpoint. To find the URL for your sync's wait endpoint, just click "Connect" in the Sequin console. Wait endpoints take this form:

Where `kind` is the platform, like `stripe` or `twilio`. `id` is the Sequin ID of your sync.

A wait endpoint only returns after we've confirmed your database is up-to-date. So, you can weave it into your workflow like this:

  1. Make a write request directly to the API
  2. Call your sync's wait endpoint
  3. When #2 completes, read from your Sequin database

Here's an example curl request to a wait endpoint on Sequin:

> curl
< { "ok": true }

Note: The wait endpoint is in alpha and experimental. We may add additional properties to the response in the near future.


Your Sequin database will contain all your Twilio data - which includes PII and sensitive information. We take the security of that data seriously.

Please read about our full security practices. Here is a short synopsis of how we keep your Twilio data secure:

  • You supply us with an API key which is encrypted at rest. The Sequin application database is only accessible through a bastion host.
  • We only access customer databases by request or to diagnose a sync issue.
  • Sequin workers first backfill your database with all your Twilio data. Then, after the backfill, Sequin workers poll Twilio's events endpoint every second to keep your data in-sync.
  • Data flows directly from Twilio, through Sequin workers, to your database. We don't cache or store Twilio data anywhere else.
  • We use Sentry and Datadog for error monitoring. Sometimes errors Datadog catches will contain API response data. But these are minimized and our logs in Datadog have a shelf-life of 30 days.
  • By default, Sequin provisions a private database and a database user for you on a shared RDS instance. While Sequin shared instances are secure, we can also sync to a database you own for greater peace of mind.

Was this helpful?