Amazon Connect

The Amazon Connect integration with ASAPP’s GenerativeAgent allows callers to have conversations with GenerativeAgent while maintaining the call entirely with in your Amazon Connect contact center.

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.

• Have a 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 Valkey
  • Create/manage VPC

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

  AWS Components

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

The components used in the example integration are intended for testing environments. 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 must be in the same VPC.

You can use an existing VPC or create a new one:

• To use an existing VPC: Verify it has at least two subnets in different Availability Zones, and that the subnets are private and isolated (not connected to the Internet).
• To create a new VPC: In the AWS Console, go to VPC > Your VPCs, click Create VPC, and follow the prompts to set up a VPC with at least two private isolated subnets in different Availability Zones.

​

Configure your Amazon Connect instance

To connect your Amazon Connect instance with an Amazon Kinesis Video Stream service, follow these steps:

1. Navigate to Live Media Storage

   • In the AWS Console, navigate to Amazon Connect and select your Amazon Connect instance by clicking on the Instance alias.
   • On the left menu, go to Data storage > Live Media Storage.

2. Enable Live Media Streaming

   • Under Data Storage options, enable Live Media Streaming.

3. Set Retention Period

   • Set a retention period of at least 1 hour.

4. Save the Kinesis Video Stream Instance Prefix

   • Copy the Kinesis video stream instance prefix; you will need this when you Configure IAM Roles and Policies.

​

Create security groups

You will need three security groups: one for Valkey ElastiCache, one for the PullAction Lambda function, and one for the PushAction Lambda function.

1. Create all three security groups

   • In the AWS Console, navigate to VPC > Security Groups.
   • For each of the following, click Create security group, using these names (or similar):
     • ValkeyElastiCacheSecurityGroup
     • PullActionLambdaSecurityGroup
     • PushActionLambdaSecurityGroup
   • Associate each security group with your VPC.
   • Save the security group IDs for later use.

2. Configure security group rules

   • Valkey ElastiCache security group:

     • Inbound rules:
       • Allow TCP traffic on port 6379 from the PullAction Lambda security group.
       • Allow TCP traffic on port 6379 from the PushAction Lambda security group.
     • Outbound rules:
       • No outbound rules are required. Remove any default outbound rules.

   • PullAction Lambda security group:

     • Outbound rules:
       • Allow TCP traffic on port 6379 to the Valkey ElastiCache security group.
       • Remove any other default outbound rules.

   • PushAction Lambda security group:

     • Outbound rules:
       • Allow TCP traffic on port 6379 to the Valkey ElastiCache security group.
       • Remove any other default outbound rules.

​

Create the Valkey ElastiCache

The Amazon Connect Flow uses ElastiCache (Valkey engine) to store ordered list of actions for each call. Follow these steps to create and configure your Valkey Cache in AWS ElastiCache:

1. Create a subnet group

   • In the AWS Console, navigate to ElastiCache > Subnet groups.
   • Click Create subnet group.
   • Enter a name and description for your subnet group (e.g., ValkeySubnetGroup).
   • Select your VPC.
   • Add both of your private isolated subnets (each in a different Availability Zone) to the group.
   • Save the subnet group.

2. Create a Valkey ElastiCache

   • In the AWS Console, navigate to ElastiCache.
   • In the left menu, select Valkey caches.
   • Click the Create cache button at the top right.

3. Configure Settings

   3.1 Configuration

   • Engine: Select Valkey.
   • Deployment option: Choose Design your own cache.
   • Creation method: Select Cluster cache.
   • Cluster mode: Set to Disabled.
   • Cluster info: Enter a name (e.g., asapp-generativeagent), up to 40 characters.
   • Location: Choose AWS Cloud.
   • Multi-AZ: Leave Enabled.

   3.2 Cache settings

   • Engine version, Port, Parameter groups: Leave default values.
   • Node type: For testing, select cache.t4g.micro. Adjust sizing based on your expected call volume before production.
   • Number of replicas: Set to 1.

   3.3. Connectivity

   • Subnet group: Choose the existing subnet group you created previously.

   3.4. Availability Zone placements

   • Availability Zone placements: Select No preference.

   Click Next to proceed to Advanced settings.

