Integration Description

This document is an overview of the integration between Cogito and Amazon Connect, as well as a step-by-step guide for setting up the integration.

Amazon Connect is an easy to use omnichannel cloud contact center provided by AWS.

In order to capture audio and provide call guidance to customer agents/representatives, Cogito integrates with the Amazon Connect environment. It utilizes the below integration points to receive Call Events (CTI) and real time audio feeds:

• Amazon Kinesis Video Streams is providing media using the permissions configured in a private IAM role deployed using a SAM template.
• The Streams API is providing CTI events using a Javascript method that relays events to Cogito via HTTPS POST requests.

Integration Points

Media Streaming - Amazon Connect and Amazon Kinesis Video Streams

• Call media session information (metadata) is sent from Amazon Connect via a Lambda Function to Cogito’s EC2 instance.
• The client’s message contains a parameter ContactId which is used to match to the CTI Event's ContactID field.
• Once the match occurs - the matcher verifies the agent is configured in Cogito.
• Call Audio (media) is delivered to Cogito via Amazon Kinesis Video Streams feature.
• Amazon Connect is configured to enable Live Media Streaming.
• Connectivity is established from a Cogito’s EC2 instance running OSS process to Amazon Connect Kinesis Video Streams.
• The permission to send the media to Cogito is configured via a private IAM role deployed using a SAM template.
• The price for Kinesis Video Streams in US-East is $0.0085 per GB ingested and $0.0085 per GB consumed at the time of writing. Please refer to https://aws.amazon.com/kinesis/video-streams/pricing/ for current pricing.

CTI Streaming - Streams API

• Agent and Contact events will be sent via the Streams API to the Cogito’s AWS API Gateway.
• Cogito integrates with the Streams API used to control integrations of the Amazon Connect Contact Control Panel (CCP).
• To integrate with Cogito, the cogito-connect-streams JS library will need to be added to the same code that initializes the amazon-connect-streams library.
• The cogito-connect-streams library would need to be initialized using the info below provided by Cogito:

• Cogito's connect streams API will call the agent() and contact() functions on the initialized connect object to subscribe to state change events.
• Cogito's connect streams API will then forward these events to Cogito over HTTPS to the /cticalls endpoint of the configured URL.

Call Matching

Both Kinesys Video Stream and Streams API CTI feeds will contain “ContactId” parameter that will be used to perform call matching:

• AmazonConnect ContactId

User Management

Cogito User Management requires a standardized set of data associated with each user. Cogito uses this information primarily to enable telephony integrations and to enable appropriate reporting pipelines.

Users will be provisioned on the Cogito system with Amazon Connect user information. The attribute Cogito uses for agent identification is Amazon Connect username. Cogito receives this value as username in the Streams API events. The username is provisioned as the Telephony Agent ID attribute in Cogito User Management.

There are several methods of user management in Cogito:

• .CSV file : client provides a standardized set of data associated with each user, compiled into a “User Input File”, to input users into Cogito's systems. The User Input File should be provided as a single un-tabbed .CSV file.
• Cogito's Admin Service APIs: Cogito's Admin Service APIs is a collection of REST APIs that can be used by authenticated and authorized clients to onboard and manage their users in their own namespace which is referred to as a “domain” in this document.

Customer Configuration Items

Prerequisites - Before you Begin

The process for integration between Cogito and Amazon Connect requires that a number of Amazon Resource Names (ARNs) and other identifiers must be communicated.

Cogito will provide the following information:

• The AWS Account ID.
• The ARN of the media-related Lambda function in the Cogito VPC.
• The ARN of the Amazon EventBus.
• The @cogitocorp/cogito-connect-streams- package provided through NPM.
• apiUrl - the URL of Cogito’s HTTP endpoint for telephony.
• site - the agent site.
• apiKey - the API key used to authenticate HTTP requests.

Client will provide the following information:

• The ARN of Client’s Amazon Connect instance.
• The prefix of Client’s Kinesis Video Stream. If a Kinesis Video Stream is not yet set up, provide this prefix to Cogito after completing Step 1 of Configuring Media Streaming.
• The ARN for the IAM Role created during this procedure as described under “Configuring Media Streaming” section 3.

Below are the detailed instructions on how to obtain the Amazon Connect ARN and "Kinesis video stream prefix" for the Amazon Connect account, as well as the URL for the softphone that will be used to provide the ARN and softphone URL to Cogito:

1. Log into the AWS account where Amazon Connect is configured.
2. Type "Amazon Connect" into the AWS search bar, hit enter, and select the desired "Instance alias" that will be used.
3. Copy the "Instance ARN" field in the "Distribution Settings". It should look like this:

The ARN in this example was: arn:aws:connect:us-east-1:274457450602:instance/86bd8f23-2dd5-45c1-9f46-60e61f8d1a78

4. Select "Data storage" from the left hand side and copy the "Kinesis video stream prefix" value from the "Live media streaming" section since this may be used later:

The "Kinesis video stream prefix" in this example was: telephonydev-connect-telephonydev-contact-

This does not need to be provided to Cogito, but should be documented since it will be used later in the “Configuring Media Streaming” Section 2.b.

Configuring Media Streaming

Call Audio (media) is delivered to Cogito via Amazon Kinesis Video Streams feature.

The below steps are performed inside the AWS Management Console

