In this article:

Integration Overview
Architecture Summary
        Key Terminology
        What Data Assembled Reads
        Multi-Region Support
Pre-Installation Planning
        AWS Account Requirements
        Amazon Connect Requirements
Installation Guide
        Choosing the Correct CloudFormation Template
        Select the Correct Setup Option
               Setup Option 1: No Existing Streams or Buckets
               Setup Option 2: Existing Streams Setup
               Setup Option 3: Existing s3 Bucket
Validating data in Assembled
Limitations & Known Constraints
FAQ

Integration Overview

Architecture Summary

The Assembled + Amazon Connect integration works by reading two streams of data from your AWS account: Agent Events (real-time agent activity) and Contact Trace Records (CTRs) (completed contact metadata). Assembled never writes to your AWS environment - all access is strictly read-only.

Data Flow

Agent Events are generated by Amazon Connect in real time as agents change status, handle contacts, or go available/unavailable. Amazon Connect publishes these events directly to an Amazon Kinesis Data Stream, which Assembled polls approximately every 30-60 seconds to update agent state data in the platform.

Contact Trace Records (CTRs) are generated by Amazon Connect when a contact (call, chat, task) is completed. These records are delivered either directly to a Kinesis Data Stream or via Kinesis Data Firehose into an Amazon S3 bucket, where Assembled reads them and maps them to cases in the platform.

Cross-Account Access

Assembled does not store credentials to your AWS account. Instead, access is granted through AWS Security Token Service (STS) role assumption – a standard, auditable AWS security pattern.

During setup, a CloudFormation template creates an IAM role called AllowAssembledReadAccess in your AWS account. This role is configured to trust Assembled's AWS account, allowing Assembled's services to temporarily assume the role and read from your Kinesis streams and S3 bucket. Credentials are short-lived and never stored. All access can be revoked instantly by deleting the IAM role.

What Gets Created in Your AWS Account

Depending on your existing AWS setup, the CloudFormation template will create some or all of the following resources:

No existing resources in your account are modified or deleted.

Key Terminology

Amazon Connect Instance / ARN
A single deployment of Amazon Connect within an AWS account. Each instance has a unique identifier called an Instance ARN. Customers may have multiple instances across different AWS regions.

Contact Trace Record (CTR)
A record generated by Amazon Connect each time a contact (call, chat, or task) is completed. CTRs contain metadata about the contact including queue, duration, agent, and customer journey details. Assembled reads CTRs to create and update cases in the platform.

Agent Event
A real-time record generated by Amazon Connect whenever an agent's state changes, such as going available, handling a contact, or going on break. Assembled reads Agent Events to track and display accurate agent activity in the platform.

Amazon Kinesis Data Stream
An AWS service that captures and transports real-time data records. In this integration, Kinesis streams are used to deliver Agent Events from Amazon Connect to Assembled, and optionally to deliver CTR data as well.

Amazon Kinesis Data Firehose
An AWS service that reliably loads streaming data into destinations such as S3. In this integration, Firehose is used as the delivery mechanism that transports CTR data from a Kinesis stream into an S3 bucket for Assembled to read.

Amazon S3 (Simple Storage Service)
AWS object storage used in this integration to store CTR files delivered by Kinesis Firehose. Assembled reads CTR data from S3 using date-based prefixes to efficiently locate the relevant files.

S3 Prefix
The folder-like path structure used to organize objects within an S3 bucket. Assembled requires CTR files to be organized using a standard date prefix format (YYYY/MM/dd/) in order to efficiently query data by date.

AWS CloudFormation
An AWS service that provisions infrastructure resources using pre-written templates. Assembled provides CloudFormation templates that automatically create the necessary Kinesis streams, S3 buckets, Firehose delivery streams, and IAM roles required for the integration.

CloudFormation Stack
A collection of AWS resources created and managed together using a single CloudFormation template. During setup, customers deploy an Assembled-provided stack in their AWS account. A status of CREATE_COMPLETE confirms successful deployment.

IAM (Identity and Access Management)
The AWS service that controls who can access what within an AWS account. In this integration, IAM is used to define exactly what Assembled is permitted to read, and nothing more.

IAM Role
A set of permissions that can be temporarily assumed by a trusted entity. The CloudFormation template creates an IAM role called AllowAssembledReadAccess in the customer's account, which Assembled's services assume in order to read data.

What Data Assembled Reads

Assembled reads two categories of data from your Amazon Connect environment: Contact Trace Records (CTRs) and Agent Events. It also makes a small number of read-only API calls to Amazon Connect directly for user metadata. All data is read-only and Assembled never modifies anything in your AWS account.

