Amazon Connect

Learn how to integrate GenerativeAgent into 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.

Call transfers facilitate connecting users to GenerativeAgent via PSTN (dialing a number) while maintaining your control over the entire call duration.

This guide demonstrates how GenerativeAgent integrates with Amazon Connect using Call Transfer over PSTN.

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 Call Transfer over PSTN.
2. GenerativeAgent handles the conversation using Lambda functions to communicate with ASAPP’s APIs, and respond to the caller using a 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
4. Use Output Context of the call to determine the next course of action.

Detailed Flow

1. Incoming call: A customer calls your existing phone number in Amazon Connect.
2. Gather information: Your flow collects any details needed before the transfer, such as the task name or customer ID.
3. Request a number: The flow invokes the call-transfer Lambda function, which calls POST /call-transfers and returns a transferNumber.
4. Transfer the call: The flow transfers the call over PSTN to the ASAPP number.
5. GenerativeAgent handles the call: GenerativeAgent talks with the customer and works through their request.
6. Call returns: The call with GenerativeAgent ends, and control returns to your flow.
7. Get output context: The flow invokes the get-call-context Lambda function, which calls GET /call-transfers/{id} and returns the outputContext.
8. Check the transfer type: The flow branches on transferType, which is one of SYSTEM, AGENT, DISCONNECT, or INTERNAL_ERROR.
9. Handle the call: The flow takes the next step based on the outcome, such as routing to the IVR or a human agent queue.

The red F1, F2, and F3 markers show where the flow can fail and send the call to fallback handling. See Handling failures.

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.

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

  AWS Components

  You will set up and configure the following AWS services:

  • Amazon Connect - Handles call flow and audio streaming
  • Lambda functions - These functions will handle communication between Amazon Connect and GenerativeAgent

• Enable Call Transfer over PSTN by contacting your ASAPP account team.

Configuring Amazon Connect with GenerativeAgent

Step 1: Create Lambda Functions

Lambda functions are used to interact with ASAPP’s GenerativeAgent APIs to create call transfers and retrieve call context. They can be created using the AWS Console or AWS API.

To create a Lambda function in AWS Console:

1. Log in to the AWS Management Console.

2. Open Lambda.

3. Select Author from scratch and fill in the required fields:

   Basic Information

   • Function name: call-transfer or ‘get-call-context ’
   • Runtime: Select Node.js 22.x
   • Architecture: Select x86_64

   Execution Role

   • Under Change default execution role, select “Create a new role with basic Lambda permissions”. This option automatically adds the necessary permissions for basic Lambda execution and CloudWatch logging.
   • CloudWatch logging is required for debugging and monitoring Lambda executions, so ensure these permissions are included.
   • If you are creating the Lambda function using infrastructure-as-code tools (such as Terraform), you must ensure the following permissions are included in the execution role:
     • Allow logs:CreateLogStream and logs:PutLogEvents for all streams under your CloudWatch Log Group.
     • Allow lambda:InvokeFunction action in your resource base policy.
     • List connect.amazonaws.com as the Principal Service in your resource policy.

   After filling in the required fields, click Create function.

4. In the Function Overview section, look for ARN and save it.

5. Go to the Code tab, click upload from and select .zip file to upload your Lambda function code. Click Deploy.

6. Go to the Configuration tab, select Environment variables, and add the following environment variables:

   Variable	Description
   ASAPP_API_ID	API Credential provided by ASAPP.
   ASAPP_API_SECRET	API Credential provided by ASAPP.
   ASAPP_API_HOST	API hostname provided by ASAPP, usually api.asapp.com

7. Click Save.

Sample Lambda function code to create Call Transfer

const ASAPP_API_ID = process.env.ASAPP_API_ID;
const ASAPP_API_SECRET = process.env.ASAPP_API_SECRET;
const ASAPP_API_HOST = process.env.ASAPP_API_HOST;

