Important

The blueprints and code samples provided in this section are for reference and demonstration purposes only, delivered on an "as-is" basis. While these resources help illustrate how to connect Veridas services with third-party platforms, the final implementation, testing, and ongoing maintenance are the sole responsibility of the client. Our team does not guarantee continuous updates, long-term compatibility, or dedicated technical support for these sample integrations.

Important

The following is a text extracted directly from the Veridas "Genesys Cloud IVR Blueprint" repository, which includes all the artifacts required for the deployment of the Genesys Cloud IVR Blueprint. If you are interested in deploying Genesys Cloud IVR Blueprint in your Genesys Cloud environment, please contact the Veridas team to gain access to the repository and begin your integration.

Genesys Cloud IVR Blueprint¶

This project contains all required resources to deploy Veridas Genesys Cloud IVR Blueprint into a Genesys Cloud environment.

This blueprint enables a plug-and-play deployment of an integration for a IVR voice authentication scenario with Veridas services within Genesys Cloud. Under the hood, it uses the following Veridas services:

VSS (Veridas Streaming Service): for receiving and processing audio from Genesys Cloud Audiohook.
VCSP (Veridas Credential Service Provider): for generating, storing, and managing biometric credentials and handling authentication.

The deployment will provide a set of common module flows in Architect that can be used to build a voice authentication scenario. Additionally, an example flow demonstrating the use of these modules will be included.

Deploy instructions¶

Important

This section assumes that the integrator has a Genesys Cloud account and possesses platform administration knowledge. No details regarding Genesys Cloud administration are provided here. In case of any doubts, it is recommended to consult the official Genesys Cloud documentation.

1. Create a Genesys Cloud profile¶

The first step consists on creating a new profile (or using an existing one) in Genesys Cloud with the necessary permissions so that the Genesys Cloud IVR Blueprint can deploy the required resources in the customer’s infrastructure.

Go to People & Permissions > Roles / Permissions, click on Add Role and fill in with the following details (no detailed information can be left with default values):

Role Details:
- Name: Veridas IVR Blueprint
Permissions:
- Architect > Flow > All Permissions
- Architect > Job > All Permissions
- Architect > UI > All Permissions
- Integrations > All Permissions
- OAuth > All Permissions

Click on Save & Continue and then click on Change Membership to add your current maintenance user to the created profile. This is important for the next step.

2. Create a Genesys Cloud OAuth Client¶

To be able to deploy resources in Genesys Cloud, the Genesys Cloud IVR Blueprint requires a client identifier to authenticate in the customer's account. For this, it is necessary to create a new OAuth client that makes use of the profile created in the previous step.

Go to Integrations > OAuth, click on Add Client and fill in with the following details (other information can be left with default values):

App Name: Veridas IVR Blueprint
Grant Types: Client Credentials
Assign Roles:
- Role: Veridas IVR Blueprint*

* Genesys Cloud only allows to assign roles that are assigned to the user creating the OAuth client, so make sure you assigned the new role to your maintenance user in the last step.

Copy the generated Client ID and Client Secret and click on Finish.

3. Create a new terraform environment¶

Genesys Cloud IVR Blueprint uses Terraform as a tool to deploy all the necessary Genesys Cloud infrastructure and maintain change control. All the resources are described using the Genesys Cloud Terraform provider. Make sure to install Terraform before continue.

The entire source code is located within the src folder, which contains two subdirectories:

modules: Contains reusable Terraform modules with all the logic for creating resources.
environments: Contains environment-specific “root modules” (dev, staging, prod). Each environment has its own main.tf that calls the modules and a terraform.tfvars with environment-specific variables.

There already exists a default environment that can be used, but for the shake of learning, let's create another environment and let's name it "sandbox". To do this, just create a new folder called sandbox within environments and copy the main.tf and variables.tf from the default environment.

4. Fill in terraform variables¶

Using the template located in src/environments/terraform.tfvars.template, create a new terraform.tfvars file within the src/environments/sandbox/ directory and fill it with the following values:

genesyscloud_client_id: Genesys Cloud OAuth Client ID created in the last step.
genesyscloud_client_secret: Genesys Cloud OAuth Client Secret created in the last step.
genesyscloud_region: Your Genesys Cloud account region. Check region names.
base_url: BASE_URL provided by Veridas pointing to Veridas services.
apikey: API Key provided by Veridas to authenticate within Veridas services.
environment (Optional): Optional suffix to add to deployed resources to distinguish between production environments ("sandbox" in this example).

5. Deploy resources¶

Once the environment is fully described to start deploy run:

terraform init

This prepares the project directory by initializing the backend and downloading the providers. After that, to deploy the resources:

terraform apply -auto-approve

Note

If any change is required, run terraform apply again after applying the corresponding changes to the source code. Terraform will keep track of the changes for you.

When you don't need deplyed resources anymore you can destroy them by running:

terraform destroy -auto-approve

6. Assign a phone¶

Once deployed, a new Example Flow sandbox inbound flow will be available in your Genesys Cloud environment. Just assign an active phone number to this flow and start using it by making calls.

This Example Flow sandbox is just an example flow that demonstrates what you can do with Veridas Genesys Cloud IVR Blueprint and how to do it. Feel free to integrate voice authentication in your existing flows by using deployed common module flows.

Deployed resources¶

Once deployed, following new resources will be created in your Genesys Cloud environment:

Resource Type	Name / Identifier	Purpose
Genesys Cloud Integration Credential	`genesyscloud_integration_credential.veridas_data_actions_apikey`	Stores the API key used by the Data Actions integration to authenticate requests to Veridas APIs.
Genesys Cloud Integration Credential	`genesyscloud_integration_credential.veridas_audiohook_apikey`	Stores the API key used by the Audiohook integration to authenticate streaming requests to Veridas APIs.
Genesys Cloud Integration	`genesyscloud_integration.integration_data_actions`	Custom REST Data Actions integration for VSS/VCSP API operations.
Genesys Cloud Integration	`genesyscloud_integration.integration_audiohook`	Audiohook integration for real-time audio streaming to VSS.
Genesys Cloud Flow	`genesyscloud_flow.example_flow`	Example flow YAML integrating VSS/VCSP Data Actions, demonstrating how to orchestrate Veridas interactions.
Genesys Cloud Integration Action	`genesyscloud_integration_action.vss_create_session`	Data Action that creates a new VSS session for a call.
Genesys Cloud Integration Action	`genesyscloud_integration_action.vss_read_session`	Data Action that reads the status of a VSS session.
Genesys Cloud Integration Action	`genesyscloud_integration_action.vcsp_read_account`	Data Action that checks if a subject account exists in VCSP `subject_id`.
Genesys Cloud Integration Action	`genesyscloud_integration_action.vcsp_delete_account`	Data Action that deletes a subject account from VCSP.
Genesys Cloud Integration Action	`genesyscloud_integration_action.vcsp_enroll`	Data Action that enrolls a subject’s voice sample in VCSP.
Genesys Cloud Integration Action	`genesyscloud_integration_action.vcsp_one_to_one_matching`	Data Action that performs 1:1 biometric matching against a subject.
Genesys Cloud Flow	`genesyscloud_flow.vss_create_session`	Common Module Flow that implements the VSS “Create Session” logic using the YAML definition at `./flows/vss/create_session.yaml`.
Genesys Cloud Flow	`genesyscloud_flow.vss_read_session`	Common Module Flow that implements the VSS “Read Session” logic using the YAML definition at `./flows/vss/read_session.yaml`.
Genesys Cloud Flow	`genesyscloud_flow.vcsp_read_account`	Common Module Flow that implements the VCSP “Read Account” logic using the YAML definition at `./flows/vcsp/read_account.yaml`.
Genesys Cloud Flow	`genesyscloud_flow.vcsp_delete_account`	Common Module Flow that implements the VCSP “Delete Account” logic using the YAML definition at `./flows/vcsp/delete_account.yaml`.
Genesys Cloud Flow	`genesyscloud_flow.vcsp_enroll`	Common Module Flow that implements the VCSP “Enroll” logic using the YAML definition at `./flows/vcsp/enroll.yaml`.
Genesys Cloud Flow	`genesyscloud_flow.vcsp_one_to_one_matching`	Common Module Flow that implements the VCSP “1:1 Matching” logic using the YAML definition at `./flows/vcsp/one_to_one_matching.yaml`.

Notes

Veridas Data Actions implement Veridas VSS and VCSP REST calls, defining input/output contracts and API call templates. They centralize external API logic, making it reusable across multiple flows.

Architect Common Module flows (vss_* and vcsp_*) use these Data Actions to perform operations like creating sessions, reading accounts, enrollment, and 1:1 matching.

Common Module Flows API¶

The ultimate purpose of Genesys Cloud IVR Blueprint is for the customer to be able to integrate voice authentication into their IVR flows. To achieve this, among the resources deployed by Genesys Cloud IVR Blueprint are a series of common modules that act as an Architect SDK, allowing the use of Veridas' voice authentication services (VSS+VCSP).

Common Module Flow	Parameters	Description	Output	Error Codes
`vss_create_session`	`net_speech_duration`, `stream_id`	Creates a new VSS session for a call.	`{}`	`INTERNAL_ERROR`, `TIMEOUT`
`vss_read_session`	`stream_id`	Reads the status of a VSS session.	`{ "status": <status>, "sample": <audio_file> }` if finished, otherwise `{ "status": <status> }`	`INTERNAL_ERROR`, `TIMEOUT`
`vcsp_read_account`	`subject_id`	Checks if a subject account exists in VCSP.	`{ "exists": true/false }`	`INTERNAL_ERROR`, `TIMEOUT`
`vcsp_delete_account`	`subject_id`	Deletes a subject account from VCSP.	`{}`	`INTERNAL_ERROR`, `TIMEOUT`
`vcsp_enroll`	`sample`, `subject_id`, `authenticity_threshold`	Enrolls a subject’s voice sample in VCSP.	`{"spoof": true/false}`	`INTERNAL_ERROR`, `TIMEOUT`, `AUTHENTICITY_ERROR`
`vcsp_one_to_one_matching`	`sample`, `subject_id`, `authenticity_threshold`, `biometric_threshold`	Performs 1:1 voice matching against a subject.	`{ "match": true/false, "spoof": true/false }`	`INTERNAL_ERROR`, `TIMEOUT`, `AUTHENTICITY_ERROR`

Notes

Additionally, each Common Module Flow has two extra outputs:
- success: boolean flag to indicate that operation succeeded or not.
- error_code: error code with information about the specific error.
subject_id must contain only alphanumeric characters, _ or -.
stream_id must always be assigned to Call.ConversationId since it's the stream_id used by Audiohook stream.

Add these common module flows into your new or existing Architect flows by using the Architect Call Common Module action. Use them in the way that best fits the business logic of your scenario.