Prerequisites
Before beginning, ensure you have:
An active Amazon Web Services (AWS) account with administrator access
An existing Amazon Connect instance
Reality Defender's AWS account ID (provided by Reality Defender)
Reality Defender credentials for accessing RealCall API and webhooks
Familiarity with the AWS Management Console
Step 1: Enable Live Media Streaming in Amazon Connect
This step configures Amazon Connect to stream live call audio to Kinesis Video Streams (KVS), which Reality Defender will consume for analysis.
Log in to the AWS Management Console.
Navigate to Amazon Connect and select your instance.
Copy and record the instance ARN (Amazon Resource Names), as it will be needed in Step 5.
In the left-hand menu, click Data storage.
Under Live media streaming, click Edit and then Enable live media streaming.
Enter a Prefix for the KVS that will store the media (e.g.,
realcall-connect-realitydefender-contact-).
Note: The prefix you select must match the KVS name that will be used for streaming media.Set your preferred Data retention period to control how long streams are retained.
Save your changes.
If the KVS doesn’t exist yet, follow the steps below to create it:
Navigate to Kinesis Video Streams.
In the left-hand menu, click Video Streams.
Click Create Video Stream.
Enter a Prefix for the KVS that will store the media (e.g., realcall-connect-realitydefender-contact-).
Note: This value must match the one set in the Live media streaming section of the Amazon Connect configuration.Click Create Video Stream.
Copy and record the Video Stream ARN, it will be needed in Step 5.
Step 2: Configure the Amazon Connect Contact Flow
This step sets up a contact flow that initiates media streaming and captures the metadata Reality Defender needs to locate and process each call's audio stream.
Log in to your Amazon Connect instance via the AWS Management Console.
In the left-hand menu, navigate to Routing > Flows.
Select an existing contact flow or click Create flow.
In the flow designer, drag and drop a Start media streaming block to the point in the flow where you want streaming to Reality Defender and the analysis to start.
Immediately after, add a Set contact attributes block.
In the Set contact attributes block, configure the following dynamic attributes:
Media Stream attributes:
Namespace | Key |
Media streams | Customer audio start fragment number |
Media streams | Customer audio stream ARN |
Media streams | Customer audio start timestamp |
System attributes:
Namespace | Key |
System | Customer address or number |
Continue building out the remainder of the flow with any transfer or routing logic required for your business needs.
Save and publish the flow.
Basic flow example:
Example flow with an IVR leg:
Step 3: Create an Amazon SQS Queue
Reality Defender uses an SQS queue to receive notifications about new and updated calls from Amazon Connect. This step creates that queue.
In the AWS Management Console, navigate to Amazon Simple Queue Service (SQS).
Click Create queue.
Configure the queue:
Name: Enter a name for the queue (e.g.,
connect).Type: Select Standard for high throughput, or FIFO if strict message ordering is required.
Optionally, configure additional attributes such as Message Retention Period, Visibility Timeout, Delivery Delay, or Access Policies.
Click Create queue.
Keep note of the queue's ARN — it will be needed in Steps 4 and 5.
Step 4: Configure Amazon EventBridge to Route Connect Events to SQS
This step creates an EventBridge rule that listens for specific Amazon Connect call events and forwards them to the SQS queue created in Step 3.
In the AWS Management Console, navigate to Amazon EventBridge.
Click Rules, and then Create rule.
Provide a Name (e.g.,
ConnectCallNotifications) and, optionally, a description.Under Event bus, keep the selection set to Default.
For Event pattern, select Custom pattern (JSON editor).
Click Edit pattern and paste the following:
{
"source":["aws.connect"],
"detail-type":["Amazon Connect Contact Event"],
"detail":{
"eventType":["INITIATED", "CONTACT_DATA_UPDATED"]
"channel": ["VOICE"]
}
}Under Select Targets, click AWS Service.
Set Target to SQS Queue and select the queue created in Step 3.
If prompted, allow EventBridge to create or assign a role with permission to write to the SQS queue.
Review the configuration and click Create.
Step 5: Configure IAM Permissions for Reality Defender
This step grants Reality Defender the minimum necessary permissions to access KVS, consume messages from SQS, and retrieve contact attributes from Amazon Connect.
Required Permissions by Service
Kinesis Video Streams
KVS permissions allow Reality Defender to access and manage audio streams captured during calls in Amazon Connect. Because all streams share a similar naming pattern, a catch-all prefix is used to scope access appropriately.
Permission | Purpose |
| Access stream metadata and state |
| Get the endpoint for a specified stream for either reading or writing. |
| Retrieve audio stream data for analysis |
| Identify active streams |
Resource specification: Stream-specific permissions are scoped to streams matching the prefix set in Step 1. kinesisvideo:ListStreams is scoped separately to "Resource": "*" in the IAM policy because it is a list operation. Example ARN: arn:aws:kinesisvideo:*:*:stream/realcall-connect-realitydefender-contact-*.
Amazon SQS
SQS permissions allow Reality Defender to consume and manage messages from the queue created in Step 3. These messages notify Reality Defender of new incoming calls or updates to a call's state.
Permission | Purpose |
| Manage message visibility for delayed processing |
| Remove processed messages from the queue |
| Consume call notifications from the queue |
| Send messages to the queue |
Resource specification: Permissions are restricted to the specific SQS queue created for this integration. Example ARN: arn:aws:sqs:<region>:<account-id>:connect.
Amazon Connect
The GetContactAttributes API allows Reality Defender to retrieve metadata about each call — such as the stream ARN, fragment number, and timestamps — which are required to locate and process the correct audio stream.
Permission | Purpose |
| Retrieve call metadata such as stream ARN and timestamps |
Resource specification: This permission is limited to your specific Amazon Connect instance. Example ARN: arn:aws:connect:<region>:<account-id>:instance/<instance-id>.
IAM Policy
Once the required permissions are defined, create an IAM policy and attach it to a role that Reality Defender can assume. This keeps access secure and limited to only the actions and resources required for the integration to function.
Create a new IAM policy using the JSON below. Replace the Resource ARNs with the actual ARN values: use the SQS ARN from Step 3, and the Kinesis Video Stream and Amazon Connect instance ARNs from Step 1, respectively.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "KVSList",
"Effect": "Allow",
"Action": "kinesisvideo:ListStreams",
"Resource": "*"
},
{
"Sid": "SQS",
"Effect": "Allow",
"Action": [
"sqs:SendMessage",
"sqs:ReceiveMessage",
"sqs:DeleteMessage",
"sqs:ChangeMessageVisibility"
],
"Resource": "arn:aws:sqs:<region>:<account-id>:<sqs-name>"
},
{
"Sid": "KVSContactStreams",
"Effect": "Allow",
"Action": [
"kinesisvideo:GetDataEndpoint",
"kinesisvideo:GetMedia",
"kinesisvideo:DescribeStream"
],
"Resource": "arn:aws:kinesisvideo:<region>:<account-id>:stream/<kvs-stream-name>*"
},
{
"Sid": "ConnectContacts",
"Effect": "Allow",
"Action": "connect:GetContactAttributes",
"Resource": "arn:aws:connect:<region>:<account-id>:instance/<instance-id>/contact/*"
}
]
}
Example:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "KVSList",
"Effect": "Allow",
"Action": "kinesisvideo:ListStreams",
"Resource": "*"
},
{
"Sid": "SQS",
"Effect": "Allow",
"Action": [
"sqs:SendMessage",
"sqs:ReceiveMessage",
"sqs:DeleteMessage",
"sqs:ChangeMessageVisibility"
],
"Resource": "arn:aws:sqs:us-east-1:1234567890:integrations-aws-connect"
},
{
"Sid": "KVSContactStreams",
"Effect": "Allow",
"Action": [
"kinesisvideo:GetDataEndpoint",
"kinesisvideo:GetMedia",
"kinesisvideo:DescribeStream"
],
"Resource": "arn:aws:kinesisvideo:us-east-1:1234567890:stream/realcall-connect-realitydefender-labs-use1-contact-*"
},
{
"Sid": "ConnectContacts",
"Effect": "Allow",
"Action": "connect:GetContactAttributes",
"Resource": "arn:aws:connect:us-east-1:1234567890:instance/b4ba8fe2-736b-483d-8ceb-726071d45e77/contact/*"
}
]
}
The created policy looks like this:
Attach the Policy to a Role
In the AWS Management Console, navigate to IAM > Roles.
Create a new role or select an existing one designated for Reality Defender.
When creating a new role,
Set the Trusted Entity Type to “AWS account”.
Select Another AWS account and enter the account ID provided by Reality Defender.
Under Add Permissions, attach the previously created policy to the role.
Provide Reality Defender with the Role ARN so it can assume the role and access the required resources.
Configure the Trust Relationship
The IAM role must also include a trust relationship that allows Reality Defender to assume it.
In the role’s Trust relationships tab, configure the trust policy provided by Reality Defender. The policy should allow Reality Defender’s AWS account to assume the role using sts:AssumeRole.
Example:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "<reality-defender-aws-account-arn>"
},
"Action": "sts:AssumeRole"
}
]
}Replace <reality-defender-aws-account-arn> with the AWS principal provided by Reality Defender.
Step 6: Receiving Results
Once the integration is configured, Reality Defender analyzes calls using the media stream and contact metadata provided by Amazon Connect.
To retrieve the analysis result for a call, use the RealCall Session API. The Amazon Connect contact ID should be passed as the session_id when requesting results.
For authentication details, endpoint usage, response fields, and example requests, see RealCall Session API.
Summary
Once all steps are complete, the following will be in place:
Component | Purpose |
Amazon Connect — Live Media Streaming | Streams call audio to Kinesis Video Streams |
Contact Flow | Captures stream ARN, fragment number, and timestamps as contact attributes |
Amazon SQS Queue | Receives call event notifications from EventBridge |
Amazon EventBridge Rule | Forwards |
IAM Policy & Role | Grants Reality Defender scoped access to KVS, SQS, and Connect |
RealCall Session API | Retrieves analysis results for completed or in-progress calls |
If you encounter any issues during setup, please contact Reality Defender Support.