Contact Trace Records (CTRs)

CTRs are generated when a contact is completed. Assembled reads the following fields from each CTR: 

Contact Info:

Agent Info (within CTR):

Queue Info (within CTR):

Agent Events 

Event Metadata:

PII Fields and Redaction:

Optional PII Redaction

Assembled supports an optional configuration that, when enabled, automatically clears all fields marked above before data is stored or processed. All remaining fields, including contact IDs, timestamps, durations, queue names, and routing profiles, are fully preserved. Contact your Assembled account team to enable this flag for your organization.

Multi-Region Support

Assembled supports Amazon Connect deployments across multiple AWS regions. If your organization operates Amazon Connect instances in more than one region, each region must be configured individually in Assembled.

How It Works Across Regions

Each region maintains its own set of streaming resources, but certain components are shared at the AWS account level to avoid duplication:

Multiple Instances in the Same Region

If you have more than one Amazon Connect instance running in the same AWS region, those instances can share a single Agent Events Kinesis stream and a single Firehose delivery stream. You do not need to run the CloudFormation template again for a second instance in the same region. You do need to add each instance's ARN separately in Assembled.

Key Considerations for Multi-Region Deployments

The IAM role is created only once. The AllowAssembledReadAccess role is scoped to your AWS account and covers all regions automatically. Do not re-run the initial setup CloudFormation template when adding a new region — use the dedicated new region template instead to avoid conflicts. 

Each region requires its own Amazon Connect Data Streaming configuration. You must enable Data Streaming separately for each Connect instance and point the CTR and Agent Events destinations to the correct region-specific Kinesis streams. 

The S3 bucket is shared across all regions. CTR data from every region is delivered into the same {AccountId}-assembled-ctr-bucket. Assembled uses the date prefix and region metadata within each file to distinguish records across regions. 

Agent Events gaps cannot be backfilled. If a region is added after agents are already active, any Agent Event data from before the setup date is permanently unrecoverable. Plan region additions ahead of go-live where possible to avoid historical gaps in agent state data.

Pre-Installation Planning

Before beginning the Assembled<>Amazon Connect integration, confirm that all of the following requirements are in place. Skipping this step is one of the most common causes of blocked or failed implementations.

AWS Account Requirements

The person running the CloudFormation template must have sufficient AWS permissions. The setup process creates IAM roles, Kinesis streams, Firehose delivery streams, and S3 buckets. The AWS user running CloudFormation needs the following permissions: 

• Permission to run CloudFormation templates
• List, Read, and Write access to AWS::IAM
• List, Read, and Write access to AWS::Kinesis::Stream
• List, Read, and Write access to AWS::KinesisFirehose::DeliveryStream
• List, Read, and Write access to AWS::S3
• Admin access to Amazon Connect

Note: These permissions are broadly scoped. If the person managing the Assembled implementation does not have this level of access, involve an AWS admin or engineer. Do not attempt to run the CloudFormation template with a restricted IAM user - the stack will fail and roll back.

Your AWS account must not have restrictive Service Control Policies (SCPs) that block resource creation. SCPs are organization-level policies that can prevent CloudFormation from creating Firehose delivery streams, S3 buckets, or IAM roles - even if the individual user has the correct permissions. This has blocked implementations for customers operating in resell or managed AWS accounts. 

If your organization uses AWS Organizations and you suspect SCPs may be in place, confirm with your AWS administrator before starting. If SCPs cannot be modified and the CloudFormation template fails, contact Assembled support - manual configuration steps may be available as an alternative path.

Amazon Connect Requirements

You must have at least one active Amazon Connect instance. The instance must be fully configured with agents, queues, and routing profiles before beginning the Assembled setup. Assembled reads data about contacts and agents - if the instance is not yet in use, there will be nothing to sync.

You must know your Connect Instance ARN. This is required during the Assembled setup flow. To find it, log in to the AWS Console, navigate to Amazon Connect, click your instance alias, and copy the Instance ARN from the Overview page. It follows the format: arn:aws:connect:{region}:{account-id}:instance/{instance-id}.

Amazon Connect Data Streaming must be enabled. This is the feature inside Amazon Connect that authorizes it to push CTR and Agent Events data to your Kinesis or S3 destination. It is not enabled by default. If this is not turned on before or during setup, no data will flow to Assembled.

Installation Guide

Choosing the Correct CloudFormation Template

