Amazon Connect Integration with Kore using Amazon External Voice Connector (Voice Automation)

This document outlines the steps for Kore users to integrate Kore Voice Automation with Amazon Connect, leveraging Amazon's external voice transfer capabilities. This setup enables voice transfers from Amazon Connect to a Voice Gateway and back, facilitating a seamless call experience through the Amazon Connect desktop.

Architecture Diagram

Prerequisites

• External voice transfer connectors per account with AWS Connect Instance enabled.
• A Kore voice AI Agent trained with few use cases.

Note

Amazon Connect external voice pricing is subject to change. Refer to the Amazon Connect External Voice Pricing Changes document for the latest information.

Setup Instructions

1. Enabling External Voice Transfer in Amazon Connect

Before setting up the integration, you must enable the "External voice systems" option in your Amazon Connect instance. Refer to Set up Amazon Connect external voice transfer to an on-premise voice system for more information.

• Service Quota Increase: Submit a Service Quota Increase request to Amazon Connect. This feature is enabled only after Amazon Connect approves your request.
• Accessing the Option: Once approved, the "External voice systems" option becomes visible in your Amazon Connect console.
  

2. Creating an External Voice Transfer Connector

After enabling the feature, create a connector under Voice transfer integrations to link Amazon Connect with your Voice Gateway.

• Navigate to Connector Creation: Click the External voice systems option to access the connector creation screen.
  

• Connector Configuration:

  • Name: Provide any desired name for the connector.
  • Connector destination type: Select audio code from the dropdown list.
  • Voice system type: Select one or multiple options; it does not affect the functionality.
  • Encryption: Select Disabled.
  • Logging: Select the option(s) to view the corresponding log in Connector Logs. It is recommended to select both the options.
• Host and Port Details: After creation, the connector configuration displays the IP address of the host, the protocol, and the port. This port should correspond to your Voice Gateway environment.
• The final configuration appears as shown in the following screenshot:
  

3. Configuring the Amazon Connect Flow

The next step involves modifying your Amazon Connect flow to utilize the newly created external voice connector.

• Add "Transfer to Phone Number" Node: Within your Amazon Connect flow, add a "Transfer to phone number" node.
  

• Select External Voice System: Instead of entering a phone number, select the External voice system option.

• Attach Connector: Attach the specific connector you created in the previous step.
• Enable "Resume flow after disconnect": Set this option to "Yes." This step ensures that after the call ends with the third-party system (Voice Gateway), the call is transferred back to Amazon Connect, facilitating a continuous flow and correlation between Amazon Connect and the Kore system.
  

4. Configuring Contact Center AI (Kore Side Configuration)

On Kore side, specific configurations are required in Contact Center AI (CCAI) to receive and manage calls transferred from Amazon Connect.

• Create New Configuration: In CCAI, create a new configuration (or use an existing one).
• Whitelist IP Address: The most critical step here is to whitelist the IP address provided by Amazon Connect. This IP address is essential for allowing communication from Amazon Connect to Kore. Check with Amazon Connect documentation or Support for the details on this IP address.

• DID Number: Provide the same Direct Inward Dialing (DID) number that will be used for the transfer (which was entered in the Transfer to phone number node in the previous step).
  

• Attach to Start Flow: Once the configuration is complete, attach this number to the relevant Experience Flow within Kore.
  

End-to-End Call Flow

The following steps describe the call flow after this integration:

1. A call originates in Amazon Connect by calling the Amazon Connect number.
   

   

2. The Amazon Connect flow transfers the call to Voice Gateway via the external voice connector.

3. Kore CCAI handles the call. You can view the details of the call in the CCAI Dashboard > Interactions section.
   

4. After interaction with Kore, the call is transferred back to Amazon Connect.
   

This setup provides a robust solution for leveraging Kore's voice automation capabilities within your Amazon Connect Contact Center environment.

Metadata Passing from Kore to Amazon Connect (Additional Feature)

Currently, Amazon Connect does not support SIP header extraction. To pass metadata from Kore to Amazon Connect, use the following alternative AWS components:

• API Gateway
• Lambda function
• DynamoDB Table
• CloudWatch (for debugging)

Architecture

1. Create a DynamoDB table with contactId (Amazon Connect Contact Id) as a partition key.
2. Create an API Gateway and invoke from outside AWS (via the Kore Dialogtask > Service Node, before agent transfer) to store data in the DynamoDB table.
3. To call this API, the Amazon Connect contact ID must be passed as one of the query parameters. This ID is retrieved from the SIP headers data sent from Amazon Connect to Kore.
4. Write two lambda functions—One for the API Gateway business logic and the other for its authentication.
5. In the Amazon Connect flow, invoke another lambda function to extract these metadata saved in DynamoDB in the last step.
6. These metadata values are then set as contact attributes within the flow.

Note