export const handler = async function (event) {

   console.log("Received event:", JSON.stringify(event, null, 2));
   let contactId = event.Details?.ContactData?.ContactId;
   if (!contactId) {
       console.error("ContactId not found in event");
       return { result: "error", error: "ContactId not found in event", transferNumber: "" }
   }

   let taskName;
   if (event.Details?.Parameters?.taskName) taskName = event.Details.Parameters.taskName;

   let customerId = event.Details?.ContactData?.CustomerEndpoint?.Address;
   if (event.Details?.Parameters?.customerId) customerId = event.Details.Parameters.customerId;

   let requestBody = {
       id: contactId,
       externalConversationId: contactId,
       type: "PHONE_NUMBER",
       phoneNumber: {
           country: "US"
       },
       inputContext: {
           inputVariables: {}
       }
   };

   if (taskName) requestBody.inputContext.taskName = taskName;
   if (customerId) requestBody.inputContext.inputVariables.customerId = customerId;

   for (const [key, value] of Object.entries(event.Details.Parameters)) {
       if (key !== "taskName" && key !== "customerId") {
           requestBody.inputContext.inputVariables[key] = value;
       }
   }

   let response;
   try {
       response = await fetch(`https://${ASAPP_API_HOST}/generativeagent/v1/call-transfers`, {
           method: "POST",
           headers: {
               "Content-Type": "application/json",
               "asapp-api-id": ASAPP_API_ID,
               "asapp-api-secret": ASAPP_API_SECRET
           },
           body: JSON.stringify(requestBody)
       });
   } catch (error) {
       console.error("Error calling ASAPP API:", error);
       return { result: "error", error: error.message, transferNumber: "" }
   }

   if (!response.ok) {
       let responseText = await response.text();
       console.error("Error calling ASAPP API:", response.statusText,responseText);


       return { result: "error", error: response.statusText, transferNumber: "" }
   }

   const responseData = await response.json();
   console.log("ASAPP API response:", responseData);
   let transferNumber = responseData.phoneNumber?.transferNumber;
   if (!transferNumber) {
       console.error("Transfer number not found in ASAPP API response");
       return { result: "error", error: "Transfer number not found in ASAPP API response", transferNumber: "" }
   }
   return { result: "ok", transferNumber: transferNumber, expireAt: responseData.phoneNumber?.expireAt }
};

Parameters:

Parameter	Description
taskName	(Optional) The name of the GenerativeAgent task to be initiated in the initial Connections.
customerId	The unique identifier for the customer. If not provided, the calling number of the caller will be used as the customerId. Ensure the value is unique and consistent for each customer to avoid integration issues.

Response:

Field	Type	Description
result	string	”ok” if the call transfer was created successfully, “error” otherwise.
error	string	Error message if the call transfer failed.
transferNumber	string	A E.164 formatted PSTN number assigned to transfer the call by ASAPP.
expireAt	string	The time the transferNumber expires, by default 1 minute after it is issued. Complete the transfer before this time.

Sample Lambda function code to retrieve Call Context

const ASAPP_API_ID = process.env.ASAPP_API_ID;
const ASAPP_API_SECRET = process.env.ASAPP_API_SECRET;
const ASAPP_API_HOST = process.env.ASAPP_API_HOST;      

export const handler = async function (event) {
   console.log("Received event:", JSON.stringify(event, null, 2));
   let contactId = event.Details?.ContactData?.ContactId;
   if (!contactId) {
       console.error("ContactId not found in event");
       return { result: "error", error: "ContactId not found in event", outputContext: {} }
   }


   let response;
   try {
       response = await fetch(`https://${ASAPP_API_HOST}/generativeagent/v1/call-transfers/${contactId}`, {
           method: "GET",
           headers: {
               "asapp-api-id": ASAPP_API_ID,
               "asapp-api-secret": ASAPP_API_SECRET
           }
       });
   } catch (error) {
       console.error("Error calling ASAPP API:", error);
       return { result: "error", error: error.message, outputContext: {} }
   }




   if (!response.ok) {
       console.error("Error calling ASAPP API:", response.statusText);
       return { result: "error", error: response.statusText, outputContext: {} }
   }


   const responseData = await response.json();
   console.log("ASAPP API response:", responseData);
   if (!responseData.outputContext) {
       console.error("Output context not found in ASAPP API response");
       return { result: "error", error: "Output context not found in ASAPP API response", outputContext: {} }
   }


   return { result: "ok", outputContext: responseData.outputContext }
};

Parameters:

Parameter	Description
contactId	The unique identifier for the contact. This is typically the ContactId from the Amazon Connect event.

