How to batch enroll callers in Amazon Connect Voice ID

Today, contact centers managers that are adopting Amazon Connect also have to migrate their existing business applications such as Contact Center Intelligence, Chat, Outbound Communications, and more to Amazon Connect. Additionally, if a contact center was using biometrics previously, contact center managers must re-enable that functionality on Amazon Connect using Voice ID to avoid any lapses in contact center security. This can be challenging, as migrating from one biometrics solution to another (including Amazon Connect Voice ID) requires re-enrolling all the callers once again. It is time-consuming for the contact center to wait for callers to call in to enroll, and it may be frustrating for callers to have to re-enroll again. Thus, this process is expensive, and can lead to a lapse in security until enrollments are completed. The batch enroll solution discussed in this blog makes it easier to migrate to Amazon Connect Voice ID.

Amazon Connect Voice ID offers powerful APIs to streamline the migration of the contact center customers into Voice ID, and to register fraudsters so that they can be quickly be flagged before they can do any damage. Voice ID’s batch migration APIs allow contact centers to bulk enroll up to a 100K callers using their call recordings in one single API transaction. This can help contact centers get a jump start on using Voice ID by authenticating callers when they call in the next time without waiting for them to enroll again.

In this blog, you will learn how to enroll your customers into Amazon Connect Voice ID using previously recorded call audio and how to use the batch API for enrollment.

Prerequisites

For the walkthrough you will need:

An AWS account
Access to AWS IAM to create policies and roles
The AWS Command Line Interface (AWS CLI) version 2
An existing Amazon Connect instance
Voice ID is enabled for your Amazon Connect Instance. You can enable Voice ID for your Amazon Connect Instance by following the steps outlined in the section entitled Get Started in the blogpost Machine learning-based voice authentication with Amazon Connect Voice ID

Setting up the solution

These instructions assume a working knowledge of Amazon Connect and AWS Command Line Interface. For details on how to perform basic administration tasks with these services, see the following:

Step 1: Create an input manifest file containing a list of speakers to be enrolled into Voice ID

Open any text editor, paste the below code showing an example input schema, update it with your list of speakers, and save that file with the “input-file.json” name.

{
    "Version": "1.0",
    "SpeakerEnrollmentRequests": [
        {
            "RequestId": "aSampleRequestId",
            "SpeakerId": "aSampleSpeakerId",
            "AudioSpecifications": [
                {
                    "S3Uri": "{S3 URI to a call audio recording that needs to be used for enrolling the speaker. AudioSpecifications: Currently, the maximum number of audio files allowed for an enrollment request is 10. Each file can be a .wav file up to 20MB, containing audio with 8KHz sample rate and PCM-16 encoding.}",
                    "ChannelId": 0
                }
            ]
        }
    ]
 }

Upload input-file.json to a S3 bucket

Step 2: Create an IAM Role for Voice ID to access the S3 buckets where the audio files are stored, input manifest file and write the job output file

Sign into your AWS Management Console and goto IAM
Choose Policies on the left navigation.
Choose Create policy on the top-right.

Choose JSON tab and paste the below content.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject"
            ],
            "Resource": "*"
        }
    ]
}

Choose Next: tags at bottom-right.
Choose Next: review at bottom-right.
Enter amazon-connect-voiceid-policy under the Name and choose Create policy at the bottom-right. Ignore the warning under Summary.
Choose Roles on the left navigation.
Choose Create role on the top-right.
Choose EC2 and choose Next: Permissions.
Enter amazon-connect-voiceid-policy under Filter policies and choose Next: Tags.
Optionally enter tags and choose Next: Review.
Enter “amazon-connect-voiceid-role” under the Role name and choose Create Role.
Enter “amazon-connect-voiceid-role” under the Role, you will see the new role that you just created.

Choose the role amazon-connect-voiceid-role, go to Trust relationships tab, choose Edit trust relationship, and paste the below content :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "voiceid.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Choose Update Trust Policy
See Batch enrollment using audio data from prior calls for more details on the permissions needed in this role.

Step 3: Start a new batch Speaker Enrollment Job using the AWS VoiceID CLI

Run the following aws cli command. See the StartSpeakerEnrollmentJob API Reference for more details about the inputs in the request.

