This guide walks you through setting up the Modulate integration with Amazon Connect for real-time audio monitoring and toxicity detection.

Technical Overview

This integration allows you to stream calls from Amazon Connect call centers to Modulate for AI analysis in realtime. The method for doing that is as follows:

  1. The Amazon Connect call center streams calls to Amazon Kinesis Video Streams - this is managed by Amazon and is largely plug-and-play
  2. When a new call is started, the /kvs endpoint should be called. This can be done from a lambda block in a contact flow.
  3. Upon receiving an API call, this service will begin grabbing audio from the KVS stream corresponding to the new call. To do this, Modulate will need access to the relevant KVS streams via AWS cross account access.
  4. Audio from the call will appear in the Modulate web console
  5. When the KVS stream ends, Modulate will automatically stop recording. This will happen automatically when the call disconnects, or you can trigger it manually with a contact flow block to stop streaming to KVS.

Prerequisites

Setup Process

Step 1: Create Customer Role with KVS Access

First, you’ll need to create an IAM role in your AWS account that grants access to your Connect KVS streams. This role will be assumed by a role in Modulate’s AWS account to access your streams.

1.1 Create the IAM Role

Create a new IAM role in your AWS account. For now, you can use a placeholder trust policy - you’ll update this later with the intermediate role ARN provided by Modulate:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/placeholder"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

You’ll replace this placeholder ARN in Step 3 after receiving the intermediate role ARN from Modulate.

1.2 Attach KVS Permissions

Attach a permissions policy to grant access to your Connect KVS streams:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesisvideo:GetDataEndpoint",
        "kinesisvideo:GetMedia",
        "kinesisvideo:GetMediaForFragmentList",
        "kinesisvideo:ListFragments",
        "kinesisvideo:DescribeStream"
      ],
      "Resource": "arn:aws:kinesisvideo:*:*:stream/your-connect-instance-*"
    }
  ]
}

Adjust the resource ARN pattern to match your Connect instance naming convention.

1.3 Note Your Role ARN

Save the ARN of the role you created (e.g., arn:aws:iam::YOUR-ACCOUNT:role/ModulateKVSAccess) - you’ll need to provide this to Modulate in the next step.

Step 2: Contact Modulate for Integration Setup

Reach out to your Modulate representative to initiate the integration process. You’ll need to provide:

Step 3: Update Customer Role Trust Policy

After Modulate creates the intermediate role, they will provide you with the corresponding role ARN (e.g., arn:aws:iam::123456789012:role/prod-kvs-adapter-yourclient).

Update the trust policy of your customer role (created in Step 1) to trust this intermediate role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/prod-kvs-adapter-yourclient"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Replace the ARN with the intermediate role ARN provided by Modulate.

Step 4: Test the Integration

Before setting up production triggers, test the integration with a demo call:

  1. Make a test call through your Amazon Connect instance
  2. Note the KVS stream name (typically: your-connect-instance-contact-{CONTACT-ID})
  3. Test the API endpoint using the provided credentials. This can be done in a number of ways, but one easy way to test the API is to use the Swagger UI provided on the API docs page.

Example test request:

curl -G "https://prod-aws-connect.modulate.ai/kvs" \
  --data-urlencode "streamName=your-connect-instance-contact-12345678-1234-1234-1234-123456789012" \
  --data-urlencode "callerName=test-caller" \
  --data-urlencode "agentName=test-agent" \
  --data-urlencode "callName=test-call" \
  --data-urlencode "roleArn=arn:aws:iam::YOUR-ACCOUNT:role/ModulateKVSAccess" \
  -H "X-Account-ID: 12345678-1234-1234-1234-123456789012" \
  -H "X-API-Key: 87654321-4321-4321-4321-210987654321"

A successful response indicates the role assumption and KVS access are working correctly.

Step 5: Create Lambda Integration Function

Next, you will want to call this API when a new call comes in. The easiest way to do that is to create an AWS Lambda function which Amazon Connect can call as part of a contact flow.

5.1 Create the Lambda Function

  1. Create a new Lambda function in your AWS account
  2. Use Python 3.9+ runtime
  3. Download our Connect Lambda example and deploy it to your Lambda function. You can also create the lambda from scratch if you prefer.

5.2 Configure Lambda Function

Update the configuration variables in the Lambda function:

# Update these with your values
TOXMOD_API_URL = "https://prod-aws-connect.modulate.ai"
TOXMOD_ACCOUNT_ID = "12345678-1234-1234-1234-123456789012"
TOXMOD_API_KEY = "87654321-4321-4321-4321-210987654321"
KVS_ROLE_ARN = "arn:aws:iam::YOUR-ACCOUNT:role/ModulateKVSAccess"
CONNECT_INSTANCE_PREFIX = "your-connect-instance-name"

5.3 Set Lambda Permissions

Ensure your Lambda execution role has:

Step 6: Configure Amazon Connect Contact Flow

Add the Lambda function to your Amazon Connect contact flow:

  1. Open your contact flow in the Amazon Connect console
  2. Add an “Invoke AWS Lambda function” block
  3. Select your Modulate integration Lambda function
  4. Place the block early in your flow (typically right after call routing)

Step 7: Test End-to-End Integration

  1. Make a test call through your Amazon Connect instance
  2. Verify the Lambda function is triggered
  3. Check CloudWatch logs for successful API calls
  4. Confirm that audio is displayed on the “Recent Incidents” page of the Modulate web console. Make sure that debug mode is enabled, and the filters are set up to show content of all scores, not just high-scoring clips.