1. Select the Amazon Connect service. If Kinesis Video Streams is not configured to enable Live Media streaming, complete the following steps:

a) Select Amazon Connect Instance.

b) Navigate to the Data storage tab and click the Edit button in the Live media streaming section.

c) Check the Enable live media streaming checkbox that appears.

d) In the Prefix input box, enter the desired prefix for your Kinesis Video Stream.

e) Click Save.

📘

If you haven’t already - provide this prefix to Cogito, as indicated in the Prerequisites section of this document.

2. Deploy the iam-role-awsconnectkinesis4cogito serverless app that was shared by Cogito.

📘

Please note, Cogito will need to share the application with you before you are able to access it.

a) In the AWS search bar type in "Serverless Application Repository" → Click “Enter” → Select "Available applications" → Select "Private applications" → Select the iam-role-awsconnectkinesis4cogito serverless app that was shared by Cogito.

b) Complete the "Application settings" section with the following information:

• Application name - iam-role-awsconnectkinesis4cogito;
• CogitoAwsAccountId - the AWS account number of the Cogito account that hosts the amazon-connect Lambda.

This can be found by copying the value between the region and function in the ARN provided by Cogito. In this example the CogitoAwsAccountId was: 877034620506 .

• CogitoEventBusArn - the ARN of the Amazon EventBus provided by Cogito.
  In this example the CogitoEventBusArn was: arn:aws:events:us-east-1:877034620506:event-bus/cogito-002-us-east-1-Amazon-Connect-Contact-Events.
• KinesisVideoStream - this is the "Kinesis vide stream prefix" value that was retrieved in the Prerequisites section.

In this example the KinesisVideoStream was: telephonydev-connect-telephonydev-contact-

c) Click "Deploy".

3. Provide the deployed iam-role-awsconnectkinesis4cogito serverless app ARN to Cogito:

a) In the AWS search bar type in "IAM" → Click “Enter” → Select "Roles" on the left side → Type in "RoleKinesis4Cogito" in the "Roles" search bar → Select the option that says “serverlessrepo-iam-...”.

b) Copy the ARN in the middle of the page and provide this to Cogito. Cogito will now finish the deployment on their end.

The serverlessrepo-iam-... ARN in this example was: arn:aws:iam::274457450602:role/serverlessrepo-iam-role-a-RoleKinesis4CogitoEnable-1ISA7TLQHF7AH

The below steps are performed inside the Amazon Connect Dashboard

1. In the desired "Instance Alias" in "Amazon Connect" select the "Access URL" and log in to Amazon Connect.
2. On the left hand side select "Routing".
3. Navigate to your Contact Flows list.
4. For each contact flow that processes calls that will go through Cogito perform the following:

a) Select the name of the Contact Flow to open the customizer.

b) Select "Interact", then select "Start media streaming", and create a connection from "Start" to the "Start media streaming" block.

c) Select "Start media streaming" and ensure that both "From the customer" and "To the customer" are checked:

d) Select "Integrate", then select "Invoke AWS Lambda function", and create a connection from "Start media streaming: Success" to "Invoke AWS Lambda function".

e) Select "Invoke AWS Lambda function" and copy the AmazonConnect "Function ARN" provided by Cogito into the "Select a function" field:

In this example the "Function Arn" was: arn:aws:lambda:us-east-1:877034620506:function:AmazonConnect-AmazonConnectA-AmazonConnectFunction-1JYJMI5SY64HX
Cogito recommends specifying a Timeout value of 3 seconds.

f) Create "Invoke AWS Lambda function: Success", "Invoke AWS Lambda function: Failure", and "Start media streaming: Failure" connections to the next successful step in the contact flow.

g) The following diagram is a sample Contact Flow Configuration:

h) Select "Save" and then select "Publish" to save the changes.

Configuring CTI Streaming - Streams API

In order to receive CTI events, Cogito integrates with the Streams API used to control integrations of the Amazon Connect Contact Control Panel (CCP). Agent and Contact events that contain the snapshot of the current state of the agent or contact are sent to Cogito whenever the state changes.
To integrate with Cogito, the cogito-connect-streams JS library will need to be added to the same code that initializes the amazon-connect-streams library.

Installing and setting up the Amazon Connect Streams API integration

Cogito's connect streams API will call the agent() and contact() functions on the initialized connect object to subscribe to state change events. It will then forward these events to Cogito over HTTPS to the /cticalls endpoint of the configured URL.

1. Install cogito-connect-streams JS library. It can be installed using npm or yarn from https://www.npmjs.com/package/@cogitocorp/cogito-connect-streams
   npm install @cogitocorp/cogito-connect-streams.
2. Import with nmp and ES6
   import "@cogitocorp/cogito-connect-streams".
3. Initialize the library:

a) Place a call to
connect.core.initCCP({ /_ ... _/ }) ;

b)Initialize library using
cogito.initCogito({ apiUrl: cogitoRestURL, apiKey: cogitoRestAPIKey, site: 'site1' }) .

4. The values for cogitoRestURL, cogitoRestAPIKey, and site will be provided by Cogito.

Solution Architecture Diagram - AmazonConnect

Detailed Low Level Design Diagram

References

• Streams API Documentation on Github
• Enabling Live Media Streaming
• Configuring Contact Flows