To start the installation process, you’ll first need to determine which Assembled configuration route is correct for you based on any existing configuration that may already be configured.

If you’re not sure, start by logging into the AWS Console at console.aws.amazon.com using an account with Amazon Connect admin permissions.

Next, in the search bar, type Amazon Connect Customer and select it from the results to navigate to the Amazon Connect service page.

Note: please also ensure you have the correct region selected in the top-right corner.

On the next page, click the instance alias of the Connect instance you are integrating with Assembled.

Then, in the left-hand navigation panel, click Data streaming.

On this page, this is where the setup will differ depending on what’s already configured (or not).

If your setup looks like the below, you will follow the setup steps outlined immediately below in the below Setup Option 1: No Existing Streams or Buckets section.

If your setup looks like the below (with data streaming already enabled for Contact Trace Records and Agent Events), you can jump to the below Setup Option 2: Existing Streams Setup section.

In the above scenario, the Kinesis streams have already been created, so we’ll deploy a different Cloudformation template to ensure Assembled leverages that existing infrastructure, rather than trying to create them from scratch.

Start Amazon Connect setup in Assembled

To start, log into Assembled and navigate to Settings, click Third-party integrations in the left-hand panel, switch to the Available tab, locate Amazon Connect and click Configure integration.

Select the Correct Setup Option

Here, which option you select will depend on what infrastructure (kinesis streams and/or S3 bucket) you already have set up.

Setup Option 1: No Existing Streams or Buckets

If you have no existing streams or s3 bucket, click here for installation instructions.

Setup Option 2: Existing Streams Setup

If you have existing CTR and Agent events kinesis streams, click here for installation instructions.

Setup Option 3: Existing s3 Bucket

If you have an existing CTR s3 bucket, click here for installation instructions.
 

Validating data in Assembled

Assembled polls for new data on a 15-second cycle. After completing the setup steps, allow a few minutes before expecting to see data appear.

Use this checklist to confirm your integration is fully operational:

• Agent states are appearing in the Agent analysis page within at least 60 seconds of state changes
• Completed contacts (calls, chats, tasks) appear in Assembled after ending in Amazon Connect
• Contacts are attributed to the correct queues via the Queues and Exclusions page
• Contacts are attributed to the correct agents 
• Agent handle time and ACW time look accurate
• Adherence is tracking correctly for scheduled agents (if applicable)
• Amazon Connect IDs appear on agent profiles within 24 hours

Limitations & Known Constraints

"New Calls" and "Open Calls" will always show 0

Amazon Connect only generates Contact Trace Records (CTRs) after a call has fully ended. Every contact arrives in Assembled in a terminal state: Solved, Abandoned, Missed, or Transferred. There is no mechanism in Amazon Connect to stream in-progress contact data, so real-time "open" or "active" call counts are not available through this integration. This is expected behavior, not a configuration issue.

Live queue metrics are not supported

Metrics such as current callers waiting, longest wait time, and real-time queue depth are not available through the Assembled integration. Your Amazon Connect dashboard remains the best source for real-time queue visibility.

Assembled does not show which specific contact an agent is currently handling

For live visibility into agent activity, the relevant signal is agent state (e.g., "On Contact"), not an individual ticket or contact record.

The S3 bucket used for CTRs must contain only CTR data

Assembled reads every object in the configured bucket assuming it is a CTR. Storing other data types in the same bucket will cause processing errors.

DISCONNECT CTRs are excluded by default

DISCONNECT-type CTRs, which are typically generated by exit surveys at the end of a contact flow, are excluded from Assembled by default to avoid inflating contact volume metrics. If you need these included, contact Assembled support.

Historical agent state data cannot be recovered

Agent state data is real-time only and is not stored for backfill. If agent state streaming is interrupted, those state records cannot be reconstructed retroactively. CTR data, however, can be backfilled from S3.

FAQ

Q: Can I use Firehose instead of Kinesis for Agent Events?

No. Agent Events only support Kinesis. Firehose is not available as a destination for Agent Events in Amazon Connect.

Q: Do I need to use Assembled's CloudFormation template?

No. You can create AWS resources any way you prefer, as long as there is an S3 bucket receiving CTRs and a Kinesis stream receiving Agent Events in the expected format. For custom setups, Assembled provides an IAM-only template to grant the necessary access to your existing resources.

Q: Can the integration support multiple AWS regions?

Yes. Run the new region CloudFormation template for each additional region. Make sure to switch the region selector in CloudFormation (it defaults to us-east-1) to the correct region before deploying.