4. Configure Advanced Settings

   4.1 Security

   • Encryption at rest: Enable
   • Encryption in transit: Disable
   • Selected security groups: Click Manage and select the security groups created earlier in the Create security groups section.
   • Backups: Uncheck Enable automatic backups.
   • Maintenance: Leave default options.
   • Logs: Leave default options.

   Click Next to review your configuration.

5. Review and Create

   • Review all settings.
   • Click Create to provision your Valkey Cache.

   Once created, save the Primary endpoint—you will use this value as PRIMARY_VALKEY_HOST and PRIMARY_VALKEY_PORT when configuring your Lambda functions.

​

Step 2: Create Lambda functions to call GenerativeAgent

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

You will need to create the following Lambda functions:

• Engage
• PushAction
• PullAction

​

Engage Lambda Function

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

To create a Lambda function from the AWS Console:

​

PullAction Lambda Function

This Lambda function is called by the Amazon Connect Flow and queries Valkey for the next actions of a specific call.
The call identifier is the contactId taken from the Event.ContactData.

​

PushAction Lambda Function

ASAPP calls this Lambda function to communicate a further action for each call GenerativeAgent is engaging.
This function also pushes next actions into Valkey for PullAction to query at the next opportunity.

​

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 create an IAM role from the AWS Console:

{
    "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": "*"
        }
    ]
}

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

​

Step 4: Add Prompts and the GenerativeAgent Flow Module

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

​

Upload the Prompts

The GenerativeAgent Flow Module requires specific prompts during the conversation.

To upload the prompts:

1. Download the prompt files

   Download the required .wav prompt files from the following repository: Prompt audio files

   Copy

   Ask AI

     asappBeepBop.wav
     asappSilence1second.wav
     asappSilence400ms.wav
   

2. Upload and name each prompt in Amazon Connect

   In your Amazon Connect instance, navigate to Routing > Prompts.

   For each .wav file:

   • Click Add prompt.
   • Upload the file.
   • When prompted for the name, enter the file name without the .wav extension:
     Copy

     Ask AI

       asappBeepBop
       asappSilence1second
       asappSilence400ms
     

3. Save the prompt ARNs

   After uploading each prompt, save the ARN for each prompt.

   You will need these ARNs when editing the GenerativeAgent Flow Module JSON in the Create GenerativeAgent Flow Module section.

​

Create GenerativeAgent Flow Module

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

To create the GenerativeAgent Flow Module in your Amazon Connect instance:

1. Download the Module JSON

   • Download the ASAPPGenerativeAgent.json flow module json from the repository: ASAPP GenerativeAgent Flow Module

2. Edit the Module JSON Open the .json file and update the ARNs to reference your own Lambda functions:

   • Replace the ARN for the Engage Lambda function with the ARN you created in Step 2: Engage.
   • Replace the ARN for the PullAction Lambda function with the ARN you created in Step 2: PullAction.
   • Locate the section with "Identifier": "Wait1sPrompt" and, within its "Parameters", replace the "PromptId" string value with your asappSilence1second prompt ARN.
   • Locate the section with "Identifier": "Wait400msPrompt" and, within its "Parameters", replace the "PromptId" string value with your asappSilence400ms prompt ARN.
   • Locate the section with "Identifier": "PlayBeepBopShort" and, within its "Parameters", replace the "PromptId" string value with your asappBeepBop prompt ARN.

3. Import the Module

   • In your Amazon Connect instance, navigate to Routing > Flows > Modules.
   • Click Create flow module.
   • Expand the Save dropdown and select Import.
   • Upload your edited .json file and click Import.

4. Verify the Module

   • Ensure the imported module appears in your list and references the correct Lambda ARNs.

​

Invoke the GenerativeAgent Flow Module

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

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

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

​

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 Flow 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: