Amazon Connect

The Amazon Connect integration with ASAPP’s GenerativeAgent allows a caller into your Amazon Connect contact center to have a conversation with Generative Agent.

This guide demonstrates an example integration using AWS’s basic building blocks and ASAPP-provided flows. It showcases how the various components work together, but you can adapt or replace any part of the integration to match your organization’s requirements.

​

How it works

At a high level, the Amazon Connect integration with GenerativeAgent works by handing off the conversation between your Amazon Connect flow and GenerativeAgent:

1. Hand off the conversation to GenerativeAgent through your Amazon Connect Flows.
2. GenerativeAgent handles the conversation using Lambda functions to communicate with ASAPP’s APIs, and respond to the caller using AWS’s Text to Speech (TTS) service.
3. Return control back to your Amazon Connect Flow when:
   • The conversation is successfully completed
   • The caller requests a human agent
   • An error occurs

​

Before you Begin

Before using the GenerativeAgent integration with Amazon Connect, you need to:

• Get your API Key Id and Secret

  • Ensure your API key has been configured to access GenerativeAgent APIs. Reach out to your ASAPP team if you need access enabled.

• Have an existing Amazon Connect Instance

  • Have claimed phone numbers.
  • Access to an Amazon Connect admin account.

• AWS administrator account with the permissions for the following:

  • Creating/managing IAM roles/policies: create a policy permitting list/read operations on the Kinesis Video Streams associated with the Amazon Connect Flow
  • Managing Amazon Connect Instance
  • Create/manage Lambda functions
  • Create/manage CloudWatch Log Groups
  • Create/manage ElastiCache for Redis
  • Create/manage VPC

• Be familiar with AWS including Amazon Connect, IAM roles, and more:

  AWS Components

• Receive the Generative Agent Connect Flow and Prompts from your ASAPP team.

The components used in the example integration are intended for testing environments, and you can use your own components in Production when you integrate GenerativeAgent.

​

Step 1: Set up your AWS Account and Amazon Connect Instance

You need to set up your AWS Account and configure AWS services that will be used for an Amazon Connect flow that engages GenerativeAgent. You will configure the flow in a future step.

​

Provide a dedicated VPC

All components of the GenerativeAgent Amazon Connect integration expect to be in the same VPC.

Ensure you have a VPC with at least two subnets in different Availability Zones

​

Configure your Amazon Connect Instance

You need to connect your Amazon Connect Instance with an Amazon Kinesis Video Stream Service in your AWS account.

To configure the Amazon Connect Instance, you need to:

• Navigate to Connect -> Data storage -> Live Media Storage
• Enable Live Media Streaming under Data Storage options.
• Set a retention period at minimum of 1 hour.
• Save the kinesis video stream instance prefix, it will be used as part of setting up the permissions for the IAM role.

​

Create security groups

Create security groups that you will use for communication between the Lambda functions and the ElastiCache Cluster:

• Security group for the ElastiCache Cluster
• Security group for the PullAction Lambda
• Security group for the PushAction Lambda

You will use these security groups when setting up the Lambda Functions.

Once created, you will need to configure the security groups:

• PullAction Lambda Security Group
  • Outbound
    • Allow TCP traffic on port 6379 to the just created ElastiCache cluster security group
  • Save the security group id, it will be used when creating the PullAction Lambda.
• PushAction Lambda Security Group
  • Outbound
    • Allow TCP traffic on port 6379 to the just created ElastiCache cluster security group
  • Save the security group id, it will be used when creating the PushAction Lambda.
• ElastiCache Security Group
  • Inbound
    • Allow TCP traffic on port 6379 from the just created PullAction lambda security group
    • Allow TCP traffic on port 6379 from the just created PushAction lambda security group
  • Save the security group id, it will be used when creating the Redis ElastiCache Cluster.

​

Redis ElastiCache Cluster

The Amazon Connect Flow uses ElastiCache Clusters in order to store ordered list of actions for each call.

To configure the ElastiCache Cluster:

1. Create Subnet Group
   • In ElastiCache console, create a subnet group
   • Select your VPC and choose at least two subnets across different AZs
2. Create the Redis Cluster

   • Choose Redis as the engine

   • Select cluster mode (disabled/enabled)

   • Pick node type based on performance requirements

     The sizing is based on the amount of state that drives the memory and quantity of operations per second.

     You should size it based on the expected number of calls that will use GenerativeAgent.

     In this guide, we use a basic sizing. However you should test the sizing in your testing environments and size the VPC accordingly before launching to Production.

   • Choose Multi-AZ for enhanced reliability

   • Use the security group you created for the ElastiCache Cluster.

3. Connect the ElastiCache endpoint to the ASAPP-dedicated Amazon Connect Flow
   • Use the ElastiCache endpoint for all connections
   • Implement connection pooling
4. Save the Primary endpoint, it will be used as part of setting up the lambda functions.

​

Step 2: Create Lambda Functions to call GenerativeAgent

The GenerativeAgent Module expects certain Lambda functions to exist to interact with GenerativeAgent.

You will need to create the following Lambda functions:

• Engage
• PushAction
• PullAction

​

Engage

This lambda function sends REST API requests to ASAPP and engages GenerativeAgent into a conversation.

​

PullAction

This lambda function is called by the Amazon Connect Flow and queries Redis for next actions in a specific call.

The call identifier is the contactId taken from the Event.ContactData.

​

PushAction

ASAPP calls this lambda function to communicate a further action for each call GenerativeAgent is engaging.

This function also pushes next actions into Redis for PullAction to query at the next opportunity.