Response:

Field	Type	Description
result	string	”ok” if the call context was retrieved successfully, “error” otherwise. On “Ok” response, it includes the Call Transfer Data.
outputContext	object	The output context of the call, which includes the conversation

Call Transfer Data

Field	Type	Description
ID	string	The unique identifier for the call transfer. This is typically the Transfer ID.
externalConversationId	string	The external conversation ID associated with the call transfer.
status	string	The status of the call transfer, e.g., “COMPLETED”.
createdAt	string	The timestamp when the call transfer was created.
callReceivedAt	string	The timestamp when the call was received.
completedAt	string	The timestamp when the call transfer was completed.
inputContext	object	The input context for the call transfer, which includes variables such as taskName and inputVariables.
inputContext.taskName	string	The name of the task being handled by GenerativeAgent.
inputContext.inputVariables	object	Key-value pairs of input variables used in the conversation.
inputContext.inputVariables.name	string	The unique identifier for the customer.
type	string	The type of transfer, which is “PHONE_NUMBER” for this integration.
phoneNumber	object	The phone number details for the transfer.
phoneNumber.country	string	The country code for the phone number, e.g., “US”.
phoneNumber.transferNumber	string	The E.164 formatted PSTN number assigned to transfer the call by ASAPP.

Status

Status	Description
ACTIVE	The call transfer is currently active and the temporary number is waiting to be connected.
ONGOING	The call transfer is in progress and the GenerativeAgent is still handling the call.
COMPLETED	The call transfer has been completed successfully.
EXPIRED	The call transfer has expired and the temporary number is no longer valid.

Output Context

Field	Type	Description
transferType	string	How the call ended and what your flow should do next. One of SYSTEM, AGENT, DISCONNECT, or INTERNAL_ERROR. See the Handle Call Context step for how to branch on each value.
currentTaskName	string	The name of the current task being handled by GenerativeAgent.
referenceVariables	object	Key-value pairs of reference variables used in the conversation.
transferVariables	object	Key-value pairs of transfer variables used in the conversation.

You can have the metrics, logging, redundancy, warm starts, and other settings configured as per your specific requirements, environment, and uses cases.

Step 2: Add your Lambda Functions to your Amazon Connect instance

The Lambda function must be added to your Amazon Connect instance to be used in the contact flow. To do this:

1. Open the Amazon Connect console.
2. Select your Amazon Connect instance.
3. In the left navigation pane, choose Contact flows.
4. Choose AWS Lambda functions from the dropdown menu.
5. Click Add Lambda function.
6. Select the Lambda function call-transfer you created earlier.
7. Click Add.
8. Repeat the process for the get-call-context Lambda function.

Step 3: Set Up Flow in Amazon Connect

1. Create Call Transfer Record

   To createa a Call Transfer record in your Amazon Connect contact flow, you need to reference the call-transfer Lambda function:

   1. In the Amazon Connect console, open your contact flow.
   2. Add an Invoke AWS Lambda function block at the point where you want to initiate the transfer.
   3. Select the call-transfer Lambda function.
   4. Map any required parameters (such as taskName or customerId) in the block’s configuration.
   5. Use the output variable transferNumber from the Lambda function as the destination number in a Transfer to phone number block.
   6. Connect the block’s Error branch to your fallback path. This is failure point F1, see Handling failures.
   7. Connect the blocks to complete the flow.

   The transferNumber expires after a set period, by default 1 minute. Complete the Transfer to phone number block before the expireAt time returned by the API. Once the number expires it is released and can be reassigned to a subsequent call transfer.

2. Transfer Call to GenerativeAgent

   1. Go to “Transfer to phone number” block and navigate to the Properties panel.
   2. Set the Transfer Via to “Phone number”.
   3. Under Phone number, select Set Dynamically.
   4. The Namespace must be set to External.
   5. The Key must be set to transferNumber.
   6. Set Resume Flow after Disconnect to Yes.
   7. Connect the block’s Error branch to your fallback path. This is failure point F2.
   8. Connect the output of this block to the next step in your flow.

   Resume Flow after Disconnect resumes your flow whichever side ends the call, whether GenerativeAgent handed the call back cleanly or the caller hung up. Your flow cannot tell these apart until the get-call-context step runs, so do not treat flow resumption on its own as a successful handoff.

