Amazon Kinesis 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.
Amazon Kinesis is a fully managed, real-time data streaming service that lets you ingest and process large streams of records for analytics and downstream processing.
- Category: Raw data
- Release status: Beta
- Authentication: AWS IAM role
- Regional availability: US1, IE1
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
In the US1 region, you can send all event types to Amazon Kinesis. See Event types for the full list.
In the IE1 region, only Voice Insights events are eligible for delivery.
Before you set up an Amazon Kinesis destination, make sure you have:
- An Amazon Web Services (AWS) account with:
- An existing Kinesis data stream. Twilio doesn't create the stream for you.
- An identity and access management (IAM) role in your AWS account that Twilio can assume to write to the stream. This role must have a trust policy whose Principal is the intermediary role that Twilio assumes (
arn:aws:iam::177261743968:role/egress-domain-prod-isolated). - An External ID (2-1224 characters) that you choose and add to that role's trust policy
sts:ExternalIdcondition, for cross-account security.
- The following AWS account information to create your Kinesis
destination:
- The Amazon Resource Name (ARN) of your IAM role.
- The Stream ARN of your Kinesis data stream.
- The External ID you added to your IAM role's trust policy.
Info
See Set up a destination for the full UI and Destinations API setup flow common to every destination type.
To create a Kinesis destination in the Twilio Console:
- From your AWS 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 Amazon Kinesis destination through the Destinations API, send a POST request to the Destinations endpoint and set destinationType to amazon-kinesis. 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 |
|---|---|---|
arn (Required) | string | The full ARN of the Amazon Kinesis Data Stream to deliver events to. |
credentials.credentialType (Required) | string | Set to AWS_IAM. |
credentials.externalId (Required) | string | The external ID in your IAM role's trust policy. |
credentials.roleArn (Required) | string | The ARN of the IAM role Twilio assumes in your AWS account. |
The following example shows a request body. Replace the uppercase placeholder values with your own.
1{2"destinationType": "amazon-kinesis",3"name": "My Amazon Kinesis destination",4"config": {5"arn": "STREAM_ARN",6"credentials": {7"credentialType": "AWS_IAM",8"externalId": "EXTERNAL_ID",9"roleArn": "IAM_ROLE_ARN"10}11}12}
Use amazon-kinesis as the destinationType.
| Field | Description | Required | Default |
|---|---|---|---|
| Stream ARN | The full ARN of the Amazon Kinesis Data Stream to deliver events to. | Yes | None |
| IAM Role ARN | The ARN of the IAM role Twilio assumes in your AWS account to write to the stream. | Yes | None |
| External ID | External ID that must match the sts:ExternalId condition in your IAM role's trust policy. 2-1224 characters. | Yes | None |
Twilio authenticates to Kinesis by using AWS IAM role assumption rather than static credentials. You must set your role's trust policy Principal to the intermediary role Twilio assumes, not the Twilio AWS account.
Twilio assumes your IAM Role ARN in two steps. First, Twilio assumes an intermediary AWS role (arn:aws:iam::177261743968:role/egress-domain-prod-isolated).
Then that role assumes your IAM Role ARN and passes your External ID as the sts:ExternalId condition to obtain short-lived, rotated credentials scoped to your stream. Twilio doesn't store long-lived API keys.
| Field | Kinesis field |
|---|---|
| Event source | Partition Key |
| Full event envelope | Record data |
When you save an Amazon Kinesis destination, Twilio validates the connection by assuming your IAM role and confirming it can read your stream's shard information. If validation fails, check that:
- The IAM Role ARN is correct and its trust policy allows the intermediary role (
arn:aws:iam::177261743968:role/egress-domain-prod-isolated), with ansts:ExternalIdcondition matching your External ID, to assume it. - The role has permission to access the stream.
- The Stream ARN is correct and the stream exists in the expected region.
To trigger a test event, open the Console and go to the Trigger Test Event utility.
A corresponding record appears in your Kinesis stream shortly after.
| Cause | What you'll see | Fix |
|---|---|---|
| Role assumption denied or missing stream permissions | Validation fails with an auth error | Check the role's trust policy. Principal must be the intermediary role (arn:aws:iam::177261743968:role/egress-domain-prod-isolated), not just the Twilio AWS account, including the sts:ExternalId condition, and the role's stream permissions |
| Stream not found | Validation fails with a configuration error | Confirm the Stream ARN and that the stream exists in that region |
| Other AWS-side error | Validation fails with a resource error | Check the stream's status in the AWS Console and retry |
If Twilio can't deliver events to your stream, 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.