Amplitude 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.
Amplitude is a digital analytics platform that lets you turn Twilio events into user-level product and behavioral analytics, such as funnels, retention, segmentation, and cohorts.
- Category: Analytics
- Release status: Beta
- Authentication: API key
- Regional availability: US1
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
Identifier-restricted eligibility: Twilio can only send events that contain an end user identifier (such as a phone number or user ID) to Amplitude, because Amplitude requires every event to identify a user or device.
Twilio can send the following event types to Amplitude:
- 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
All other event types aren't eligible for this destination. See Event types for the full list of available event types.
Before you set up an Amplitude destination, make sure you have:
- An Amplitude account with a project to send events to.
- Your Amplitude project's API Key, found in your Amplitude project settings.
- Your Amplitude project's Secret Key, found alongside the API Key in your Amplitude project settings. Generating it requires a Manager or Admin role on the project.
Info
See Set up a destination for the full UI and Destinations API setup flow common to every destination type.
To create an Amplitude destination in the Twilio Console:
- From your Amplitude 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 an Amplitude destination through the Destinations API, send a POST request to the Destinations endpoint and set destinationType to amplitude. 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.apiKey (Required) | string | Your Amplitude project API key. |
credentials.secretKey (Required) | string | Your Amplitude project secret key. Twilio uses it to verify your credentials when you save the destination and never uses it to deliver events. |
region | enum<string> | Your Amplitude data residency 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": "amplitude",3"name": "My Amplitude destination",4"config": {5"credentials": {6"credentialType": "API_KEY",7"apiKey": "API_KEY",8"secretKey": "SECRET_KEY"9}10}11}
Use amplitude as the destinationType.
| Field | Description | Required | Default or choices |
|---|---|---|---|
| API Key | Your Amplitude project API Key. Sent with every event you send to Amplitude. Sensitive: stored encrypted. | Yes | None |
| Secret Key | Your Amplitude project Secret Key. Used only to verify your credentials when you save the destination. Never used to send events. Sensitive: stored encrypted. | Yes | None |
| Region | Your Amplitude project's data residency. | No | US (default), EU |
Twilio authenticates to Amplitude by using your API Key, sent as a field on every event delivered to Amplitude. Your Secret Key is used only for the one-time validation check when you save the destination.
| Field | Amplitude field |
|---|---|
| Event type | Event Type |
| Event time | Time |
| End-user identifier (for example, phone number) | User ID |
| Event payload | Event Properties |
| CloudEvent ID | Insert ID (used for delivery deduplication) |
Amplitude limits event property values to 1024 characters. Twilio omits any value over that limit rather than truncating it.
When you save an Amplitude destination, Twilio validates your API Key and Secret Key against Amplitude before marking the destination active. If validation fails, check that:
- Your API Key and Secret Key are both correct and belong to the same Amplitude project.
- Neither key has been revoked or rotated in Amplitude since you last saved the destination.
Twilio doesn't currently offer a way to manually trigger a test event for this destination from either the Console or the CLI. To confirm delivery is working, wait for a real event of a subscribed type to fire.
| Cause | What you'll see | Fix |
|---|---|---|
| Invalid or revoked API Key / Secret Key | Validation fails with an auth error | Re-check both keys in Amplitude and update the destination |
| Event missing an end user identifier | Event is not delivered to Amplitude | See Eligible events. Twilio can send only events that carry an identifier |
| Request rejected as malformed, blocked, or oversized (Amplitude returns 400, 403, or 413) | Delivery errors reported in the Debugger; retrying or rotating credentials does not resolve it | A 403 typically means the Amplitude abuse-protection layer blocked the request. This is not an auth failure, so rotating your API/Secret Key won't help. Check your event payload shape and size instead |
| Amplitude unreachable or rate-limiting requests (429/5xx) | Delivery errors reported in the Debugger | Automatically retried; sustained errors may indicate you've exceeded your Amplitude plan's throughput |
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.