Kinesis quickstart

Before continuing with this quickstart, perform the following tasks.

• Install the AWS CLI.
• Configure valid AWS credentials.
• Set the value of the environment variable AWS_DEFAULT_REGION to your desired region if needed.
• Install and configure the Twilio CLI for your account.
• Download the Twilio Kinesis script.
• Install jq.

The Twilio Kinesis script configures the policies and roles needed to allow Twilio to write to your stream. Run the script and pass the stream name and shard count as arguments.

1. Copy the script and save it to a file named create_kinesis_stream.sh.

2. Make this script executable.

   Copy code block

   chmod 755 create_kinesis_stream.sh

3. Run the script.

   • Use the name twilio-events for the Kinesis stream. If you use any other name, change the permission instructions to use your custom name.
   • Set the number of shards to 1. This makes initial validation easier. You can modify it after the Sink has been set up.

   Example of creating a Kinesis stream with shards set to 1

   Copy code block

   ./create_kinesis_stream.sh twilio-events 1 | jq . > twilio-sink.json

To create the Kinesis stream with the specific shard count, the script uses the AWS CLI. It returns a JSON payload with the details you need to create a Sink. In the previous example, the script writes the received data to a file named twilio-sink.json.

To update the shard count of the Kinesis stream after it has been validated, run the following script:

To create a Kinesis Sink, run this command:

To test your sink, send a test message to your Kinesis.

1. Run the following Twilio CLI command:

   Copy code block

   twilio api:events:v1:sinks:test:create --sid ${SID}

2. Download the test message script as cat_kinesis.sh.

3. Make the script executable.

   Copy code block

   chmod 755 cat_kinesis.sh

4. Run the script on your Kinesis stream.

   Copy code block

   ./cat_kinesis.sh twilio-events

   The script outputs a test event:

   Copy code block

   1
   {
   2
     "specversion": "1.0",
   3
     "type": "com.twilio.eventstreams.test-event",
   4
     "source": "Sink",
   5
     "id": "AC1234567890123456789012",
   6
     "dataschema": "https://events-schemas.twilio.com/EventStreams.TestSink/1.json",
   7
     "datacontenttype": "application/json",
   8
     "time": "2020-08-18T21:10:02.113Z",
   9
     "data": "{\"test_id\":\"95001c1e-5b8e-45f5-830d-f9cbf1d16420\"}"
   10
   }

If Twilio can't deliver events to your Sink due to a problem with the Sink, errors display in the Twilio Debugger. After the first error about Sink failure, notifications continue in Debugger every 20 minutes. The notification includes the Sink ID and details about the error.

With your Sink tested, you can subscribe to one or more events. The following table lists some of the available events. To review other event types, see the Event Types heading in the side table of contents.

To subscribe to any of these events, make an API call as shown in the following example. The new subscription reads the event-types from the --types argument. Use the event type and schema version from the previous table. The event-types you specify in the --types argument are sent to the Sink specified given in the --sink-sid argument. Use the SID of the Sink you created.

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

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

You can tail the events coming out of Kinesis with the cat_kinesis.sh script.

./cat_kinesis.sh twilio-events

The script iterates over the specified shards in a stream and requests records from them. All data in the stream has been Base64 encoded. The script decodes it and uses jq so humans can read the output.

Twilio sends the data to Kinesis in the CloudEvents format. The SDK encodes into and decodes from Base64 to Kinesis. Depending on how you read the data from Kinesis, you might have to decode the data from Base64.

1
{
2
"specversion": "1.0",
3
"type": "com.twilio.voice.insights.call-summary.predicted-complete",
4
"source": "/v1/Voice/CA00000000000000000000000000000000/Summary",
5
"id": "EZ00000000000000000000000000000000",
6
"dataschema": "https://events-schemas.twilio.com/VoiceInsights.CallSummary/1",
7
"datacontenttype": "application/json",
8
"time": "2020-07-23T22:56:33.000Z",
9
"data": "{\"call_sid\":\"CA00000000000000000000000000000000\",\"account_sid\":\"AC00000000000000000000000000000000\",\"parent_call_sid\":\"\",\"parent_account_sid\":\"\",\"start_time\":\"2020-07-23T22:56:28Z\",\"end_time\":\"2020-07-23T22:56:33Z\",\"duration\":0,\"connect_duration\":0,\"call_type\":\"client\",\"call_state\":\"canceled\",\"from\":{\"caller\":\"+55555555\",\"callee\":\"\",\"carrier\":\"MEGA:CORP\",\"connection\":\"landline\",\"number_prefix\":\"5555\",\"location\":{\"lat\":0.0,\"lon\":-0.0},\"city\":\"\",\"country_code\":\"US\",\"country_subdivision\":\"\",\"ip_address\":\"\",\"sdk\":null},\"to\":{\"caller\":\"\",\"callee\":\"client:SOMECLIENT\",\"carrier\":\"\",\"connection\":\"twilio_sdk\",\"number_prefix\":\"\",\"location\":null,\"city\":\"\",\"country_code\":\"\",\"country_subdivision\":\"\",\"ip_address\":\"\",\"sdk\":null},\"processing_state\":\"partial\",\"processing_version\":1,\"sip_edge\":null,\"carrier_edge\":null,\"sdk_edge\":null,\"client_edge\":null,\"tags\":[],\"attributes\":null,\"properties\":{\"q850_cause\":0,\"last_sip_response_num\":0,\"pdd_ms\":0,\"route_id\":\"\",\"media_region\":\"unknown_realm\",\"signaling_region\":\"unknown_realm\",\"twilio_media_ip\":\"\",\"twilio_signaling_ip\":\"\",\"external_media_ip\":\"\",\"external_signaling_ip\":\"\",\"sip_call_id\":\"\",\"user_agent\":\"\",\"selected_region\":\"unknown_realm\",\"region\":\"unknown_realm\",\"trunk_sid\":\"\",\"disconnected_by\":\"unknown_disconnected_by\",\"direction\":\"outbound_api\",\"settings\":null}}"
10
}

The data field should follow the Voice Insights Call Summary schema.