aws voice-id start-speaker-enrollment-job \
    --region us-west-2 \ 
    --domain-id sampleDomainId \
    --input-data-config S3Uri={replace_with_S3_location_of_the_input_manifest_file_created_in_step_1_above e.g. s3://input-bucket/input_folder/input-file.json} \ 
    --output-data-config S3Uri={replace_with_S3_location_for_the_job_output_file e.g. s3://output-bucket/output-folder} \
    --data-access-role-arn {replace_with_arn_of_the_iam_role_created_in_step-2 e.g. arn:aws:iam::AWS_ACCOUNT_ID:role/amazon-connect-voiceid-role}

The previous start-speaker-enrollment-job command will return a JSON response describing the details of the submitted job, as follows. Initially, the JobStatus will be SUBMITTED.

{
    "Job": {
        "CreatedAt": 1632246415.566,
        "DataAccessRoleArn": "arn:aws:iam::AWS_ACCOUNT_ID:role/amazon-connect-voiceid-role",
        "DomainId": "sampleDomainId",
        "EnrollmentConfig": {
            "ExistingEnrollmentAction": "SKIP",
            "FraudDetectionConfig": {
                "FraudDetectionAction": "FAIL",
                "RiskThreshold": 20
            }
        },
        "InputDataConfig": {
            "S3Uri": "s3://input-bucket/input_folder/input-file.json"
        },
        "JobId": "sampleJobId",
        "JobStatus": "SUBMITTED",
        "OutputDataConfig": {
            "S3Uri": "s3://output-bucket/output-folder"
        }
    }
 }

You can check the status of the job after submitting it using the describe-speaker-enrollment-job as follows.

aws voice-id describe-speaker-enrollment-job \
    --domain-id sampleDomainId \
    --job-id sampleJobId \
    --region us-west-2

When the job is complete, the JobStatus will change to COMPLETE, as in the response below.

{
    "Job": {
        "CreatedAt": 1632246415.566,
        "DataAccessRoleArn": "arn:aws:iam::AWS_ACCOUNT_ID:role/amazon-connect-voiceid-role",
        "DomainId": "sampleDomainId",
        "EndedAt": 1632246647.605,
        "EnrollmentConfig": {
            "ExistingEnrollmentAction": "SKIP",
            "FraudDetectionConfig": {
                "FraudDetectionAction": "FAIL",
                "RiskThreshold": 20
            }
        },
        "InputDataConfig": {
            "S3Uri": "s3://input-bucket/input_folder/input-file.json"
        },
        "JobId": "sampleJobId",
        "JobProgress": {
            "PercentComplete": 100
        },
        "JobStatus": "COMPLETED",
        "OutputDataConfig": {
            "S3Uri": "s3://output-bucket/output-folder/sampleJobId/input-file.json.out"
        }
    }
 }

Once the job is COMPLETE, you can find the output file within your output S3 bucket. The full S3 URI path can be obtained from the OutputDataConfig of the describe-speaker-enrollment-job response. This output file will contain a list of successful and failed speaker enrollments. In our example input file, we had one speaker enrollment request, and hence the output file contains one successful and zero failed enrollments as below.
```
{
    "Errors": [],
    "SuccessfulEnrollments": [
        {
            "CustomerSpeakerId": "aSampleSpeakerId",
            "EnrollmentStatus": "NEW_ENROLLMENT",
            "GeneratedSpeakerId": "id#sampleGeneratedSpkerId",
            "RequestId": "aSampleRequestId"
        }
    ],
    "Version": "1.0"
 }
```

Step 4: Importing and configuring the contact flow into your Amazon Connect instance

Download a pre-built contact flow named Connect-VoiceID-Sample-Contact-Flow.
In Amazon Connect choose Routing, Contact flows.
On the Contact flows page, scroll down to the flows with name Connect-VoiceID-Sample-Contact-Flow
Edit the Set contact attributes block and set the Customer ID to the value of CustomerSpeakerId in the output file within your output S3 bucket. In our example output file, the CustomerSpeakerId is aSampleSpeakerId
You can now Save and Publish the contact flow
Now that a customer is enrolled into Amazon Connect Voice ID in step 3 above, you can call to check the authentication process.
Launch the CCP with the URL https://[instance_name].my.connect.aws/ccp-v2/or https://[instance_name].awsapps.com/connect/ccp-v2/ if you are using an older Amazon Connect instance. (replace instance_name with the name of your Amazon Connect instance).
Set the agent status to Available.
Call the phone number assigned to the Connect-VoiceID-Sample-Contact-Flow. When connected, you will interact with an IVR about the reason you are calling for. Amazon Connect Voice ID will use the audio collected during this conversation to verify your identity, based on the authentication threshold configured in the Set Voice ID block in your contact flow.
Once the call is transferred to an agent, accept the call on the CCP softphone interface
Once connected, the Voice ID status in the interface shows Authenticated after a successful authentication. If the score did not meet the threshold configured, which would happen if a different caller called in place of you, the status will display Not Authenticated. If there was insufficient audio, Inconclusive will be displayed.

Clean up

You can delete the Amazon Connect Voice ID domain. If you had created a new Amazon Connect Instance, you can delete the instance in the Amazon Connect service console.

Conclusion

In this post we demonstrated how to perform batch enrollment of customers in Amazon Connect Voice ID. We hope this helps streamline migration to Amazon Connect Voice ID. If you want to learn more about other Voice ID capabilities, check out the feature page.

AWS Contact Center