Segment Quickstart

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.

Expand image

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.

To create a new Segment Sink, run this command:

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

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.

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.

Expand image

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.

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

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

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

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

1
{
2
  "anonymousId": "13460360364754414896",
3
  "context": {
4
    "externalIds": [
5
      {
6
        "collection": "users",
7
        "encoding": "none",
8
        "id": "+34606234664",
9
        "type": "phone"
10
      }
11
    ],
12
    "library": {
13
      "name": "unknown",
14
      "version": "unknown"
15
    }
16
  },
17
  "event": "com.twilio.messaging.message.delivered",
18
  "integrations": {},
19
  "messageId": "EZ159d95769704d0837c04fde4fd2d32e4",
20
  "originalTimestamp": "2021-11-17T05:11:29.346644414-08:00",
21
  "properties": {
22
    "accountSid": "AC824d654a84f279949ca008d28875f833",
23
    "apiVersion": "2010-04-01",
24
    "eventName": "com.twilio.messaging.message.delivered",
25
    "from": "+18126097345",
26
    "messageSid": "SMbfcfc5f402de469aa18941e3e11c59ae",
27
    "messageStatus": "DELIVERED",
28
    "messagingServiceSid": "MGcf4248034753df3eac81423fd08fa0cd",
29
    "timestamp": "2021-11-17T13:11:28.963Z",
30
    "to": "+ 18126097345"
31
  },
32
  "receivedAt": "2021-11-17T13:11:29.378Z",
33
  "timestamp": "2021-11-17T13:11:29.346Z",
34
  "type": "track"
35
}

The properties field should meet its schema, which is the Messaging.MessageStatus schema 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: one 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).