3. Retrieve Call Context After Transfer Back

   1. Add another Invoke AWS Lambda function block after the transfer block.
   2. Select the get-call-context Lambda function.
   3. Map the ContactId from the Amazon Connect flow to the Lambda function input.
   4. Use the output variable outputContext from the Lambda function to determine the next steps.
   5. Connect the block’s Error branch to your fallback path. This is failure point F3.
   6. Connect the output of this block to the next step in your flow.
4. Handle Call Context

   1. Use the output context from the get-call-context Lambda function to determine the next steps in your flow.

   2. Based on the following fields in the output context, you can decide how to proceed:

      • Transfer Type: Indicates how the call ended and what you should do next. Branch your contact flow on all four possible values, not only AGENT and SYSTEM.
      • Current Task Name: If it matches a specific task, you can route the call accordingly.
      • Reference Variables: Use these variables to provide additional context or information to the customer.
      • Transfer Variables: Use these variables to handle any specific transfer logic.

      Transfer Type	Description	What to do in your flow
      SYSTEM	GenerativeAgent explicitly executed a transfer-to-system action.	Transfer Variables are populated. Use them to drive the next step in the flow, such as routing back to the IVR.
      AGENT	GenerativeAgent ran out of options and is handing the call back.	Transfer the call to a human agent queue.
      DISCONNECT	The caller hung up before GenerativeAgent finished.	Reference Variables may still be populated, but do not expect Transfer Variables. No one is left on the line to route further.
      INTERNAL_ERROR	GenerativeAgent or an upstream ASAPP component errored.	Treat as unrecoverable for this call. Route to your IVR default or a human agent rather than retrying the same flow path.

   Do not build flow branching that only checks for AGENT against SYSTEM. An unhandled DISCONNECT or INTERNAL_ERROR value falls through to whatever your flow’s default path is, which may not be the right one.

Handling failures

A call can fail at three distinct points in the flow. Handle them separately, because they surface in different places and call for different fallbacks. A single generic error path leaves it ambiguous which Lambda’s failure is being handled.

1. The call-transfer Lambda invocation fails

   An AWS-side error, a timeout, or a missing transferNumber in the response. The Lambda returns result of "error" with an empty transferNumber.

   Catch this on the Invoke AWS Lambda function block’s own error branch, before your flow ever attempts the phone transfer. There is no conversation to retrieve context for, so route straight to your fallback path.

2. The get-call-context Lambda invocation fails

   An AWS-side error, a timeout, or a missing outputContext in the response. The Lambda returns result of "error" with an empty outputContext.

   Catch this on that block’s own error branch. The conversation itself may have gone fine, but your flow has no way to read the outcome, so do not assume success. Route to your fallback path rather than letting an empty outputContext fall through your transferType branching.

3. The PSTN call transfer completes with a non-success outcome

   A status of EXPIRED, or a transferType of DISCONNECT or INTERNAL_ERROR.

   This is only visible after get-call-context runs, so it needs its own branching as described in the Handle Call Context step.

   Treat EXPIRED as a failure that requires invoking the call-transfer Lambda again for a fresh number. Retrying the same transferNumber will not work, because the expired number has already been released.

Handling customer reconnections

There may be scenarios where you want to reconnect a customer to where they left off with GenerativeAgent, for example after the caller hangs up or after a transfer back to your flow.

To resume the conversation instead of starting a new one, invoke the call-transfer Lambda again using the same externalConversationId. GenerativeAgent resumes the conversation where it left off.

In the sample Lambda code, externalConversationId is set to the Amazon Connect ContactId. A ContactId is specific to a single contact, so reconnecting a customer across contacts requires passing a stable identifier of your own instead. Use any identifier that stays consistent for the customer across the reconnection.

Next Steps

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

Configuration Overview

Learn how to configure GenerativeAgent’s behaviors, tasks, and communication style

Connect your APIs

Configure your APIs to allow GenerativeAgent to access necessary data and perform actions

Review Knowledge Base

Connect and optimize your knowledge base to improve GenerativeAgent’s responses

Go Live

Follow the deployment checklist to launch GenerativeAgent in your production environment