A total of three lambda functions are required for this use case.

AWS Side Configuration

Create a DynamoDB Table

Name: koreCcSessions

Partition Key: contactId

Create Three Lambda Functions

You must create three lambda functions for three different purposes. All these lambda function runtimes should be in:

Runtime: python.

The recommended lambda function name and the internal code is given in the following section.
Once you paste the lambda code, deploy the latest version of the code. Ensure your first and third lambda functions have DynamoDB full access. (You can add permissions inside the IAM role of the lambda function.)

1. koreStoreSessionMetadata: This lambda function is used to expose an API Gateway (Trigger) to get the metadata from Kore Platform and store it in the DynamoDB table. Copy and deploy the following code:

   import json
   import boto3
   dynamodb = boto3.resource('dynamodb')
   table = dynamodb.Table('koreCcSessions')
   # Ensure the table name matches your DynamoDB setup
   def lambda_handler(event, context):
   # Assume the third-party instance sends data in JSON format
   print('@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@Entered into the lambda for koreStoreSessionMetadata@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@')
   print('event', event);
   query_params = event.get('queryStringParameters')
   print('query_params', query_params)
   contactId=''
   if query_params:
   # Example: Access specific query parameters
   contactId = query_params.get('contactId')
   try:
   # Attempt to parse the input as JSON
   data = json.loads(event.get('body'))
   except (ValueError, TypeError):
   # If it's not JSON, return the input as is
   data = event.get('body', {})
   # Extract data from the incoming request
   print('contactId', contactId, type(contactId))
   print('data', data, type(data))
   # Store the data in DynamoDB
   table.put_item(
   Item={
   'contactId': contactId,
   'kore_session_data':data
   }
   )
   return {
   'statusCode': 200,
   'body': json.dumps('Data stored successfully')
   }
   

2. AuthenticateBeforeStoringInDynamoDB: This lambda function is used to add an authentication layer (Authoriser) on the API Gateway mentioned in the last lambda function (koreStoreSessionMetadata). Copy and deploy the following code:

   import json
   import os
   def lambda_handler(event, context):
   #1 - Log the event
   print('*********** The event is: ***************')
   print(event)
   token  = os.getenv('AUTH_TOKEN', 'abc123')  #Set AUTH_TOKEN value in the lambda environment variable, abc123 is the default value
   print('*********** The token is: ***************')
   print(token)
   #2 - See if the person's token is valid
   if event['authorizationToken'] == token:
   auth = 'Allow'
   else:
   auth = 'Deny'
   print(auth)
   #3 - Construct and return the response
   authResponse = { "context": {"stringKey": "value","numberKey": "1","booleanKey": "true"},"policyDocument": { "Version": "2012-10-17", "Statement": [{"Action": "execute-api:Invoke", "Resource": ["*"], "Effect": auth}] }}
   return authResponse
   

   Note

   Add “AUTH_TOKEN” as an Environment variable of lambda and enter your desired token value. This value needs to be the same as the Token validation value inside the API Gateway authorizer.

3. koreRetrieveSessionMetadata: This lambda is invoked in the Amazon Connect Contact Flow after the call gets disconnected from Kore and is handed over to Amazon Connect. This lambda returns all the metadata stored in the DynamoDB table using the first lambda. Copy and deploy the following code:

   import json
   import boto3
   dynamodb = boto3.resource('dynamodb')
   table = dynamodb.Table('koreCcSessions') 
   # Ensure the table name matches your DynamoDB setup
   def lambda_handler(event, context):
   
   # Assume Amazon Connect provides a primary key via Lambda input
   print('$$$$$$$$$$$$$$$$$$$$$$ Entered into retrieve session details lambda $$$$$$$$$$$$$$$$$$$$')
   print(json.dumps(event))
   contactId = event['Details']['Parameters']['contactId']
   print('contactId from contact flow',contactId)
   
   # Retrieve the data from DynamoDB
   response = table.get_item(
   Key={
   'contactId': contactId
   }
   )
   print("response", response)
   
   # Return the data in the format Amazon Connect expects
   if 'Item' in response:
   key = {
   'statusCode': 200,
   'body': json.dumps(response['Item']['kore_session_data'])
   }
   return key
   
   else:
   
   return {
           'statusCode': 404,
           'body': json.dumps('Data not found')
           }
   

Create an API Gateway

1. Create a REST API Gateway with the default configuration:
   

2. Create an API resource with the Resource path as “/kore-metadata.” Click Create resource:
   

3. Create an API Method with the following details:

   1. Method type: POST
   2. Integration type: Lambda function (koreStoreSessionMetadata)
   3. Turn on the Lambda proxy integration toggle.
   4. Select the lambda function (koreStoreSessionMetadata).
   5. Click Create Method.
      

4. The created method appears as shown in the following screenshot:
   

5. To enable authentication for this API Gateway, you need Authorizers. Create a new Authorizer with the following details:

   1. Authorizer name: koreClientAuth
   2. Authorizer type: Lambda
   3. Lambda function: AuthenticateBeforeStoringInDynamoDB
   4. Lambda Event Payload: Select Token
   5. Token source: authorizationToken
   6. Token validation - optional: Enter the value you want to use as Token for the API authentication. You need the same value to store in the Env Variable of AuthenticateBeforeStoringInDynamoDB Lambda function with the key as AUTH_TOKEN.

   7. Click Create authorizer.
      

      

6. Once the koreClientAuth Authorizer is created, add this as part of authentication for the API Resource and method you created.

   1. Click Edit method request.
   2. Under Authorization, select Token authorizers as koreClientAuth.
   3. Click Save.
      

7. Click Deploy API.
   

Modify the Contact Flow

Open the Amazon Connect instance and add the last lambda function (koreRetrieveSessionMetadata) inside the flow.

Modify the Amazon Connect flow:

• Add an AWS Lambda function node after the Transfer to phone number node.
• In the AWS Lambda function:
  • Select the Invoke Lambda function (koreRetrieveSessionMetadata), which was added in the last step.
  • Add a parameter:
    • Destination Key: contactId (enter this name)
    • Value: set dynamically
      • Namespace: System
      • Key: Contact id
  • Response Validation: JSON
  • Save the configuration.
• Add one Set contact attribute node. In this node:
  • Set attributes on: Current Contact
  • Add another attribute
    • Namespace: User defined
    • Key: customData
    • Value to be Set dynamically
      • Namespace: External
      • Key: body
  • Save the configuration.
• Connect all the nodes, and you can add a Play prompt node to understand if there is any error in the flow.
• Save and Publish the flow.

Note

You can also import the contact flow (.JSON file) from this link (right-click and save as .JSON).

Kore Side Configuration

In CCAI

• Start Flows

  1. Open Conditional Flow.

  2. Add the following code snippet in a Script node immediately after the Start node:

     setCallFlowVariable('sipHeaders', context.
     BotUserSession.channels[0].handle.sipHeaders);
     var headers = getCallFlowVariable
     ('sipHeaders'); userSessionUtils.
     put('sipHeaders', headers);
     

  3. Click Test to test the flow.
     

  4. Identify the Automation bot used in Conditional Flow. You will need it in the next step when configuring the Botbuilder.
     

• Agent Transfer

  1. Go to Settings > Integrations > Agent Transfer > Voice.
  2. Click SIP Transfer.
  3. Select SIP BYE from the SIP Transfer Method list.
  4. Click Save to save the configuration.

In Botbuilder

Ensure the Automation bot used in the CCAI Conditional Flow includes an Agent Transfer dialog task.

1. Open the Agent Transfer Dialog Task.

2. Add a Script node and paste the following code to extract contactId (Amazon Connect contact Id) from the SIP headers:

   try{ 
   var headers = context.session.UserSession.sipHeaders; 
   if(headers){ 
   var contactId = headers.find(o => o.name === 'X-Amzn-ConnectContactId'); 
   if(contactId){ 
   BotUserSession.put("ContactId", contactId.value); 
   } 
   } 
   }catch(err){
   koreDebugger.log("Error is:"+err);
   }
   

3. Add a Service node immediately after the Script node to make a REST API request to the API Gateway configured inside AWS in the earlier steps.
   

4. Click Define Request in the Service node.

Add the Request URL: Add the API Gateway URL with contactId as query parameter. Get this by accessing your first lambda function (“koreStoreSessionMetadata”) > Configuration > Trigger.

Example: https://ubpl0dxgq1.execute-api.us-east-1.amazonaws.com/dev/kore-metadata?contactId={{context.session.BotUserSession.ContactId}}

• Method: POST

• Headers:

  • Content-Type: application/json
  • authorizationToken: “abc123” (Add your token)
    

• Body:

  • Add your metadata
    Example:
    {"x_metadata":"Hello from Kore", "kore-instanceSessionId":"{{context.session.BotUserSession.lastMessage.messagePayload.instanceSessionId}}"}
    

    Note

    Pass the kore-instanceSessionId key and its value in the above specified format. This is required for the Agent AI widget to retrieve the user’s bot history. You may also include additional data, as needed.

    

  • Save the configuration.

  • Publish the bot.

Validate Your Metadata

When you call the Amazon Connect number, the call routes to Kore Automation and, after agent transfer, returns to the Amazon Connect desktop.

To view the metadata, check the Flow CloudWatch logs or use Contact Search:

1. Sign in to Amazon Connect.

2. Click Analytics and optimization > Contact search.
   

3. A list of conversations is displayed. You can also filter the results by contact ID.
   

4. When you open a contact’s details, the metadata appears as contact attributes.
   

Send Feedback