Invoke AWS Lambda functions
Amazon Connect can interact with your own systems and take different paths in contact flows dynamically. To achieve this, invoke AWS Lambda functions in a contact flow, fetch the results, and call your own services or interact with other AWS data stores or services. For more information, see the AWS Lambda Developer Guide.
To invoke a Lambda function from a contact flow, complete the following tasks.
Tasks
Create a Lambda function
Create a Lambda function, using any runtime, and configure it. For more information, see Create a Lambda Function in the AWS Lambda Developer Guide.
If you create the Lambda function in the same Region as your contact center, you can
use the Amazon Connect console to add the Lambda function to your instance as described
in the
next task, Add a Lambda function to your Amazon Connect
instance.
This automatically adds resource permissions that allow Amazon Connect to invoke the
Lambda
function. Otherwise, if the Lambda function is in a different Region, you can add
it to
your contact flow using the contact flow designer and add the resource permissions
using
the add-permission command, with a principal of
connect.amazonaws.com
and the ARN of your Amazon Connect instance. For more
information, see Using
Resource-Based Policies for AWS Lambda in the
AWS Lambda Developer Guide.
Add a Lambda function to your Amazon Connect instance
Before you can use an Lambda function in a contact flow, you need to add it to your Amazon Connect instance.
Add a Lambda function to your instance
-
Open the Amazon Connect console at https://console.aws.amazon.com/connect/
. -
Choose the name of the instance from the Instance Alias column.
-
In the navigation pane, choose Contact flows.
-
In the AWS Lambda section, use the Function drop-down box to select the function to add to your instance.
Tip The drop-down lists only those functions in the same Region as your instance. If no functions are listed, choose Create a new Lambda function, which opens the AWS Lambda console.
-
Choose Add Lambda Function. Confirm that the ARN of the function is added under Lambda Functions.
Now you can refer to that Lambda function in your contact flows.
Invoke a Lambda Function from a Contact Flow
To view a contact flow that invokes a Lambda function, see Sample Lambda integration.
-
Open or create a contact flow.
-
Add an Invoke AWS Lambda function block (in the Integrate group) to the grid. Connect the branches to and from the block.
-
Choose the title of the Invoke AWS Lambda function block to open its properties page.
-
Under Select a function, choose from the list of functions you've added to your instance.
-
(Optional) Under Function input parameters, choose Add a parameter. You can specify key-value pairs that are sent to the Lambda function when it is invoked. You can also specify a Timeout value for the function.
-
In Timeout (max 8 seconds), specify how long to wait for Lambda to time out. After this time, the contact routes down the Error branch.
For every Lambda function invocation from a contact flow, you pass a default set of information related to ongoing contact, as well as any additional attributes defined in the Function input parameters section for the Invoke AWS Lambda function block added.
The following is an example JSON request to a Lambda function:
{ "Details": { "ContactData": { "Attributes": {}, "Channel": "VOICE", "ContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX", "CustomerEndpoint": { "Address": "+1234567890", "Type": "TELEPHONE_NUMBER" }, "InitialContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX", "InitiationMethod": "INBOUND | OUTBOUND | TRANSFER | CALLBACK", "InstanceARN": "arn:aws:connect:
aws-region
:1234567890:instance/c8c0e68d-2200-4265-82c0-XXXXXXXXXX", "PreviousContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX", "Queue": { "ARN": "arn:aws:connect:eu-west-2:111111111111:instance/cccccccc-bbbb-dddd-eeee-ffffffffffff/queue/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "Name": "PasswordReset" }, "SystemEndpoint": { "Address": "+1234567890", "Type": "TELEPHONE_NUMBER" } }, "Parameters": { "sentAttributeKey": "sentAttributeValue" } }, "Name": "ContactFlowEvent" }
The request is divided into three parts:
-
Contact data—This is always passed by Amazon Connect for every contact. Some parameters are optional.
-
User attributes—These are attributes that have been previously associated with a contact, such as when using a Set contact attributes block in a contact flow. This map may be empty if there aren't any saved attributes.
-
Parameters—These are parameters specific to this call that were defined when you created the Lambda function.
Invocation retry policy
If your Lambda invocation in a contact flow gets throttled, the request will be retried. It will also be retried if a general service failure (500 error) happens.
When a synchronous invocation returns an error, Amazon Connect retries up to 3 times, for a maximum of 8 seconds. At that point, the flow will progress down the Error branch.
To learn more about how Lambda retries, see Error Handling and Automatic Retries in AWS Lambda.
Invoke multiple Lambda functions
Amazon Connect limits the duration of a sequence of Lambda functions to 20 seconds. It will error out when the total execution time exceeds this threshold. Since customers hear silence while a Lambda function executes, we recommend adding a Play prompt block between functions to keep them engaged and aware of the long interaction.
By breaking up a chain of Lambda functions with the Play prompt block, you will be able invoke multiple functions that last longer than the 20 second threshold.
Configure your Lambda function to parse the event
To successfully pass attributes between your Lambda function and Amazon Connect, configure
your
function to correctly parse the JSON request sent from the Invoke AWS Lambda
function block, and define any business logic that should be applied. How
the JSON is parsed depends on the runtime you use for your function. For example,
the
following example shows how to access sentAttributeKey
using
Node.JS:
var receivedAttribute = event['Details']['Parameters']['sentAttributeKey'];
Verify the function response
The Lambda function response should be a simple string map. This map can be up to
32k.
If you fail to reach Lambda, the function throws an exception, the response is not
understood, or the Lambda function takes more time than the limit, the contact flow
jumps
to the Error
label.
Test the output returned from your Lambda function to confirm that it will be correctly consumed when returned to Amazon Connect. The following example shows a sample response in Node.JS:
exports.handler = function(event, context, callback) { var resultMap = { Name:'CustomerName', Address:'1234 Main Road', CallerType:'Patient' } callback(null, resultMap); }
This example shows an example response using Python:
def lambda_handler(event, context): resultMap = {"Name":"CustomerName","Address":"1234 Main Road","CallerType":"Patient"} return resultMap
The output returned from the function must be a flat object of key/value pairs, with values that include only alphanumeric, dash, and underscore characters. Nested and complex objects are not supported. The size of the returned data must be less than 32 Kb of UTF-8 data.
The following example shows the JSON output from these Lambda functions:
{ "Name": "CustomerName", "Address": "1234 Main Road", "CallerType": "Patient" }
Consume the Lambda function response
There are two ways to use the function response in your contact flow. You can either directly reference the variables returned from Lambda, or store the values returned from the function as contact attributes and then reference the stored attributes. When you use an external reference to a response from a Lambda function, the reference will always receive the response from the most recently invoked function. To use the response from a function before a subsequent function is invoked, the response must be saved as a contact attribute, or passed as a parameter to the next function.
Access variables directly
If you access the variables directly, you can use them in contact flow blocks, but they are not included in contact trace records (CTR). To access these variables directly in a contact flow block, add the block after the Invoke AWS Lambda function block, and then reference the attributes as shown in the following example:
Name - $.External.Name
Address - $.External.Address
CallerType - $.External.CallerType
Make sure that the name specified for the source attribute matches the key name returned from Lambda.
Store variables as contact attributes
If you store the variables as contact attributes, you can use them throughout your contact flow, and they are included in CTRs.
To store the values returned as contact attributes and then reference them, use a
Set contact attributes block in your contact flow after the
Invoke AWS Lambda function block. Choose
External for the Type. Following the
example we're using, set Destination key to
returnedContactName
, and set the Source
attribute to Name
Add Address as a Source attribute and use
returnedContactAddress
as the Destination key.
Then add CallerType
as a Source attribute and use
returnedContactType
for the Destination
key.
Make sure that the name specified for the source attribute matches the key name returned from Lambda.