API Definition

Socket.IO Channel follows an AsyncApi structure.

Channels

Alive Channel

The service receives a Socket.IO connection to the /alive endpoint with no params, indicating that the service is up. The client can disconnect itself, or send an alive Socket.IO event to be disconnected.

Operation	Public URL	Description
alive	/alive	Check if the service is up

• Publish:
  • Description: Check service is up
  • Operation ID: alive
  • Message:
    • alive

Register Channel

Allow users to create and get the status of a Register Session.

Operation	Public URL	Description
initialize	/register	Manages a Register Session

• Publish:
  • Description: Create Register Session
  • Operation ID: createRegisterSession
  • Message:
    • initialize
• Subscribe:
  • Description: Get status of Register Session
  • Operation ID: getRegisterSession
  • Message:
    • Results
      • result-success
      • result-fail-spoof
    • Errors
      • error-consumer-not-ready
      • error-parameters
      • error-audio
      • error-das-Peak
    • Informative
      • info-consumer-ready
      • info-vad-status

Verify Channel

Allow users to create and get the status of a Verify Session.

Operation	Public URL	Description
initialize	/verify	Manages a Verify Session

• Publish:
  • Description: Create Verify Session
  • Operation ID: createVerifySession
  • Message:
    • initialize
• Subscribe:
  • Description: Get status of Verify Session
  • Operation ID: getVerifySession
  • Message:
    • Results
      • result-success
      • result-fail-score
      • result-fail-spoof
    • Errors
      • error-consumer-not-ready
      • error-parameters
      • error-audio
      • error-das-Peak
    • Informative
      • info-consumer-ready
      • info-vad-status

Components: Messages

alive - channel: Alive Channel

• Description: Sent to check server is up and running.
• Payload: text/plain

initialize - channel: Register Channel

• Description: Start a registration process.
• Payload: Content-Type: application/json

Name	Type	Description
metadata	json	Audio Settings parameters required to set up the process
register_request	json	Register Session configuration parameters

• Metadata:

Name	Type	Description	Accepted Values
audio_protocol	string	Protocol selected for the audio streaming towards das-Peak Streaming	twilio, audiohook
audio_format	string	Format of the audio sent via streaming	raw, webm
audio_codec	string	Codec of the audio sent via streaming	mulaw, opus, `` (empty value for PCM)
sample_format	string	Meta information of Sample Format of the audio	regex: [SUF]\d+_?\d+?[BL]E, example: S16LE
sample_rate	string	Meta information of Sample Rate of the audio	8000, 16000
channels	string	Meta information of the numbers of channels of the audio	1, 2
call_id	string	Identifier for the current call	Any string that uniquely identifies a call

• register_request:

Name	Type	Description	Accepted Values
authenticity_threshold	string	Authenticity threshold required for the process to succeed	0 <= value <= 1
audio_total_duration	string	Minimum amount of seconds of speech required to process the audio	3 <= value <= 30
model_hash	string	Hash of biometric model to be used	Any string that uniquely identifies a model hash
return_audio	boolean	Boolean value that allows to retrieve audio when registration is successfull. If not specified, sets to true	true, false

{
    metadata: {
      'audio_protocol': 'audiohook',
      'audio_format': 'raw',
      'audio_codec': 'mulaw',
      'sample_format': '',
      'sample_rate': '8000',
      'channels': '1',
      'call_id': `1234`
    },
    register_request: {
      'authenticity_threshold': '0.7',
      'audio_total_duration': '3.00',
      'model_hash': '<MODEL_HASH>'
    },
};

initialize - channel: Verify Channel

• Description: Start a verification process.
• Payload: Content-Type: application/json

Name	Type	Description
metadata	json	Audio Settings parameters required to set up the process
verify_request	json	Verify Session configuration parameters

• Metadata:

Name	Type	Description	Accepted Values
audio_protocol	string	Protocol selected for the audio streaming towards das-Peak Streaming	twilio, audiohook
audio_format	string	Format of the audio sent via streaming	raw, webm
audio_codec	string	Codec of the audio sent via streaming	mulaw, opus, `` (empty value for PCM)
sample_format	string	Meta information of Sample Format of the audio	regex: [SUF]\d+_?\d+?[BL]E, example: S16LE
sample_rate	string	Meta information of Sample Rate of the audio	8000, 16000
channels	string	Meta information of the numbers of channels of the audio	1, 2
call_id	string	Identifier for the current call	Any string that uniquely identifies a call

• verify_request:

Name	Type	Description	Accepted Values
credential	string	Voiceprint generated from a previous registration	Any string that uniquely represents the voice of a subject
score_threshold	string	Minimum threshold required for the process to succeed	0 <= value <= 1
authenticity_threshold	string	Authenticity threshold required for the process to succeed	0 <= value <= 1
audio_total_duration	string	Minimum amount of seconds of speech required to process the audio	3 <= value <= 30

Example:

{
    metadata: {
      'audio_protocol': 'audiohook',
      'audio_format': 'raw',
      'audio_codec': 'mulaw',
      'sample_format': '',
      'sample_rate': '8000',
      'channels': '1',
      'call_id': `1234`
    },
    verify_request: {
      'credential': '1234',
      'score_threshold': '0.80',
      'authenticity_threshold': '0.7',
      'audio_total_duration': '3.00`
    },
};

info-consumer-ready - all channels

• Description: Received when Session is successfully created, meaning Audio Consumer is ready to receive audio. When receiving this event, Session state is "PROCESSING_AUDIO".
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained

Example:

{
  'event': 'info-consumer-ready',
  'content': 'Audio consumer for provided audio protocol is ready',
};

info-vad-status - all channels

• Description: Received for a Register Session while related Audio Consumer receives audio. The latest message received of this type is always an informative update of the amount of speech collected from the audio stream. It gets sent after processing each audio chunk and, as soon as enough speech is received, one last info-vad-status message is sent. When receiving this event, Session state is "PROCESSING_AUDIO".
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained
audio_seconds	float	Seconds of speech collected (audio without silences) so far.
The margin of error of 0.01 due to rounding results
vad_percentage	int	The percentage that represents the amount of speech collected compared to the amount of speech audio requested to be collected

Example:

{
  'event': `info-vad-status`,
  'content': 'Voice activity detection percentage',
  'audio_seconds': 1.06,
  'vad_percentage': 21
};

result-success - channel: Register Channel

• Description: Received when Register Session state is set as "SUCCESS".
• Payload: Content-Type: array
• Items:
  • data: Register session data
    • Payload: Content-Type: application/json
  • collected_audio: Collected audio
    • Payload: Content-Type: application/x-wav

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained
credential	string	Voiceprint generated from the audio stream
authenticity	float	A number ranging from 0 to 1 represents how likely the sample (incoming audio) is to be a bonafide voice. The closer the number is to 1, the higher the chance of being a genuine voice. The margin of error of 0.01 due to rounding results.
voice_audio_collected	float	Seconds of speech collected (audio without silences). The margin of error of 0.01 due to rounding results.

data example:

{
  'event': result-success,
  'content': 'Registration: approved',
  'credential': '1234',
  'authenticity': 0.98,
  'voice_audio_collected': 5.06
};

result-success - channel: Verify Channel

• Description: Received when Verify Session state is set as "SUCCESS".
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained
score	float	A number ranging from 0 to 1 represents the similarity between the incoming voice and the voiceprint. 0 stands for completely different vocal patterns whilst 1 would mean completely identical. The margin of error of 0.01 due to rounding results.
authenticity	float	A number ranging from 0 to 1 represents how likely the sample (incoming audio) is to be a bonafide voice. The closer the number is to 1, the higher the chance of being a genuine voice.The margin of error of 0.01 due to rounding results.
voice_audio_collected	float	Seconds of speech collected (audio without silences). The margin of error of 0.01 due to rounding results.

Example:

{
  'event': 'result-success',
  'content': 'Authentication: approved',
  'score': 1,
  'authenticity': 0.93,
  'voice_audio_collected:' 3.06,
};

result-fail-spoof - channel: Register Channel