Save the ARN of the PushAction lambda function, it will be used when configuring the IAM role.

​

Step 3: Configure IAM Roles and Policies

As part of this integration, ASAPP services will reach out to your AWS account to invoke the lambda functions and access the Kinesis Video Streams.

ASAPP will need to assume a role in your AWS account to access these services.

We will provide you with the ARN of ASAPP’s GenerativeAgent role. You need to create an IAM role for ASAPP to assume and specify the ARN of the IAM role in the trust policy.

To configure the IAM role and policies:

1. Create an IAM role with a custom trust policy:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "TrustASAPPRole",
               "Effect": "Allow",
               "Principal": {
                   "AWS": "asapp-assuming-role-arn"
               },
               "Action": "sts:AssumeRole"
           }
       ]
   }
   
   

   Replace the asapp-assuming-role-arn placeholder with the value provided by ASAPP.

   If there are multiple ARNs to trust, create multiple statements with unique Sid values and ASAPP provided ARN values in each statement.

   Don’t immediately add permissions, instead you will add them after creation.

2. Add Kinesis Video Stream access to the IAM role by attaching the following permissions policy:

   Replace the customer-account-id with your AWS Account number and kinesis-video-streams-prefix with the value saved in the Configure your Amazon Connect Instance step.

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "ReadAmazonConnectStreams",
               "Effect": "Allow",
               "Action": [
                   "kinesisvideo:GetDataEndpoint",
                   "kinesisvideo:GetMedia",
                   "kinesisvideo:DescribeStream"
               ],
               "Resource": "arn:aws:kinesisvideo:*:customer-account-id:stream/kinesis-video-streams-prefix*/*"
           },
           {
               "Sid": "ListAllStreams",
               "Effect": "Allow",
               "Action": "kinesisvideo:ListStreams",
               "Resource": "*"
           }
       ]
   }
   

3. Add Lambda Function access by attaching the following permissions policy to the IAM role. This will allow the ASAPP service to invoke lambda functions:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "Stmt1",
               "Effect": "Allow",
               "Action": [
                   "lambda:InvokeFunction"
               ],
               "Resource": [
                   "lambda-pushaction-arn"
               ]
           }
       ]
   }
   

   Replace the lambda-pushaction-arn placeholder with the ARN of the PushAction lambda function.

4. Share the IAM role ARN with ASAPP

   ASAPP will use the ARN to interact with the PushAction lambda and Kinesis Video Streams.

​

Step 4: Add the GenerativeAgent Modules and Prompts

With the relevant components in place, you need to create or update a flow to use a GenerativeAgent Module to engage GenerativeAgent.

​

Upload the Prompts

The GenerativeAgent Modules uses specific prompts during the conversation. ASAPP will provide you with a set of .wav files to be added as prompts in your Amazon Connect Instance.

Prompt modules must be named exactly as the .wav files are named so that the GenerativeAgent Module works correctly.

​

Create GenerativeAgent Module

The GenerativeAgent Module will handle the conversation between the customer and GenerativeAgent.

You need to create the GenerativeAgent Module in your Amazon Connect Instance:

1. Receive the GenerativeAgent module json from ASAPP.

2. Edit the json to put in the correct ARNs.

   The Module will need to be updated with the correct ARNs to properly invoke the Engage and PushAction lambda functions.

   • Update the ARN that references the Engage lambda function to point to the Engage lambda function you created in Step 2.
   • Update the ARN that references the PushAction lambda function to point to the PushAction lambda function you created in Step 2.

3. Create a GenerativeAgent module.

   1. Within your Amazon Connect Instance, navigate to Routing > Flow > Modules.
   2. In the Modules section, click “Create flow module”.
   3. Expand the “Save” dropdown and select “Import”.
   4. Upload the edited JSON file and click “Import”.

​

Invoke the GenerativeAgent Module

To hand off a conversation to GenerativeAgent, you need to invoke the GenerativeAgent Module.

Most companies have many flows with nuanced logic and it is entirely up to you on when you engage the GenerativeAgent Module.

Once you have determined where within your flows you want to hand off a conversation to GenerativeAgent, you need to:

1. Set GenerativeAgent Parameter

   Create a “Set contact attributes” block and specify the ASAPP_CompanyMarker. This ASAPP_CompanyMarker is your company marker and must be passed to GenerativeAgent Module.

2. Invoke GenerativeAgent Module

   Create an “Invoke module” block and select the GenerativeAgent Module. This is where the conversation is handed off to GenerativeAgent.

   Within the GenerativeAgent module, the flow will use the various components you created in previous steps to engage ASAPP’s GenerativeAgent to the end user.

   Once the conversation is complete, GenerativeAgent will exit the module and return control to your flow.

3. Handle the result

   The GenerativeAgent module will exit for one of three reasons, and will be output the ASAPP_Disposition contact attribute with one of the following values:

   • transferToAgent: when the conversation needs to be transferred to an agent
   • disengage: when the conversation is completed
   • error: when an error has occurred

​

Step 5: Engage GenerativeAgent

Now you are ready to make a call and engage GenerativeAgent.

Call the phone number configured in your Contact Flow and follow the prompts until you reach the point where GenerativeAgent is engaged. You should see the conversation transition to GenerativeAgent based on where you placed the GenerativeAgent Module in your flow.

Verify that:

1. You are handed off to GenerativeAgent
2. GenerativeAgent responds appropriately to your inputs
3. You are returned to your flow when the conversation ends

​

Next Steps

Now that you have integrated GenerativeAgent with Amazon Connect, here are some important next steps to consider: