Sync Inc

Twilio Reference

Twilio API key

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

Twilio database schema

Your Sync Inc 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 Sync Inc, 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

Sync Inc 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, Sync Inc workers poll each of the five resource endpoints at an average rate of once per second per resource. This polling process ensures that Sync Inc ingests any creates or updates from Twilio in just a couple seconds.


Your Sync Inc database is read-only.

We advocate for a one-way data flow: read from your Sync Inc database, write to Twilio's API. Any changes will flow down to your Sync Inc 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 Sync Inc console. Wait endpoints take this form:

Where `kind` is the platform, like `stripe` or `twilio`. `id` is the Sync Inc 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 Sync Inc database

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

> 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 Sync Inc 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 Sync Inc application database is only accessible through a bastion host.
  • We only access customer databases by request or to diagnose a sync issue.
  • Sync Inc workers first backfill your database with all your Twilio data. Then, after the backfill, Sync Inc workers poll Twilio's events endpoint every second to keep your data in-sync.
  • Data flows directly from Twilio, through Sync Inc 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, Sync Inc provisions a private database and a database user for you on a shared RDS instance. While Sync Inc shared instances are secure, we can also sync to a database you own for greater peace of mind.

Was this helpful?