• Description: Received when Register Session state is set as "FAIL-SPOOF".
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained
credential	string	Voiceprint generated from the audio stream
authenticity	float	A number ranging from 0 to 1 represents how likely the sample (incoming audio) is to be a bonafide voice. The closer the number is to 1, the higher the chance of being a genuine voice. The margin of error of 0.01 due to rounding results.
voice_audio_collected	float	Seconds of speech collected (audio without silences). The margin of error of 0.01 due to rounding results.

Example:

{
  'event': 'result-fail-spoof',
  'content': 'Registration: rejected',
  'credential': '1234',
  'authenticity': 0.48,
  'voice_audio_collected': 5.06
};

result-fail-spoof - channel: Verify Channel

• Description: Received when Verify Session state is set as "FAIL-SPOOF".
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained
score	float	A number ranging from 0 to 1 represents the similarity between the incoming voice and the voiceprint. 0 stands for completely different vocal patterns whilst 1 would mean completely identical. The margin of error of 0.01 due to rounding results.
authenticity	float	A number ranging from 0 to 1 represents how likely the sample (incoming audio) is to be a bonafide voice. The closer the number is to 1, the higher the chance of being a genuine voice. The margin of error of 0.01 due to rounding results.
voice_audio_collected	float	Seconds of speech collected (audio without silences). The margin of error of 0.01 due to rounding results.

Example:

{
  'event': `result-fail-spoof`,
  'content': 'Authentication: rejected',
  'score': 0.93,
  'authenticity': 0.45,
  'voice_audio_collected:' 3.06,
};

result-fail-score - channel: Verify Channel

• Description: Received when Verify Session state is set as "FAIL-SCORE".
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained
score	float	A number ranging from 0 to 1 represents the similarity between the incoming voice and the voiceprint. 0 stands for completely different vocal patterns whilst 1 would mean completely identical. The margin of error of 0.01 due to rounding results.
authenticity	float	A number ranging from 0 to 1 represents how likely the sample (incoming audio) is to be a bonafide voice. The closer the number is to 1, the higher the chance of being a genuine voice. The margin of error of 0.01 due to rounding results.
voice_audio_collected	float	Seconds of speech collected (audio without silences). The margin of error of 0.01 due to rounding results.

Example:

{
  'event': `result-fail-score`,
  'content': 'Authentication: rejected',
  'score': 0.58,
  'authenticity': 0.98,
  'voice_audio_collected:' 3.06,
};

error-consumer-not-ready - all channels

• Description: Received after requesting a registration or verification process, whenever the audio consumer required is not operative.
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained

Example:

{
  'event': 'error-consumer-not-ready',
  'content': 'Audio consumer for provided audio protocol is not running on this instance',
};

error-parameters - all channels

• Description: Received after requesting a registration or verification process, whenever the parameters within the request are not valid nor complete.
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained
exception	string	The message that contains the error that occurred

Example:

{
  'event': 'not_correct_parameters',
  'content': 'Bad request',
  'exception': 'ValidationError'
};

error-audio - all channels

• Description: Received during a registration or verification process, whenever the audio stream does not reach the audio consumer, fails to comply with the protocol defined for the requested audio consumer, or if not enough speech is collected within a timeout.
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained
exception	string	The message that contains the error that occurred
voice_audio_collected	float	Seconds of speech collected (audio without silences). The margin of error of 0.01 due to rounding results.

Example:

{
  'event': `error-audio`,
  'content': 'Audio for provided call id not received or audio protocol not properly followed',
  'exception': `AudioNotCorrect`,
  `voice_audio_collected`: 1.06
};

error-das-Peak - all channels

• Description: Received whenever an error occurs while calling das-Peak voice biometric service.
• Payload: Content-Type: application/json

Name	Type	Description
event	string	Event and type of message received
content	string	The message that summarizes the result obtained
exception	string	The message that contains the error that occurred
voice_audio_collected	float	Seconds of speech collected (audio without silences). The margin of error of 0.01 due to rounding results.

Example:

{
  'event': `error-das-Peak`,
  'content': `das-Peak error`,
  'exception': `The audio sent within the request does not match a supported media type`,
  'voice_audio_collected': 5.06
};