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.

Endpoint

CODE

POST /api/token/

Headers

JSON

Authorization: Bearer {idm_token_service}

Request Body

JSON

{
    "agentId": "test",
    "agentSkill": "test",
    "masterId": "test", # Call.ConversationID from Genesys
    "tenantId": "test",
    "vbProfile": "test", # created on OCP console
    "ccaasProvider": "GENESYS",
    "customProperties": {       # biokeys if already present when initiating session, e.g. Ani
        "Ani":"test"
    }
}

Response

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}.

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

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

Endpoint

CODE

GET /users/info/{userID}

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.

Endpoint

CODE

POST /users/search

Headers

CODE

Authorization: Bearer {session_token}

Request Body

JSON

{
    "biokeys": [
        {
            "key": "Ani",
            "value": "1111",
            "is_user_id": false
        },
        {
            "key": "DoB",
            "value": "09121990",
            "is_user_id": false
        }
    ]
}

Response

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"
}

Get Dialog Status

Get updates on dialog status. The responses are in the form of server-sent events.

Endpoint

CODE

GET /dialog-status

Request

The following parameter needs to be added:

Parameter	Explanation
token	The token of the session

Responses

Below are the statuses that can be returned:

CALL_OPENED
BIO_ACTIVE
SYSTEM_ERROR
CALL_CLOSED
ERR_CODE_01
ERR_CODE_02
ERR_CODE_03
ERR_CODE_04
ERR_CODE_05
ERR_CODE_06

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

Endpoint

CODE

GET /verification/ondemand

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
}

Enable push Verification

This request is used to start a verification for a specific session and a specific user. Server-sent events are expected to be returned.

Endpoint

CODE

GET /verification

Note: If a new verification request is sent, the server will stop sending events for the previous one.

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

Responses

Initial Response

JSON

[
    {
        "bio_result": "",
        "bio_score": 0.0,
        "bio_user_id": "useridtest",
        "llr": 0.0,
        "result_type": "STARTING",
        "speech_millis": 0
    }
]

Early Result

JSON

[
    {
        "bio_result": "TRUE_LOW",
        "bio_score": 0.60,
        "bio_user_id": "useridtest",
        "llr": -24.237,
        "result_type": "EARLY",
        "speech_millis": 2720
    }
]

Final Result

JSON

[
    {
        "bio_result": "TRUE_HIGH",
        "bio_score": 0.91,
        "bio_user_id": "useridtest",
        "llr": -20.765799,
        "result_type": "NORMAL",
        "speech_millis": 5440
    }
]

Submit Enrolment

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

Endpoint

CODE

POST /enrol

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

JSON

{"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.

Endpoint

CODE

POST /users/optout

Headers

CODE

Authorization: Bearer : {session_token}

Request Body

JSON

{
  "user_id": "useridtest"
}

Response

JSON

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

Batch Enroll

Create enrollment by providing media file

CODE

curl -L -X POST 'https://us1-m.ocp.ai/agent-vb-mw/api/enroll' -H "Content-Type: multipart/form-data" -H 'Authorization: Bearer dummy' -F 'ccaas_provider=NICE_IN_CONTACT' -F 'profile_id=ugjT2CzZ' -F 'tenant_id=4658741' -F 'file=@/path/to/file/recording.mp4' -F 'biokeys[user_id]=userId' -F 'biokeys[Ani]=+1234567890'

Only media files downloaded from CCaaS providers are supported (.mp4 from NICE and .wav from Genesys).

Create On-demand Enrollment by providing CCaaS Session Id (call-id)

CODE

curl -L -X POST 'https://us1-m.ocp.ai/agent-vb-mw/api/enroll' -H "Content-Type: multipart/form-data" -H 'Authorization: Bearer dummy -F 'ccaas_provider=NICE_IN_CONTACT' -F 'profile_id=ugjTrAzZ' -F 'tenant_id=4605341' -F 'ccaas_session_id=471348707611' -F 'biokeys[user_id]=userId' -F 'biokeys[Ani]=+1234567890'

Indicate ccaas_session_id to use media file stored by CCaaS provider (NICE or Genesys) for enrollment.

NOTE: For both cases biokeys[user_id] is required.

You can add more biokeys to request if needed in such format:

CODE

curl -L -X POST 'https://us1-m.ocp.ai/agent-vb-mw/api/enroll' -H "Content-Type: multipart/form-data" -H 'Authorization: Bearer dummy' -F 'ccaas_provider=NICE_IN_CONTACT' -F 'profile_id=ugjTrAzZ' -F 'tenant_id=4605341' -F 'ccaas_session_id=471348707611' -F 'biokeys[user_id]=userId' -F 'biokeys[Ani]=+1234567890' -F 'biokeys[key]=value'