Voice Biometrics Generic Socket API | OCP® Learning Center

Overview

The AgentVB Middleware WebSocket API provides a Generic Socket interface for client-side initiation of verification flows and receiving streaming server-side updates.

This API replaces the Socket.IO API, which is deprecated.

The WebSocket server automatically begins sending messages upon successful connection and authentication. You send a single CommandRequestMessage to initiate commands such as GET_VERIFICATION or GET_ECHO.

All messages pushed by the server follow a SimpleWsMessage<T> envelope structure:

JSON

{
  "topic": "string",
  "data": { ... }
}

Connection Details

To establish a connection, use the following WebSocket URL and parameters.

Protocol: wss
Environment: wss://us1-m.ocp.ai
Path: /agent-vb-mw/ws/agent-vb

Connection Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The session token for authorization.
`signature`	string (JWT)	No	A JWT token to validate the client's origin.

Example URL: wss://us1-m.ocp.ai/agent-vb-mw/ws/agent-vb?token=<YOUR_TOKEN>

Operations

Client Commands

You send a JSON message to the server to trigger actions.

CommandRequest

Triggers a verification or echo command.

Payload Schema:

Field	Type	Required	Description
`command`	string	Yes	The command to execute. Allowed values: `GET_VERIFICATION`, `GET_ECHO`.
`parameters`	object	No	Key-value parameters for the command (e.g., `{"users": "user1,user2"}`).

Example:

JSON

{
  "command": "GET_VERIFICATION",
  "parameters": {
    "users": "user1,user2"
  }
}

Server Responses

The server sends the following messages to the client. Each message is wrapped in an envelope containing a topic and data.

Verification Response

Sent after a GET_VERIFICATION command is processed.

Topic: verification
Data Schema:

Field	Type	Description
`result_type`	string	The type of result (e.g., "NORMAL").
`bio_user_id`	string	The user ID verified.
`bio_result`	string	The verification result (e.g., "TRUE_HIGH").
`bio_score`	number	The biometric score.
`llr`	number	Log-likelihood ratio.
`speech_millis`	integer	Duration of speech in milliseconds.
`error_type`	string	Type of error, if any.

Status Update

Provides updates on the call status.

Topic: status
Data Schema: String (Enum)

Allowed Values:

CALL_OPENED
BIO_ACTIVE
CALL_CLOSED
ERR_CODE_01 through ERR_CODE_06

TTS Detection

Indicates the result of Text-to-Speech detection.

Topic: tts_detection
Data Schema:

Field	Type	Description
`label`	string	Detection label (e.g., `GENUINE`, `SPOOFED`, `SYNTHETIC`, `LOW_CONF`).
`global_post`	number	Global posterior score.

Blocklist Detection

Returns results from blocklist checks.

Topic: blocklist_detection
Data Schema:

Field	Type	Description
`label`	string	The detection label.
`status`	string	Status of the detection.
`risk_level`	string	Identified risk level.
`fraudster_id`	integer	ID of the identified fraudster.
`blocklist_id`	string	ID of the blocklist matched.
`score`	number	Overall score.

Enough Speech

Notifies when sufficient speech has been collected.

Topic: enough_speech
Data Schema:

Field	Type	Description
`enough_speech`	boolean	`true` when enough speech is detected.

Voice Info

Provides analysis on the voice characteristics.

Topic: voice_info
Data Schema:

Field	Type	Description
`liveness_score`	object	Contains `label` (e.g., `GENUINE`) and `global_post` score.
`satResult`	object	Signal analysis results including `valid`, `gender`, `ageLabel`, and `ageEstimate`.

ANI Validation Results

Provides results from ANI (Automatic Number Identification) validation.

Topic: ani_validation_results
Data Schema:

Field	Type	Description
`calling_number_ani`	string	The calling number being validated.
`trust_indicator`	integer	Trust score or indicator for the ANI.

Error Response

Sent when an invalid command is received or an error occurs.

Topic: error
Data Schema:

Field	Type	Required	Description
`message`	string	Yes	Description of the error.

Debug Response

Echoes debug information when GET_ECHO is sent.

Topic: debug
Data Schema: String (Debug message content).