Access to your Amazon Connect instance with permissions to create Lambda functions, configure contact flows, and manage Identity and Access Management (IAM) roles.
Role required: sn_aia.admin
About this task
Connect your Amazon Connect contact center to a ServiceNow voice assistant using the Public Switched Telephone Network (PSTN) communication channel. When a call arrives, Amazon Connect invokes a Lambda function that retrieves a PSTN number from the ServiceNow Call Context API and transfers the call to the voice assistant. After the voice assistant handles the interaction, the Lambda function retrieves the interaction context and routes the call to a queue or ends the call.
Procedure
Navigate to All > Conversational Interfaces > Assistant Designer > Assistants.
Find the voice assistant that you want to connect to Amazon Connect and select Edit.
Select Communication channels from the guided setup navigation.
In the Provider application field, select the provider application to deploy the voice assistant to.
Select the Telephony provider tab.
From the Select communication channels dropdown, select Public Switched Telephone Network (PSTN).
From the CCaaS provider dropdown, select Amazon Connect.
The following read-only fields are generated in the Call context service section. Copy and save these values — you will need them to configure the integration on the Amazon Connect side.
Field
Description
Transfer method
Read-only. Set to BYE for Amazon Connect.
Call context API
Read-only. The URL that Amazon Connect uses to send call context data to the voice assistant. Copy this value for use as the call_context_api_path and voice_service_host_name Lambda environment variables.
Client ID
Read-only. Generated client ID for OAuth2 authentication. Copy this value for use in the AWS Parameter Store setup.
Client Secret
Read-only. Generated client secret for OAuth2 authentication. Copy this value for use in the AWS Parameter Store setup.
Image omitted: voice-agents-amazon-connect-integration.png Amazon Connect integration configuration showing the Transfer method, Call context API URL, Client ID, and Client Secret fields.
Also note the voice service `sys_id`, which you can find in the URL when viewing the voice service record. You will need this value in the Amazon Connect configuration steps.
Enable context data persistence for the voice service.
Navigate to sys_now_assist_deployment_config_attributes.list.
Filter the list to find the configuration attribute records for your voice service.
Locate the attribute named persist_context_data and change its value from false to true.
This setting allows the Lambda function to retrieve interaction context data from ServiceNow after the voice assistant completes the call.
Image omitted: voice-agents-amazon-connect-persist-context-data.png The persist\_context\_data configuration attribute record for the voice service with its value set to true.
In your AWS account, create the Lambda function that connects Amazon Connect to the voice assistant.
From the AWS console, create a new Lambda function.
In the Lambda function code editor, replace the default handler code with the Lambda function code.
Set the following environment variables on the Lambda function.
Variable
Value
`call_context_api_path`
The path portion of the ServiceNow call context URL — the part of the URL after `.com`.
`now_instance_host_name`
The ServiceNow instance URL, without the `https://` prefix.
`now_instance_name`
The name portion of your ServiceNow instance URL. For example, `myinstance`, not `myinstance.service-now.com`.
`ssm_oauth_path`
The base path for OAuth credentials in AWS Parameter Store: `/com.servicenow.cti//`. Set after completing the Parameter Store setup in the following steps.
`voice_service_host_name`
The hostname from the ServiceNow call context URL.
**Note:** Both `call_context_api_path` and `voice_service_host_name` are derived from the Call Context API URL in the voice service configuration. `voice_service_host_name` uses the hostname portion of that URL, and `call_context_api_path` uses the path portion after `.com`.
Image omitted: voice-agents-amazon-connect-lambda-env-vars.png The Lambda environment variables panel showing call\_context\_api\_path, now\_instance\_host\_name, now\_instance\_name, ssm\_oauth\_path, and voice\_service\_host\_name populated with example values.
4. Grant your Amazon Connect instance permission to invoke the Lambda function.
In the Amazon Connect console, navigate to your instance, select **Flows**, and under **AWS Lambda**, add the Lambda function with the Invoke Lambda use case. Confirm the policy was added in the Lambda console under **Configuration** > **Permissions**.
Image omitted: voice-agents-amazon-connect-lambda-permission.png The AWS Lambda section under Flows in the Amazon Connect instance, showing the Lambda functions dropdown and Invoke Lambda use case.
5. Replace the Lambda execution role permissions policy with the Identity and Access Management \(IAM\) policy.
See [Amazon Connect Lambda Identity and Access Management \(IAM\) policy](voice-agent-reference.md).
In the Lambda console, navigate to **Configuration** > **Permissions** > **Execution Role** and replace the existing permissions policy. Replace `<region>`, `<account-id>`, and `<lambda-function-name>` with your values.
6. Create a CloudWatch log group for the Lambda function.
In the AWS console, navigate to **CloudWatch** > **Log Management**. If no log group exists for your Lambda function, create one named `/aws/lambda/<your_Lambda_name>`.
7. Create the OAuth credentials in AWS Parameter Store.
From the AWS console, navigate to Parameter Store and create the following parameters using **SecureString** as the type.
Name
Value
`/com.servicenow.cti///client_id`Where `sn-instance-id` is the value of the `instance_id` system property \(to find this value, navigate to `sys_properties.list` and search for `instance_id`\), and `voice-service-id` is the voice service `sys_id`.
Client ID from the ServiceNow voice service configuration.
`/com.servicenow.cti///client_secret`Where `sn-instance-id` is the value of the `instance_id` system property \(to find this value, navigate to `sys_properties.list` and search for `instance_id`\), and `voice-service-id` is the voice service `sys_id`.
Client Secret from the ServiceNow voice service configuration.
Image omitted: voice-agents-amazon-connect-param-store.png AWS Parameter Store filtered to the /com.servicenow.cti/ path, showing the client\_id and client\_secret parameters created as SecureString type.
8. Add the AWS PowerTools layer to the Lambda function.
In the Lambda console, navigate to the Lambda function and select **Layers**. Add the AWS layer `AWSLambdaPowertoolsTypeScriptV2`, version 2.33.0 or later.
Import and configure the Amazon Connect contact flow.
In your Amazon Connect instance, create a new contact flow by importing the Voice AI inbound flow JSON.
In the Amazon Connect console, navigate to Routing > Flows, select Create flow, then use the import option. Replace all placeholder values with your own before importing.
In the first AWS Lambda function block of the contact flow, set the function ARN to the Lambda you created and set the voice_service_id input parameter to the sys_id of the voice service.
In the second AWS Lambda function block, set the function ARN to the same Lambda function.
Save and publish the contact flow.
Note: When Amazon Connect transfers the call to ServiceNow, the contact flow must pass the original caller's phone number as the caller ID. Verify that your contact flow is configured to preserve the original caller ID during the transfer, not the Amazon Connect transfer number.
Image omitted: voice-agents-amazon-connect-transfer-block.png The Transfer to phone number block configured with Transfer to set dynamically using the pstnNumber contact attribute, and Resume flow after disconnect set to Yes.
Associate a phone number with the contact flow.
In the Amazon Connect service dashboard, navigate to Channels > Phone numbers.
Claim a new number or select an existing number to associate with the contact flow.
Associating a phone number with the contact flow enables incoming calls to be routed through the voice assistant.
Result
Amazon Connect is connected to your ServiceNow voice assistant. Incoming calls routed through Amazon Connect are handled by the AI voice agent, which responds with a greeting and processes the caller's requests. When call handling is complete, the contact flow routes the caller to a queue or ends the call.
What to do next
Test the integration by placing a call through your Amazon Connect phone number and verifying that the voice assistant responds correctly. Review the CloudWatch logs for the Lambda function to troubleshoot any connection issues.