Segment destination
Beta
Data Destinations is currently available as a Private Beta product and the information contained in this document is subject to change. Data Destinations is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI. To learn more, see Private beta legal information.
Twilio Segment lets you collect, unify, and route customer data to hundreds of downstream tools. Send your events to a Segment source to fold them into your existing customer data pipeline.
- Category: CDP
- Release status: Beta
- Authentication: API key
- Regional availability: US1, IE1
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
The Segment Track API requires a resolvable identifier (either a userId or anonymousId) on every event. Twilio silently suppresses events without a supported identifier instead of delivering them. For more information, see Common errors.
You can send the following event types to Segment:
- Messaging: inbound message received, message queued, message sent, message delivered, message failed, message undelivered, message read
- Voice: call answered, call initiated, call ringing, call completed, call redirected, call requested, call transferred, dial finished, enqueue finished, gather finished, record finished, media fetched
- Voice Insights: call summary complete
No other event types are currently eligible for this destination.
In the IE1 region, only Voice Insights events are eligible for delivery at this time.
Before you set up a Segment destination, make sure you have:
- A Segment account with a source configured to receive HTTP Tracking API events.
- Your Segment source's Write Key, found in the source's settings.
Info
See Set up a destination for the full UI and Destinations API setup flow common to every destination type.
To create a Segment destination in the Twilio Console:
- From your Segment account, gather the settings listed in Destination settings.
- In the Twilio Console, go to Data > Data Destinations > Destinations > Add destination subscription.
- Complete the Add destination subscription wizard.
To create a Segment destination through the Destinations API, send a POST request to the Destinations endpoint and set destinationType to segment. For authentication and the other request body fields, see Create a destination.
POST "https://destinations.twilio.com/v1/ControlPlane/Destinations"
Set the config object in the request body as follows:
| Name | Type | Description |
|---|---|---|
credentials.credentialType (Required) | string | Set to API_KEY. |
credentials.writeKey (Required) | string | Your Segment source write key. |
region | enum<string> | Your Segment region. The default is US. Valid values: US, EU. |
The following example shows a request body. Replace the uppercase placeholder values with your own.
1{2"destinationType": "segment",3"name": "My Segment destination",4"config": {5"credentials": {6"credentialType": "API_KEY",7"writeKey": "WRITE_KEY"8}9}10}
Use segment as the destinationType.
| Field | Description | Required | Default or choices |
|---|---|---|---|
| Write Key | Segment source write key, sent as the HTTP Basic Auth username. Marked as sensitive: entered once and stored encrypted. | Yes | None |
| Region | Segment region determining the API endpoint. | No | Default: US. Choices: US, EU |
Twilio authenticates to Segment by using HTTP Basic Auth, with your Write Key as the username and an empty password. This credential is stored encrypted and never appears in event payloads.
| Field | Segment field |
|---|---|
| Event friendly name | Event name |
| Event time | Timestamp |
| Event ID | Message ID (deduplication) |
| Event payload | Properties |
| Resolved user/anonymous identity | userId / anonymousId |
| External IDs | context.externalIds |
When you save a Segment destination, Twilio validates your Write Key against Segment before marking the destination active. If validation fails, check that:
- Your Write Key is correct and belongs to an active Segment source.
- The Region you selected in the Console matches where your Segment source is actually hosted.
To trigger a test event, open the Console and go to the Trigger Test Event utility.
A corresponding Track call appears in your Segment source's debugger within a few seconds.
| Cause | What you'll see | Fix |
|---|---|---|
| Invalid or revoked Write Key | Validation fails with an auth error | Re-check the write key in Segment and update the destination |
| Wrong Region selected in the Console | Validation fails even with a correct write key | Confirm your source's region in Segment and update the Region setting |
| Event missing both user and anonymous identity | Twilio silently suppresses the event. No error appears in the Debugger, and the event doesn't arrive in Segment | Ensure the subscribed event type carries a resolvable user identifier |
| Segment unreachable or timing out | Delivery errors reported in the Debugger | Check the Segment status page and retry |
If Twilio can't deliver events to your destination, Twilio sends an error notification to the Debugger (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.