Rate this page:

Segment Quickstart

Twilio Event Streams integration with Segment, Segment Sink enables you to send Twilio Events to Segment so that:

  • You can send your data to one of 400+ destinations available via Segment.
  • You can use Segment Profiles to link your Twilio data to an individual for an omni-channel view of your customer’s interactions, or use customer engagement tools, such as Engage, to deliver personalized, omnichannel experiences.

To get started,

Getting Started

  1. In the Segment app, from your workspace’s /sources page, click Add source.

  2. Choose Twilio Event Streams.

  3. Give the source a nickname. The nickname is a label used in the Segment interface. It can be whatever you like, but we recommend sticking to something that reflects the source itself, like Twilio Events for nickname and twilio_events for the schema name.

    Note: You can add multiple instances if you have multiple Twilio accounts. That’s why we allow you to customize the source’s nickname!

  4. When you click Connect, you’ll be prompted for your Twilio WriteKey. Follow the steps below to setup the Segment Sink in the Twilio Console and get a write key.

  5. You’ll be re-directed to Twilio’s app and you’ll need to authorize Segment to read from your account data. To authorize, click in the “Allow” button. Once approved, you’ll be redirected back to the set up page in the Segment app.

  6. Click on the “Finish” button and you’ll be good to go! We'll begin syncing your Twilio data into Segment momentarily, and it will be written to your warehouse at your next Warehouse run.


Create a Segment Sink Instance

Via the Console

  1. In the Twilio Console, click on Events Streams from the left-hand menu, then click Manage.
  2. On the Manage sink and subscriptions page, click Create a new Sink.
  3. Give the Sink a description.
  4. Select the Segment Sink Type.
  5. In the Segment App, you can get the write key for the Twilio Event Stream (follow the directions above to obtain a write key). Copy it into the Write Key box in the Twilio Console. Complete the setup in the Segment App.
  6. Follow directions to add a Subscription to your new Segment Sink.

Via the API

You will need to install and set up the Twilio CLI for your account to use the following command.

To create a new Segment Sink, run this command:

twilio api:events:v1:sinks:create --description <add sink description here> \
--sink-configuration '{"write_key":"${your segment write key}"}' \
--sink-type segment

If we are unable to deliver events to your Sink due to a problem with the Sink, we send errors through Twilio Debugger. After the first error about Sink failure, we will continue to notify you every 20 minutes. The notification will include the Sink ID and error details.

Subscribe to Twilio events

Now that you have a created Segment Sink, you can subscribe to one or more events. The following are the events that are available for subscription to Segment Sink. In order to prevent profile duplication within Segment, we have limited the availability of the events to the following events.

Event Type

Schema Version














You can learn more about Message Status events here.

Via the Console

  1. In the Twilio Console for Event Streams, click Create a new Subscription. A subscription is comprised of a set of pairs of Event Types and Schema versions.
  2. Select the Sink to attach the Subscription to. One Sink can have one Subscription. Give the subscription a description.
  3. Then, select the specific Twilio events and schema versions to use.
  4. Click Create Subscription.

Twilio Event Streams Subscription Config

Via the API

You can subscribe to any of these events by making an API call. This is done with the following command. The new subscription is configured to read the event-types from the --types argument — you’ll need the event type and schema version from the table above. The event-types you specify in the--types argument will be sent to the Sink specified by the --sink-sid argument. Use the Sink SID of the Sink you created above.

twilio api:events:v1:subscriptions:create --description <description> \
  --sink-sid <sink id DGxxx> \
  --types '{"type": "<event_type>","schema_version": <version>}'

For instance, to subscribe to all call summary events, you would run:

twilio api:events:v1:subscriptions:create \
  --description "Subscription on 3 call_summary events" \
  --sink-sid <sink id DGxxx> \
  --types '{"type":"","schema_version":1}' \
  --types '{"type":"","schema_version":1}' \
  --types '{"type":"","schema_version":1}'

Sample Track Event Schema

Data is sent to Segment as a JSON with the Segment Analytics format. Here’s a Message Delivered event, for example:

  "anonymousId": "13460360364754414896",
  "context": {
    "externalIds": [
        "collection": "users",
        "encoding": "none",
        "id": "+34606234664",
        "type": "phone"
    "library": {
      "name": "unknown",
      "version": "unknown"
  "event": "com.twilio.messaging.message.delivered",
  "integrations": {},
  "messageId": "EZ159d95769704d0837c04fde4fd2d32e4",
  "originalTimestamp": "2021-11-17T05:11:29.346644414-08:00",
  "properties": {
    "accountSid": "AC824d654a84f279949ca008d28875f833",
    "apiVersion": "2010-04-01",
    "eventName": "com.twilio.messaging.message.delivered",
    "from": "+18126097345",
    "messageSid": "SMbfcfc5f402de469aa18941e3e11c59ae",
    "messageStatus": "DELIVERED",
    "messagingServiceSid": "MGcf4248034753df3eac81423fd08fa0cd",
    "timestamp": "2021-11-17T13:11:28.963Z",
    "to": "+ 18126097345"
  "receivedAt": "2021-11-17T13:11:29.378Z",
  "timestamp": "2021-11-17T13:11:29.346Z",
  "type": "track"

The properties field should meet its schema, which is the Messaging.MessageStatus schema in this case.

End to End Test

  1. Complete the steps to create the Twilio Event Source (in Segment app) and create the Segment Sink and Subscription (in Twilio App).
  2. Go to Segment console, connect the Event Stream to a destination of your choice
  3. From your Twilio product, send a sample event included in the Subscription. Hint: An easy way to do this is to send a test Message.
  4. In the Segment app, go to Connections, and select the Twilio Event Streams Source. View event schema, debugger (pretty view) to see the event sent and successfully routed to your Destination.

Optional: For Personas + Twilio Messaging customers only

  1. In the Segment app, ensure your source with the Twilio Event Stream is connected to your Personas workspace (directions).
  2. Go to Personas Settings -> Identity Resolution, ensure you have customer identifiers setup for each messaging type you send through Twilio Messaging (phone, whatsapp, etc).
  3. Go to the Messaging product in the Twilio console. Send a test message from a previous identified customer.
  4. Check Personas Explorer to check events are associated to correct customers. View event schema (pretty view).
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Loading Code Sample...

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!