Voice Biometrics API

This document describes how the Voice Biometrics API be used independently as a stand alone offering.

Prerequisites

The prerequisites to use the endpoints below are the following:

Create a VB profile.
Create a Personal Access Token that belongs to the same group as the VB profile.

Endpoints

Initiate Session

This API call generates a token that will be used to correlate all HTTP calls that will be made during the course of the call.

POST	/api/token/	Get session token

Click to see details

Headers

JSON

Authorization: Bearer {idm_token_service}

Request Body

JSON

{
  "agentId": "agentId",
  "agentSkill": "agentSkill",
  "ccaasProvider": "NICE_IN_CONTACT",
  "masterId": "masterId",
  "tenantId": "tenantId",
  "vbProfile": "vbProfile",
  "customProperties": {
    "Ani": "+1234567890",
    "user_id": "User"
  }
}

Parameters		Type	Required	Description
`agentId`		String	Yes	The agent ID
`agentSkill`		String	Yes	The agent skills profile
`masterId`		String	Yes	Call conversation ID
`tenantId`		String	Yes	The tenant ID
`vbProfile`		String	Yes	The VB profile
`ccaasProvider`		String	Yes	The CCaaS provide name
`customProperties`		Object	No
	`onDemandStreamPause`	Boolean	No	Used to enable on-demand pause and on-demand resume endpoints. If this is not set to true, then the audio stream will automatically be terminated after gathering enough speech to enroll (~20 seconds)
	`cluster`	String	No	Is used to set cluster different from the default for certain NICE BUs for file enrollment. (Only for NICE integrations)
	`clusterDomain`	String	No	Default value: nice-incontact. Is used to set cluster domain different from the default for certain NICE BUs for file enrollment. (Only for NICE integrations)
	`callIdAsSessionToken`	Boolean	No	Allows to open frame with `callId` (`masterId`) instead of session token. `MasterId` should consist only of digits
	`showTtsDetectionResults`	Boolean	No	Enables TTS detection results to be displayed on the frame. Default value is true
`streamEnrol`		Boolean	No	For stream enrollment (false for recording file enrollment). default value is true
`verifyEnable`		Boolean	No	Enables verification. Default value is true
`advancedRecording`		Boolean	No	Enables file enrollments via NICE with `advancedRecording` (set to false to support NICE legacy file enrollment) Default value: true
`language`		String	No	The conversational language locale. Possible values, en-US, fr-CA, ad es-US. Default value is en-US

Response (success)

JSON

{
  "data":
    {
    "token":"729c65b2-48cc-4a8b-a0c2-aa1cb554c819"
    }
}

The token generated in this request will be used on the HTTP requests regarding the user, i.e. Enroll, Verify, Opt-in and Opt-out.

In the requests below, the token generated here will be referred as {session_token}.

Response (Fail)

Bad Request

JSON

{
  "details": "request body is invalid or missing"
}

Unauthorized

JSON

{
  "timestamp": "2023-11-17T13:13:13.718+00:00",
  "status": 401,
  "error": "Unauthorized",
  "path": "/agent-vb-mw/api/token/"
}

Internal Server Error

JSON

{
  "details": "Error during getting profiles By group"
}

Initiate Stream

The following ways are available to stream voice to the Voice Biometrics Service so that Enrolment and Verifications can be processed.

Configure Genesys Audiohook
Configure NICE’s Agent Assist Omilia Application
Connect to Omilia’s Websocket directly

Click here to expand...

Stream from Genesys Audiohook

Details to set the stream via the Genesys Audiohook can be found here.

Stream from NICE’s Agent Assist Omilia Application

Details about setting this up can be found here.

Stream to Omilia’s Websocket with your own client

Below is the endpoint where the stream should be sent.

Endpoint: wss://us1-m.ocp.ai/agent-vb-mw/stream?token={session_token}

The session_token is the one returned by the Initiate Session endpoint described above.

The protocol flow is as follows:

Client initiates a WebSocket connection to the WebSocket server, defining a message handler for the incoming recognition results.
Client sends a RecognitionConfig JSON message.
Server receives the RecognitionConfig message and starts a recognition session. No more RecognitionConfig messages are expected and sending one will result in an error.
Client starts sending messages containing binary audio data in format of string (bytearrays)(Base64-encoded) or ByteBuffer (bytearrays).
Client sends an empty message to the server to terminate a recognition session.
Server terminates the connection.

The RecognitionConfig JSON Body is as follows:

CODE

{
  "encoding" : "l16",
  "sample_rate" : 8000,
  "dialog_id" : "<DIALOG_ID>"
}

The dialog ID of the session should be the same as the one used in the initiate session request in the field masterId.

User status

Find the status of a user. Possible values are the following:

User is enrolled - ENROLLED
User is not enrolled - NOT_ENROLLED
User is opted-out - OPTED_OUT
User needs to re-enroll - RE_ENROLL

GET	/users/info/{userID}	Get the user enrollment information

Click to see details

Headers

CODE

Authorization: Bearer {session_token}

Response

JSON

{
    "user_id": "testuser",
    "status": "ENROLLED",
    "last_update": 1699360896573,
    "opt_out_ts": null,
    "opt_in_ts": null
}

Search User

Search for a specific user/users by giving their Biokeys. Only applies to users belong to the vbProfile
specified during session token creation.

POST	/users/search	Search Users by Biokeys

Click to see details

Headers

BASH

Authorization: Bearer {session_token}

Request

The following parameter needs to be added:

Parameter	Explanation
Authorization	The authorization token

Request Body

JSON

{
  "biokeys": [
    {
      "id": 0,
      "key": "UserID",
      "value": "Master",
      "display_name": "User",
      "priority": 1,
      "sensitive": true,
      "is_user_id": true
    }
  ]
}

Response (success)

JSON

{
    "users": [
        {
            "user_id": "otheruser",
            "status": "ENROLLED",
            "last_update": 1699362971388,
            "opt_out_ts": null,
            "opt_in_ts": null
        },
        {
            "user_id": "testuser",
            "status": "ENROLLED",
            "last_update": 1699360896573,
            "opt_out_ts": null,
            "opt_in_ts": null
        }
    ],
    "response_status": "FOUND_MANY"
}

On-demand Verification

This endpoint is used to request a single verification result at any point during a session. If more than one user (up to 5) is set in the users parameter, then the user with the highest score is only returned.

GET	/verification/ondemand	Starts an on demand verification

Click to see details

Request

The following parameters on the URL will need to be added:

Parameter	Explanation
`users`	The user to be passed so that a verification is run
`token`	The token of the session

Response

JSON

{
        "bio_result": "TRUE_HIGH",
        "bio_score": 0.91,
        "bio_user_id": "92feb975e7e7f8a7e6750482625a3d2f39b8dc755f35d49b2cd05ba4bb4da258",
        "bio_plain_user_id": "testuser",
        "error_type": null,
        "user_changed": false,
        "speech_millis": 5440
}

Passing user IDs that do not exist

If more than one users are passed and one of the user IDs passed does not exist, then that user ID will be ignored. If all of the user IDs passed do not exist, then the following error will be returned.

Error

JSON

{
    "bio_result": "ERROR",
    "bio_score": 0.0,
    "bio_user_id": null,
    "bio_plain_user_id": null,
    "error_type": "NO_USER",
    "user_changed": false,
    "speech_millis": 0
}

Submit Enrollment

This request will enroll a user. Make sure that enough speech (at least 10 seconds of clean speech) are given before issuing this request.

POST	/enroll	Enroll user

Click to see details

Headers

CODE

Authorization: Bearer : {session_token}

Request Body

JSON

{
  "biokeys": [
    {
      "key": "user_id",
      "value": "useridtest"
      "is_user_id": true
    },
    {
      "key": "Ani",
      "value": "12345",
      "is_user_id": false
    }
  ],
  "user_id": "useridtest"
}

Response

BASH

{"data":"Enroll user accepted"}

Request Opt-Out

The request below will opt-out a user. All data concerning the user (i.e. audios, voiceprints, biokeys) will be irrevocably lost.

POST	/users/optout	Opt-Out the user

Click to see the details

Headers

BASH

Authorization: Bearer : {session_token}

Request Body

JSON

{
  "user_id": "string",
  "org_id": "string",
  "is_hashed": true
}

Response (success)

BASH

{"data":"User opted-out"}