IVR¶
das-Peak Streaming Genesys Cloud IVR based solution is built as a Genesys Cloud Blueprint. This Blueprint includes all information to deploy required resources to create an integration with das-Peak Streaming within a customer Genesys Cloud environment.
das-Peak Streaming Genesys Cloud Blueprint allows customer to use voice registration/verification through newly created or existing Genesys Cloud IVRs (flows). It automatically creates and deploys resources (common module flows, integrations, actions) within customer Genesys Cloud platform. These resources can be used in any inbound/outbound flow to add real time voice authentication.
Following diagram describes das-Peak Streaming Genesys Cloud Blueprint architecture.
Solution components¶
- Genesys Cloud - A suite of Genesys cloud services for enterprise-grade communications, collaboration, and contact center management. Genesys Cloud is the platform where you can access the Lex-Kendra chatbot solution.
- Architect - The Genesys Cloud easy-to-learn drag and drop web-based design tool that creates flows.
- Common module flow - An Architect flow type which allows customers to build logic once and then reuse it in multiple flows.
- Data Actions - Genesys Cloud Integration that allows customers to make HTTP/S REST requests against a service API.
- AudioHook - A mechanism and generic protocol to provide a real-time stream of voice interactions from the Genesys Cloud platform to any third-party service endpoint. Check protocol specification.
- Cx as Code - A tool to declaratively manage Genesys Cloud resources and configuration across organizations using Terraform By HashiCorp.
- Terraform - An infrastructure as code tool that lets users define both cloud and on-prem resources in human-readable configuration files that they can version, reuse, and share.
- das-Peak Streaming - Veridas service meant to cover registration and authentication of subjects in real-time scenarios. Check service documentation.
- das-Peak - Veridas voice biometrics engine. Check service documentation.
Use case scenario¶
This Blueprint allows Genesys Cloud customers to integrate with das-Peak Streaming. das-Peak Streaming covers registration and authentication of subjects in real-time scenarios. das-Peak Streaming exposes a public API that can be consumed by any user.
In a Genesys Cloud environment, das-Peak Streaming integration is not simple, since integrators need to deeply know Genesys Cloud developer environment in order to make calls to das-Peak Streaming API. Thus, "Veridas das-Peak Streaming Blueprint" make things easier and allow customers to add voice verification within their own Genesys Cloud flows with a few simple steps.
Veridas das-Peak Streaming Blueprint deploys all required resources in the customer Genesys Cloud environment directly so integration is staightforward.
Prerequisites¶
Following prerequisites must be fulfilled:
- Install version 1.4.x of Terraform
- Get familiar with CX as Code. To know how it is used and what Cx as Code is for, the documentation that is on the Terraform page about Cx as Code with Gensys Cloud can be reviewed.
Implementation steps¶
- Get OAuth credentials
- Get das-Peak Streaming access links and credentials
- Download the repository
- Modify the environment file
- Running Terraform project with Cx as Code
Get OAuth credentials¶
An OAuth client is required by the Blueprint in order to have permissions to deploy all required resources in customer Genesys Cloud environment.
To obtain an OAuth client, follow official Genesys Cloud documentation. Take into account that the type of credential that must be created is Client Credentials. Once it is created, client id and client secret must be stored for later use.
account region value is also required. Check this link for a list of Genesys Cloud allowed regions.
Get das-Peak Streaming access links and credentials¶
Contact with Veridas to get valid access links and credentials.
Download the repository¶
Download the repository on your work computer or contact with Veridas to get required files and scripts.
Modify the environment file¶
The terraform.tfvars file is located in the src directory. Following fields are defined:
| Environment | Value |
|---|---|
| genesyscloud_client_id | Client ID of the OAuth client created in customer's Genesys Cloud organization. |
| genesyscloud_client_secret | Client Secret of the OAuth client created in customer's Genesys Cloud organization. |
| genesyscloud_region | The region is obtained when Genesys Cloud creates the account. Check available regions. |
| daspeak_streaming_signalling_url | das-Peak Streaming Signalling Channel URL. (provided by Veridas) |
| daspeak_streaming_apikey | API Key to use das-Peak Streaming Signalling Channel. (provided by Veridas) |
| daspeak_streaming_audio_settings_id | Identifier that is associated with the Genesys Cloud's audio configuration.* |
| daspeak_streaming_audiohook_url | das-Peak Streaming audiohook server URL. (provided by Veridas) |
| daspeak_streaming_model_hash | Biometric model hash used by das-Peak Streaming. (provided by Veridas) |
This file must be modified with suitable values.
*daspeak_streaming_audio_settings_id parameter can be obtained by creating an audio_settings resource in das-Peak Streaming. This can be done by using das-Peak Streaming REST API /audio_settings endpoint. Following CURL request creates an audio_settings resource in das-Peak Streaming for a Genesys Cloud Audiohook connection. daspeak_streaming_audio_settings_id can be found as a v4 UUID within the response id parameter.
curl --location --request POST 'DASPEAK_STREAMING_SIGNALLING_URL/audio_settings' \
--header 'apikey: DASPEAK_STREAMING_APIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"audio_protocol": "audiohook",
"audio_format": "raw",
"audio_codec": "mulaw",
"sample_format": "",
"sample_rate": 8000,
"channels": 1
}'
# Response
{"audio_codec":"mulaw","audio_format":"raw","audio_protocol":"audiohook","channels":1,"created_at":"Tue, 31 Oct 2023 10:29:54 GMT","id":"090650af-15bc-42ec-a870-10b5342fa4f5","sample_format":"","sample_rate":8000}
Running Terraform project with Cx as Code¶
Once the corresponding variables are configured, required resources can be deployed in Genesys Cloud to be able to use das-Peak Streaming voice authentication in any IVR (flow).
To initialize the project and download necessary plugins:
terraform init
To preview the changes that will be made into Genesys Cloud environment:
terraform plan -var-file terraform.tfvars
To create/modify resources in Genesys Cloud environment:
terraform apply -var-file terraform.tfvars --auto-approve
To destroy the created resources and restore default settings:
terraform destroy
Explanation of created resources¶
Once Terraform code is executed with CX as Code, following resources will be generated into customer's Genesys Cloud account:
- Integrations
- AudioHook: Audiohook integration named Veridas Audiohook that allows Genesys Cloud to send audio from Genesys Cloud to das-Peak Streaming AudioHook server.
- Genesys Cloud Data Actions: Data Actions Integration named Veridas Data Actions that contains all created data actions.
- Actions
- Create Register Session: This data action creates a Register Session in das-Peak Streaming.
- Create Verify Session: This data action creates a Verify Session in das-Peak Streaming.
- Get Register Session: This data action retrieves the status of a Register Session from das-Peak Streaming.
- Get Verify Session: This data action retrieves the status of a Verify Session from das-Peak Streaming.
- Architect Common Modules
- Get Register Result Veridas: This module retrieves the status of a Register Session from das-Peak Streaming by using "Get Register Session" data action.
- Get Verify Result Veridas: This module retrieves the status of a Verify Session from das-Peak Streaming by using "Get Verify Session" data action.
- Start Register Streaming Veridas: This module creates a Register Session in das-Peak Streaming by using "Create Register Session" data action.
- Start Verify Streaming Veridas: This module creates a Verify Session in das-Peak Streaming by using "Create Verify Session" data action.
Usage¶
Genesys Cloud account administrators can use created Common Modules to add voice registration/verification to Architect IVRs (flows). In this section, it will be shown how.
Registration process¶
For a newly created or existing flow, the following steps must be followed in order to add registration inside a flow:
Step1: Add "Start Register Streaming Veridas" Common Module¶
Firstly, a Call Common Module action must be added to the flow. The Common Module to be called by this action is Start Register Streaming Veridas (latest version). This Common Module will create a Register Session in das-Peak Streaming and will start sending audio via Audiohook created integration.
Parameters defined for Start Register Streaming Veridas Common Module are:
| Direction | Parameter | Description | Type | Allowed values | Required |
|---|---|---|---|---|---|
| Input | audio_total_duration | Minimum amount of seconds of speech required to process the audio | Decimal | [3.0, 30.0] | ✓ |
| Input | authenticity_threshold | Authenticity threshold required for the process to succeed | Decimal | [0.0, 1.0] | ✓ |
| Input | call_id | Identifier for the current call | String | Call.ConversationId |
✓ |
| Output | error_msg | Error detailed message | String | any | |
| Output | register_session_id | Identifier of the created Session | String | any | |
| Output | result | Result of the flow | String | success, error |
result parameter will specify if the action was successful or not. Also, Register Session identifier will be available via register_session_id parameter. This identifier should be used to get status of Register Session.
Step2: Get client speech¶
Upon successful result (Register Session created), client audio will be recorded from this point. Thus, IVR administrator should guarantee user speech is acquired. This can be done by asking questions to user or by any alternative method. This process is delegated to the IVR administrator.
Step3: Add "Get Register Result Veridas" Common Module¶
After Register Session has been created and enough audio has been collected, a new Call Common Module action must be added to the flow. The Common Module to be called by this action is Get Register Result Veridas (latest version). This Common Module will call das-Peak Streaming to get the status of a Register Session.
Parameters defined for Get Register Result Veridas Common Module are:
| Direction | Parameter | Description | Type | Allowed values | Required |
|---|---|---|---|---|---|
| Input | register_session_id | Identifier of requested Session | String | any | ✓ |
| Output | audio_seconds | Seconds of speech collected (audio without silences) so far when result is 'processing' | Decimal | [0.0, 30.0] | |
| Output | authenticity | Authenticity score of credential obtained | Decimal | [0.0, 1.0] | |
| Output | credential | Voiceprint generated from the audio stream | String | any | |
| Output | error_msg | Error detailed message | String | any | |
| Output | result | Result of the flow | String | success, spoof, processing, error | |
| Output | vad_percentage | The percentage that represents the amount of speech collected compared to the amount of speech audio requested to be collected when result is 'processing' | Decimal | [0.0, 100.0] | |
| Output | voice_audio_collected | Seconds of speech collected (audio without silences) | Decimal | [0.0, 30.0] |
register_session_id parameter must be equal to the one that was previously obtained by calling "Start Register Streaming Veridas" Common Module. This way, previously created Register Session status is obtained.
result parameter will specify the status of the Register Session:
- success: Register Session status is SUCCESS, meaning a valid credential was created.
- spoof: Register Session status is FAIL_SPOOF, meaning recorded voice was tagged as not authentic.
- processing: Register Session status is PROCESSING_AUDIO, meaning audio is still being processed by das-Peak Streaming.
- error: Register Session status is ERROR, meaning an error occured during registration process.
If result is "processing", IVR administrator should ensure to get more audio from user and call Get Register Result Veridas Common Module again afterwards.
If result is "success" or "spoof", biometric credential will be available via credential parameter. IVR administrator should store generated credential for later verifications if required.
Verification process¶
For a newly created or existing flow, the following steps must be followed in order to add verification inside a flow:
Step1: Add "Start Verify Streaming Veridas" Common Module¶
Firstly, a Call Common Module action must be added to the flow. The Common Module to be called by this action is Start Verify Streaming Veridas (latest version). This Common Module will create a Verify Session in das-Peak Streaming and will start sending audio via Audiohook created integration.
Parameters defined for Start Verify Streaming Veridas Common Module are:
| Direction | Parameter | Description | Type | Allowed values | Required |
|---|---|---|---|---|---|
| Input | audio_total_duration | Minimum amount of seconds of speech required to process the audio | Decimal | [3.0, 30.0] | ✓ |
| Input | authenticity_threshold | Authenticity threshold required for the process to succeed | Decimal | [0.0, 1.0] | ✓ |
| Input | call_id | Identifier for the current call | String | Call.ConversationId |
✓ |
| Input | credential | Voiceprint generated from a previous registration | String | any | ✓ |
| Output | error_msg | Error detailed message | String | any | |
| Output | verify_session_id | Identifier of the created Session | String | any | |
| Output | result | Result of the flow | String | success, error |
result parameter will specify if the action was successful or not. Also, Verify Session identifier will be available via verify_session_id parameter. This identifier should be used to get status of Verify Session.
credential input parameter must be obtained from a previous registration process. Credendial Management is delegated to IVR administrator.
Step2: Get client speech¶
Upon successful result (Verify Session created), client audio will be recorded from this point. Thus, IVR administrator should guarantee user speech is acquired. This can be done by asking questions to user or by any alternative method. This process is delegated to the IVR administrator.
Step3: Add "Get Verify Result Veridas" Common Module¶
After Verify Session has been created and enough audio has been collected, a new Call Common Module action must be added to the flow. The Common Module to be called by this action is Get Verify Result Veridas (latest version). This Common Module will call das-Peak Streaming to get the status of a Verify Session.
Parameters defined for Get Verify Result Veridas Common Module are:
| Direction | Parameter | Description | Type | Allowed values | Required |
|---|---|---|---|---|---|
| Input | verify_session_id | Identifier of requested Session | String | any | ✓ |
| Output | audio_seconds | Seconds of speech collected (audio without silences) so far when result is 'processing' | Decimal | [0.0, 30.0] | |
| Output | authenticity | Authenticity score of credential obtained | Decimal | [0.0, 1.0] | |
| Output | error_msg | Error detailed message | String | any | |
| Output | result | Result of the flow | String | success, fail, spoof, processing, error | |
| Output | score | Similarity score between the incoming voice and the voiceprint | Decimal | [0.0, 1.0] | |
| Output | vad_percentage | The percentage that represents the amount of speech collected compared to the amount of speech audio requested to be collected when result is 'processing' | Decimal | [0.0, 100.0] | |
| Output | voice_audio_collected | Seconds of speech collected (audio without silences) | Decimal | [0.0, 30.0] |
verify_session_id parameter must be equal to the one that was previously obtained by calling "Start Verify Streaming Veridas" Common Module. This way, previously created Verify Session status is obtained.
result parameter will specify the status of the Verify Session:
- success: Verify Session status is SUCCESS, meaning a valid credential was created.
- fail: Verify Session status is FAIL_SCORE, meaning verification failed.
- spoof: Verify Session status is FAIL_SPOOF, meaning recorded voice was tagged as not authentic.
- processing: Verify Session status is PROCESSING_AUDIO, meaning audio is still being processed by das-Peak Streaming.
- error: Verify Session status is ERROR, meaning an error occured during verification process.
If result is "processing", IVR administrator should ensure to get more audio from user and call Get Verify Result Veridas Common Module again afterwards.