Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Segment Quickstart


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

To get started,


Getting Started

getting-started page anchor
  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.
Sources_Twilio_Event_Streams_Segment.

Create a Segment Sink Instance

create-a-segment-sink-instance page anchor

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

via-the-api page anchor
(warning)

Warning

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:


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

(information)

Info

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

subscribe-to-twilio-events page anchor

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 TypeSchema Version
com.twilio.messaging.message.queued4
com.twilio.messaging.message.sent4
com.twilio.messaging.message.delivered4
com.twilio.messaging.message.failed4
com.twilio.messaging.message.undelivered4
com.twilio.messaging.message.read4
com.twilio.messaging.inbound-message.received.4

You can learn more about Message Status events here.

  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.

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.


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

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


_10
twilio api:events:v1:subscriptions:create \
_10
--description "Subscription on 3 call_summary events" \
_10
--sink-sid <sink id DGxxx> \
_10
--types '{"type":"com.twilio.voice.insights.call-summary.partial","schema_version":1}' \
_10
--types '{"type":"com.twilio.voice.insights.call-summary.predicted-complete","schema_version":1}' \
_10
--types '{"type":"com.twilio.voice.insights.call-summary.complete","schema_version":1}'


Sample Track Event Schema

sample-track-event-schema page anchor

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


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

The properties field should meet its schema, which is the Messaging.MessageStatus schema(link takes you to an external page) in this case.


  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(link takes you to an external page) ).
  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: