Amazon Connect integration

Plans and permissions:

• Connect Amazon Connect: Admin role, or a custom role with Configure third-party integrations set to Can configure third-party integrations
• Fix a team member’s Amazon Connect ID: Admin or Manager role, or a custom role with Manage team set to Create, edit, or delete any person or Create, edit, or delete certain people
• In AWS, you also need a user who can run CloudFormation templates, create IAM roles, Kinesis streams, Firehose delivery streams, and S3 buckets, and turn on data streaming in Amazon Connect.

Use the Amazon Connect integration to bring your Amazon Connect agent states and completed contacts into Assembled, so you can forecast, schedule, and track adherence for your Amazon Connect team. Setup runs a CloudFormation template in your AWS account that gives Assembled read-only access to your Amazon Connect data, and then you enter a few AWS details in Assembled.

To start, go to Configure > Third-party integrations, select Available, and find Amazon Connect.

This article covers Amazon Connect only. For the fields Assembled reads and how it accesses your AWS account, see Amazon Connect data and AWS access.

How the Amazon Connect integration works

Assembled reads two kinds of data from your AWS account. It never writes to your AWS account.

• Agent events: Amazon Connect publishes an agent event each time a team member’s state changes, such as going available or starting a contact. It sends them to an Amazon Kinesis data stream, and Assembled reads the stream about every 30 seconds to update agent states.
• Contact trace records (CTRs): Amazon Connect creates a CTR when a contact (a call, chat, email, or task) ends. Amazon Kinesis Data Firehose delivers CTRs to an Amazon S3 bucket, and Assembled checks the bucket for new records about every 15 seconds.

To load contact history from before you connected, see Historical Amazon Connect contact data.

Assembled reads your data through an IAM role named AllowAssembledReadAccess, which the CloudFormation template creates in your AWS account. To revoke access, delete the role.

Amazon Connect channels map to Assembled channels like this:

Amazon Connect channel	Assembled channel
VOICE	Phone
CHAT	Chat
EMAIL	Email
TASK	Back office

Keep in mind: Agent events can only be sent to a Kinesis data stream. Amazon Connect doesn’t offer Firehose as a destination for agent events.

What the template creates

The template you run depends on the options you choose in Assembled. It only creates what you don’t have yet, and it doesn’t change or delete existing resources.

Resource	What it’s for	When it’s created
AllowAssembledReadAccess IAM role, with read policies for Kinesis, S3, and Amazon Connect	Lets Assembled read your streams, bucket, and Amazon Connect users	Always
assembled-agent-events-stream Kinesis data stream	Receives agent events from Amazon Connect	If you don’t already publish agent events to a Kinesis stream
<account-id>-assembled-ctr-bucket S3 bucket	Stores CTRs for Assembled to read	If your CTRs aren’t already in an S3 bucket
<region>-assembled-ctr-delivery-stream Firehose delivery stream, with the AssembledFirehoseServiceRole IAM role	Delivers CTRs to the S3 bucket, either directly from Amazon Connect or from your existing CTR Kinesis stream	If your CTRs aren’t already in an S3 bucket

You don’t have to use the resources the template creates. Any setup works, as long as CTRs land in an S3 bucket and agent events in a Kinesis stream, in the format Amazon Connect produces. If you already stream CTRs to an S3 bucket and agent events to a Kinesis stream, the template only creates the IAM role and its read policies.

What the integration doesn’t include

• New and open contacts: Amazon Connect only creates a CTR after a contact ends, so every contact arrives in Assembled already solved, abandoned, missed, or transferred. New and open contact counts for Amazon Connect always show 0.
• Live queue metrics: Callers waiting, longest wait, and current queue depth aren’t available. Use your Amazon Connect dashboard for these.
• The contact a team member is on: Assembled shows the team member’s state, such as on contact, but not which contact they’re handling.
• Exit survey contacts: Contacts with the DISCONNECT initiation method, usually exit surveys at the end of a contact flow, are left out so they don’t inflate volume. To include them, contact our team.
• Lost agent state history: Agent events are read only as they happen, so agent states from before data streaming is on, or from a time when streaming stops, can’t be recovered. CTRs can be loaded again from S3.

Before you start

Check these before you begin. Missing permissions or access are the most common reasons setup fails.

AWS account

The person who runs the template needs permission to run CloudFormation templates, and list, read, and write access to IAM, Kinesis data streams, Kinesis Data Firehose delivery streams, and S3, plus admin access to Amazon Connect. If you don’t have this access, ask an AWS administrator to run the template: with a restricted user, the stack fails and rolls back.

Service control policies (SCPs) in AWS Organizations can block CloudFormation from creating IAM roles, S3 buckets, or Firehose delivery streams, even when the user has the right permissions. This often happens in resold or managed AWS accounts. If you use AWS Organizations, check with your AWS administrator before you start. If the SCPs can’t change and the template fails, contact our team about setting up the resources another way.

Amazon Connect

You need at least one Amazon Connect instance that’s already set up with users, queues, and routing profiles. If the instance isn’t in use yet, there’s nothing for Assembled to sync.

You also need the instance’s ARN. In the AWS console, open Amazon Connect, select your instance alias, and copy the Instance ARN from the overview page. It looks like arn:aws:connect:<region>:<account-id>:instance/<instance-id>.

Data streaming must be on in Amazon Connect. It’s off by default, and without it no data reaches Assembled. If the template creates a stream for you, you point data streaming at it after the stack is created. See Turn on data streaming in Amazon Connect.

Check your current data streaming setup

The options you choose in Assembled depend on where Amazon Connect already sends your data. To check:

1. Sign in to the AWS console with an account that has Amazon Connect admin access, and make sure the region in the top-right corner is the region of your instance.
2. In the search bar, enter Amazon Connect and select it from the results.
3. Select the Instance alias of the instance you’re connecting to Assembled.
4. In the navigation panel, select Data streaming.

If Enable data streaming isn’t selected, nothing is streamed yet, and the template creates everything.

If data streaming is on, note where Contact Trace Records and Agent Events are sent. For example, if both go to existing Kinesis streams, the template uses those streams instead of creating new ones.

To match what you find to the options in Assembled, see Choose your setup options.

Connect Amazon Connect

These steps set up your first region. To add another, see Add another region or instance.

1. Go to Configure > Third-party integrations and select Available.

2. On the Amazon Connect card, select Configure integration, then select Get started.

3. Under Contact Trace Records (CTR) and Agent events, choose the options that match your setup (see Choose your setup options), and select Next.

4. Check the summary under Your selection, then select Fill out AWS Form. The CloudFormation Quick create stack page opens in a new tab with the right template, and the stack is named assembled-integration-stack. To see what the template creates, select View template.

   

5. The page opens in the US East (N. Virginia) region. If your Amazon Connect instance is in another region, switch to that region in the top-right corner of the AWS console before you continue.

6. If the template asks for parameters, enter your existing stream or bucket ARNs. See Use existing Kinesis streams or Use an existing S3 bucket.

7. At the bottom of the page, select the checkbox acknowledging that CloudFormation might create IAM resources, then select Create stack. The stack takes a minute or two to create, and its status changes to CREATE_COMPLETE.

8. If the template created a stream or delivery stream for you, turn on data streaming in Amazon Connect.

9. Back in Assembled, select I have successfully run the CloudFormation template on my AWS account, then select Confirm.

   

10. Enter your AWS details (see Provide your AWS details), then select Submit.

11. When you see Your Amazon Connect integration has been successfully added., select Done.

The Amazon Connect card now moves to In use, with a Connected tag, your AWS Account ID, Regions, when it was authorized, and a sync line for agent states and CTRs. If a sync line turns red, hover over it to see the error. To disconnect, open the Edit integration menu on the card and select Disable integration.

Choose your setup options

In Assembled, you answer two questions about your current setup. Your answers decide which template runs and which parameters you fill in.

Your current setup	Contact Trace Records (CTR)	Agent events	Template parameters
Nothing is streamed yet	CTR data is not being streamed to S3 or Kinesis	Cleared	None
CTRs and agent events go to existing Kinesis streams	CTR data is being streamed to a Kinesis Stream	Agent events are being published to a Kinesis stream	Both stream ARNs. See Use existing Kinesis streams.
CTRs go to an existing S3 bucket	CTR data is being streamed to an S3 bucket (Recommended) (default)	Selected only if agent events already go to a Kinesis stream	The bucket ARN, and the agent events stream ARN if you selected it. See Use an existing S3 bucket.

Any other combination works the same way: choose the CTR option that matches, and select the agent events option if you already publish agent events to a Kinesis stream.

Use existing Kinesis streams

If you chose CTR data is being streamed to a Kinesis Stream and Agent events are being published to a Kinesis stream, the template asks for the ARN of each stream. It creates an S3 bucket and a Firehose delivery stream that copies CTRs from your stream into the bucket.

1. In the AWS console, search for Kinesis and open it.
2. In the Data Streams tile, select the number of streams.
3. Select your CTR stream and copy the ARN from its summary. Do the same for your agent events stream.
4. Back on the Quick create stack page, under Parameters, enter the CTR stream’s ARN in ctrKinesisStreamArn and the agent events stream’s ARN in AgentEventsKinesisStreamArn.

Important: Check that each ARN is in the right field. The parameter descriptions in the template both mention agent events, so go by the parameter name.

Use an existing S3 bucket

If you chose CTR data is being streamed to an S3 bucket (Recommended), the template asks for the bucket’s ARN. If you also selected the agent events option, it asks for that stream’s ARN in AgentEventsKinesisStreamArn, as in Use existing Kinesis streams.

1. In the AWS console, search for S3 and open it.
2. On the Buckets page, select the bucket that holds your CTRs.
3. Choose the Properties tab and copy the bucket’s ARN.
4. Back on the Quick create stack page, under Parameters, enter it in ContactTraceRecordsS3BucketArn.

Important: Use the bucket only for CTRs. Assembled reads every file in the bucket’s date folders as a contact trace record, and other files cause processing errors. Assembled looks for files in date folders named YYYY/MM/DD/ (the Firehose default) or year=YYYY/month=MM/day=DD/. If your CTRs are under another folder in the bucket, contact our team to add it.

Provide your AWS details

After you confirm that the template ran, Assembled asks for these details. Which fields appear depends on the options you chose.

Field	Where to find it
AWS Account ID	The 12-digit account ID in the account menu at the top right of the AWS console.
Region	The region your Amazon Connect instance is in, shown at the top right of the AWS console. Choose it from the list, such as US East (N. Virginia): us-east-1.
Connect Instance ARN	On your instance’s overview page in Amazon Connect, under Distribution settings.
CTR S3 Bucket Name	Appears if CTRs go to an existing S3 bucket. Enter the bucket’s name, not its ARN, as shown on the S3 Buckets page.
Agent Events Kinesis Stream Name	Appears if agent events go to an existing Kinesis stream. Enter the stream’s name, as shown in Kinesis Data streams.
External ID (optional)	Leave blank, unless your AWS team added an external ID requirement to the AllowAssembledReadAccess role.

Turn on data streaming in Amazon Connect

If the template created the agent events stream or the CTR delivery stream, point Amazon Connect at it. If you used your existing streams and bucket, there’s nothing to change.

1. In the AWS console, open Amazon Connect, select your instance alias, and select Data streaming.
2. Select Enable data streaming.
3. For Contact Trace Records, choose Kinesis Firehose and select the delivery stream named <region>-assembled-ctr-delivery-stream, such as us-east-1-assembled-ctr-delivery-stream.
4. For Agent Events, select the assembled-agent-events-stream Kinesis stream.
5. Save your changes.

Data starts flowing to Assembled once data streaming is on.

Check that data is coming in

Allow a few minutes after setup, then check:

• Agent states: In Monitor > Real-time agent analysis, team members’ states update within about a minute of a change in Amazon Connect. See Real-time agent analysis.
• Contacts: Completed calls, chats, and tasks appear a minute or two after they end, because Firehose delivers CTRs to S3 in batches about once a minute.
• Queues: In Configure > Queues and exclusions, contacts from the last hour appear in the count cards at the top of the page. See Queues and exclusions.
• Team members and handle time: Contacts are attributed to the right team members, and handle time and after-contact work look right.
• Adherence: Scheduled team members show adherence as expected.
• Amazon Connect IDs: Assembled matches team members to Amazon Connect users by email once a day, so within a day, team members’ profiles show their Amazon Connect ID. If an ID is missing or wrong, see A team member’s scorecard shows no Amazon Connect data or the wrong status.

Add team members from Amazon Connect

To add team members from Amazon Connect, go to Manage team > People management and select Add people > Import from Amazon Connect. See People management.

Set up queues for Amazon Connect

To route contacts into queues, create queue rules in Configure > Queues and exclusions, using the Amazon Connect properties Channel, Initiation method, Queue name, Queue ARN, Routing profile name, and Routing profile ARN. See Queues and exclusions.

Add another region or instance

Assembled supports Amazon Connect instances in more than one AWS region, and each region is set up separately. To add a region, contact our team. You run a separate new-region template in that region.

Some resources are shared across your AWS account, and some are created in each region:

Resource	Scope
AllowAssembledReadAccess IAM role	One per AWS account, shared by all regions
<account-id>-assembled-ctr-bucket S3 bucket	One per AWS account. CTRs from every region land in it, in date folders.
assembled-agent-events-stream Kinesis stream	One per region
<region>-assembled-ctr-delivery-stream Firehose delivery stream	One per region
<region>-assembled-read-kinesis-policy IAM policy	One per region, attached to the shared role

Important: Don’t run the first-region template again for a new region. The IAM role already exists, and running it again causes conflicts.

Turn on data streaming for each Amazon Connect instance, and point it at the streams in that instance’s region.

Instances in the same region can share one agent events stream and one delivery stream, so you don’t need to run a template again for them. To add another instance in the same region, contact our team with its ARN.

Agent events can’t be loaded for the time before a region is set up. If team members in a new region are already working, set up the region before you rely on their agent states in Assembled, to avoid gaps in their history.

Troubleshooting

A team member’s scorecard shows no Amazon Connect data or the wrong status

On a team member’s Agent scorecard, Amazon Connect data can be missing altogether, or the team member can show the wrong status, such as Offline all day while they’re working. This happens when their profile in Assembled has no Amazon Connect ID, or the wrong one. Assembled uses the ID to link the person’s Amazon Connect activity to their profile.

The Amazon Connect ID on a team member’s profile is the ARN of their Amazon Connect user, which looks like arn:aws:connect:<region>:<account-id>:instance/<instance-id>/agent/<user-id>. Amazon Connect identifies users by this ARN in agent events and contact records. If your integration is set up to identify people by username, the ID is the person’s Amazon Connect username instead.

Assembled fills in the ID once a day by matching the team member’s email in Assembled to their Amazon Connect user. It checks the user’s email first, then the secondary email, then the username.

Cause	How to tell	What to do
The team member’s email doesn’t match their Amazon Connect user	The team member’s profile has no Amazon Connect ID, and their email in Amazon Connect doesn’t match their email in Assembled. See Check the team member’s Amazon Connect ID.	Make the emails match, or enter the ID yourself.
The ID isn’t the user’s ARN	The ID on the profile isn’t an ARN. For example, it’s a Salesforce user ID, which often starts with 005, or the user ID on its own.	Enter the user’s ARN.
The ID belongs to a different Amazon Connect user	The ID is an ARN, but for a different Amazon Connect user, for example because two users share an email. See Check the team member’s Amazon Connect ID.	Fix the emails in Amazon Connect, then enter the right ARN.
The team member was added less than a day ago	The team member was added to Assembled or Amazon Connect less than a day ago, so the daily match hasn’t filled in their ID yet.	Wait for the next daily match, or enter the ID yourself.

After you fix the ID, allow some time for new activity to arrive, then check the team member’s scorecard again. If it still shows no data or the wrong status, check that the ID is the user’s ARN, not a Salesforce ID or another identifier. If that doesn’t help, chat with our team and include the team member’s name; their email in Assembled and in Amazon Connect; the Amazon Connect ID on their profile; the dates, times, and time zone where the data looks wrong; a screenshot of their scorecard; and what you’ve already tried.

Check the team member’s Amazon Connect ID

1. Go to Manage team > People management and select the team member’s name. Edit person opens.
2. Under Optional IDs, look at Amazon Connect ID. If it’s empty, the team member has no ID.
3. Compare the ID with the team member’s user ARN. The ARN is your instance ARN followed by /agent/ and the user’s ID. Your AWS administrator can also look it up with the Amazon Connect API.
4. In Amazon Connect, go to Users > User management, select the team member, and check that their email there matches their email in Assembled.

Make the emails match

This is the most reliable fix, because the daily match keeps the ID correct from then on.

1. In Amazon Connect, go to Users > User management and select the team member.
2. Set their email to the same address as their profile in Assembled, and save.

Assembled links the team member at the next daily match. You can also enter the ID yourself.

Enter the Amazon Connect ID yourself

Important: If the team member’s email matches a different Amazon Connect user, the daily match replaces the ID you enter. Fix the emails first.

1. Go to Manage team > People management and select the team member’s name.
2. Under Optional IDs, find Amazon Connect ID.
3. Enter the team member’s user ARN.
4. Select Save changes.

If the team member had no ID, this adds one. If they had the wrong one, this replaces it.