IVR management

This section contains IVR management proto files.

Notes:

To download Gatekeeper proto files, click download Gatekeeper proto files.
Default values are determined by the gRPC specification. For more information, go to protocol buffers language guide .

ivrbot/ivr_bot_service.proto

IVRBot

IVR Bot service API. The IVR Bot supports 2 flows: IVR Session flow steps (the business logic flow is controlled by the server):

GetPersonStatus - Optional. Checks if person is enrolled before starting the IVR session.
StartIVRSession - Mandatory. Starts the IVR session.
SubmitPersonId - Mandatory. The claimed person, triggers biometric flow for verification or enrollment.
GetSessionDecision - Mandatory. Returns the session decision, if available. IVR could trigger the API several times until the response would have a decision.
EndIVRSession - Mandatory. Ends the IVR session.

IVR Recording flow steps (the biometric business logic flow is controlled by the IVR):

StartRecording - Mandatory. Starts a recording, the media is streamed by the server (based on recording adapters). The returned media urn could be used by the IVR to call biometric operations (such as Verify, ProcessAudio, Enroll, and Train).
StopRecording - Optional. Stops the recording. If not called, the recording is stopped based on timeout provided by StartRecording request.

gRPC method definitions

gRPC method definitions
Method Name	Request Type	Response Type	Description
GetPersonStatus	GetPersonStatus Request	GetPersonStatus Response	Gets person status unrelated to gatekeeper engagement. Could be used as pre-condition to check if a person is enrolled before starting the IVR session. The additional bindings support calling this API without exposing the person ID as part of the URL path (recommended when having Personally Identifiable Information (PII) as part of the person ID).
StartIVRSession	StartIVRSession Request	StartIVRSession Response	Starts the IVR session to trigger biometric operations based on person status.
SubmitPersonId	SubmitPersonId Request	SubmitPersonId Response	Submits the person ID associated with the ongoing IVR Session.
SubmitOptIn	SubmitOptIn Request	SubmitOptIn Response	Submits the person’s consent. The person’s consent is required for the enrollment flow. Without consent, the person is not enrolled. For opting out use Call Session Manager service Submit Agent Action API.
GetSessionDecision	GetSessionDecision Request	GetSessionDecision Response	Gets the current session decision.
EndIVRSession	EndIVRSession Request	EndIVRSession Response	Ends the IVR Session. Use the post command for passing custom data as part of the request.
StartRecording	StartRecording Request	StartRecording Response	Requests the Media Manager to start recording media such as a call. The start recording API is not required when calling StartIVRSession. The returned media urn could serve as input to biometric operation APIs. A recording factor will be added to the engagement.
StopRecording	StopRecording Request	StopRecording Response	Requests the Media Manager to stop a recording. Calling this API is optional, since recording will be stopped based on StartRecording max recording time in the request.

Methods with HTTP bindings

Notes:

REST API responses use the camel case naming convention, such as gkPersonId, but the REST API requests can either use the camel case or snake case naming convention, such as gk_person_id.
The following example displays root prefix and endpoint to build a complete URL, such as https://gatekeeper.api.nuance.com/v1/audios/upload-url:
- Root prefix for API: https://gatekeeper.api.nuance.com
- Endpoint: /v1/audios/upload-url
To know more about root prefixes for API that can be used for different geographies, go to Sites.

GetPersonStatus

GET /v1/ivr-bot/scopes/{gk_scope_id}/persons/{person_id}/status

POST /v1/ivr-bot/scopes/{gk_scope_id}/persons/status:get

StartIVRSession

POST /v1/ivr-bot/{gk_scope_id}/sessions

SubmitPersonId

PATCH /v1/ivr-bot/sessions/{call_session_id}/person

POST /v1/ivr-bot/sessions/{call_session_id}/person:submitId

SubmitOptIn

POST /v1/ivr-bot/sessions/{call_session_id}:optin

GetSessionDecision

GET /v1/ivr-bot/sessions/{call_session_id}/decision

Gets the current session decision.

For more information, see GetSessionDecision.

Endpoint

/v1/ivr-bot/sessions/{call_session_id}/decision

Request

{}

Response

Verify + DKF:

{
  "sessionDecision": {
    "decision": "DECISION_FRAUD",
    "decisionReason": "DECISION_REASON_UNSPECIFIED"
  },
  "verifyProgressStatus": {
    "progressStatus": "PROGRESS_STATUS_COMPLETED",
    "verifyProgressInformation": {
      "audioValidity": "REASON_AUDIO_OK"
    }
  },
  "detectFraudstersProgressStatus": {
    "progressStatus": "PROGRESS_STATUS_COMPLETED",
    "detectFraudstersProgressInformation": {
      "audioValidity": "REASON_AUDIO_OK"
    }
  },
  "status": {
    "statusCode": "OK",
    "statusSubCode": 0,
    "httpTransCode": 0,
    "fieldViolations": [],
    "statusDetails": [],
    "diagnosticDetails": []
  }
}

Enrollment + DKF:

{
  "detectFraudstersProgressStatus": {
        "progressStatus": "PROGRESS_STATUS_COMPLETED",
        "detectFraudstersProgressInformation": {
            "audioValidity": "REASON_AUDIO_OK"
        }
  },
  "processAudioForEnrollProgressStatus": {
        "progressStatus": "PROGRESS_STATUS_COMPLETED",
        "processAudioForEnrollProgressInformation": {
            "audioValidity": "REASON_AUDIO_OK",
            "currentNetAudio": "60.060s",
            "minNetAudioRequiredForEnroll": "10s",
            "minNetAudioRequiredForTrain": "20s",
            "maxNetAudioRequiredForEnroll": "60s"
        }
  },
  "enrollProgressStatus": {
        "progressStatus": "PROGRESS_STATUS_COMPLETED",
        "enrollProgressInformation": {
            "enrollStatus": "ENROLL_STATUS_READY"
        }
  },
  "trainProgressStatus": {
        "progressStatus": "PROGRESS_STATUS_COMPLETED",
        "trainProgressInformation": {
            "trainStatus": "TRAIN_STATUS_TRAINED"
      }
  },
  "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
  }
}

Verification Progress:

{
	"status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "fieldViolations": [],
        "statusDetails": []
 	},
	"verifyProgressInformation": {
		"audioValidity": "REASON_AUDIO_OK"
	}
}

Enrollment Progress:

{  
    "processAudioForEnrollProgressStatus": {
        "progressStatus": "PROGRESS_STATUS_IN_PROGRESS",
        "processAudioForEnrollProgressInformation": {
            "audioValidity": "REASON_AUDIO_OK",
            "currentNetAudio": "16.060s",
            "minNetAudioRequiredForEnroll": "10s",
            "minNetAudioRequiredForTrain": "20s",
            "maxNetAudioRequiredForEnroll": "60s"
        }  
    },
    "status": {
            "statusCode": "OK",
            "statusSubCode": 0,
            "httpTransCode": 0,
            "fieldViolations": [],
            "statusDetails": [],
            "diagnosticDetails": []  
    }
}

Verify with Noisy audio:

{
      "sessionDecision": {
            "decision": "DECISION_UNSPECIFIED",
            "decisionReason": "DECISION_REASON_AUDIO_TOO_NOISY"
      },
      "verifyProgressStatus": {
            "progressStatus": "PROGRESS_STATUS_COMPLETED",
            "verifyProgressInformation": {
                "audioValidity": "REASON_AUDIO_TOO_NOISY"
            }
      },
      "status": {
            "statusCode": "OK",
            "statusSubCode": 0,
            "httpTransCode": 0,
            "fieldViolations": [],
            "statusDetails": [],
            "diagnosticDetails": []
      }
}

Enroll with Audio Too Noisy:

{
      "processAudioForEnrollProgressStatus": {
            "progressStatus": "PROGRESS_STATUS_COMPLETED",
            "processAudioForEnrollProgressInformation": {
                  "audioValidity": "REASON_AUDIO_TOO_NOISY",
                  "currentNetAudio": "3.730s",
                  "minNetAudioRequiredForEnroll": "10s",
                  "minNetAudioRequiredForTrain": "20s",
                  "maxNetAudioRequiredForEnroll": "60s"
          }
      },
      "status": {
            "statusCode": "OK",
            "statusSubCode": 0,
            "httpTransCode": 0,
            "fieldViolations": [],
            "statusDetails": [],
            "diagnosticDetails": []
      }
}

EndIVRSession

DELETE /v1/ivr-bot/sessions/{call_session_id}

POST /v1/ivr-bot/scopes/{call_session_id}:delete

StartRecording

POST /v1/ivr-bot/recording/start

StopRecording

POST /v1/ivr-bot/recording/stop

EndIVRSessionRequest

Input message that defines parameters for EndIVRSession.

EndIVRSessionRequest
Field	Type	Description
call_session_id	string	Mandatory. The call session unique ID, returned by StartIVRSession.
custom_data	repeated EndIVRSessionRequest.CustomDataEntry	Optional. Key value pairs that is passed as KVPs to Gatekeeper (available for Business Logic Layer webhook and scope configuration)

EndIVRSessionRequest.CustomDataEntry

EndIVRSessionRequest.CustomDataEntry
Field	Type	Description
key	string
value	string

EndIVRSessionResponse

Output message that defines parameters returned by EndIVRSession.

EndIVRSessionResponse
Field	Type	Description
status	nuance.rpc.Status

GetPersonStatusRequest

Input message that defines parameters for GetPersonStatus.

GetPersonStatusRequest
Field	Type	Description
gk_scope_id	string	Mandatory. Gatekeeper scope ID.
person_id	string	Mandatory. Person ID.
voice_print_tag	string	Optional. Specific voice-print tag that checks the enrollment status. If not specified, one of the person’s voice-prints is used.

GetPersonStatusResponse

Output message that defines parameters returned by GetPersonStatus.

GetPersonStatusResponse
Field	Type	Description
One of opt_in_out:		Optional. If the person did not opt-in nor opt-out, none of the options are set.
opt_in_info	OptInInfo	Person opted-in.
opt_out_info	OptOutInfo	Person opted-out.
enroll_status	EnrollStatus	Mandatory. Person’s enrollment status.
voice_print_lock_info	VoicePrintLockInfo	Optional. Person’s voiceprint lock information.
status	nuance.rpc.Status	Mandatory. Returned status.

GetSessionDecisionRequest

Input message that defines parameters for GetSessionDecision.

GetSessionDecisionRequest
Field	Type	Description
call_session_id	string	Mandatory. The call session unique ID, returned by StartIVRSession.

GetSessionDecisionResponse

Output message that defines parameters returned by GetSessionDecision.

GetSessionDecisionResponse
Field	Type	Description
session_decision	SessionDecision	Optional. Provided when session decision is available. Could serve as condition to end the IVR Session.
verify_progress_status	ProgressInformation	Optional. Provided when the IVR Session verification starts.
detect_audio_spoofing_progress_status	ProgressInformation	Optional. Provided when the IVR Session audio spoofing started.
detect_fraudsters_progress_status	ProgressInformation	Optional. Provided when the IVR Session detect fraudsters started.
process_audio_for_enroll_progress_status	ProgressInformation	Optional. Provided when the IVR Session process audio for enroll started.
enroll_progress_status	ProgressInformation	Optional. Provided when the IVR Session enroll started (after process audio for enroll completed and the person opted-in).
train_progress_status	ProgressInformation	Optional. Provided when the IVR Session voiceprint training started (after enrollment completed)
status	nuance.rpc.Status	Mandatory. Returned status.

StartIVRSessionRequest

Input message that defines parameters for StartIVRSession.

StartIVRSessionRequest
Field	Type	Description
gk_scope_id	string	Mandatory. Gatekeeper scope ID.
call_id	string	Mandatory. The call ID is a unique call identification that is consistent for the whole call.
recording_id	string	Mandatory. Recording identifier. Unique recording ID is used as correlation ID with SIPREC. In case of a mismatch, recording requests fail.
ani	string	Optional. Caller Automatic Number Identification (ANI).
dnis	string	Optional. Caller dialed number.
custom_data	repeated StartIVRSessionRequest.CustomDataEntry	Optional. Key value pairs that is passed as KVPs to Gatekeeper (available for Business Logic Layer webhook and scope configuration)

StartIVRSessionRequest.CustomDataEntry

StartIVRSessionRequest.CustomDataEntry
Field	Type	Description
key	string
value	string

StartIVRSessionResponse

Output message that defines parameters returned by StartIVRSession.

StartIVRSessionResponse
Field	Type	Description
call_session_id	string	Mandatory. The call session unique ID is used as a key to other IVR session related APIs requests.
status	nuance.rpc.Status	Mandatory. Returned status.

StartRecordingRequest

Input message that defines parameters for StartRecording.

StartRecordingRequest
Field	Type	Description
gk_scope_id	string	Mandatory. Gatekeeper scope ID.
gk_engagement_id	string	Mandatory. Gatekeeper engagement ID.
gk_session_id	string	Mandatory. Gatekeeper session ID.
recording_id	string	Mandatory. Recording identifier. Unique recording ID is used as correlation ID with SIPREC. In case of a mismatch, recording requests fail.
platform	string	Optional. When a scope is mapped to several realm id’s, the platform identifies a specific realm id.
recording_side	RecordingSide	Mandatory. The side to be recorded.
max_recording_duration	google.protobuf.Duration	Optional. Specifies the maximum recording duration. This value will override the one from realm configuration. If not specified, the max recording duration will default to the one from realm configuration. A negative value or 0, max recording duration will be disabled.
caller_attributes	CallerAttributes	Optional. Caller attributed that will be attached to the audio segment.
agent_extension	string	Optional. Agent extension. For certain connectors, the absence of the required agent extension may lead to a failure, resulting in an NOT_FOUND status code.

StartRecordingResponse

Output message that defines parameters returned by StartRecording.

StartRecordingResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. Returned status.
media_urn	string	Mandatory. Media urn (available only when the returned status code is OK).

StopRecordingRequest

Input message that defines parameters for StopRecording.

StopRecordingRequest
Field	Type	Description
media_urn	string	Mandatory. The media urn from StartRecording response.

StopRecordingResponse

Output message that defines parameters returned by StopRecording.

StopRecordingResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. Returned status.

SubmitOptInRequest

Input message that defines parameters for SubmitOptIn.

SubmitOptInRequest
Field	Type	Description
call_session_id	string	Mandatory. The call session unique ID, returned by StartIVRSession.

SubmitOptInResponse

Output message that defines parameters returned by SubmitOptIn.

SubmitOptInResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. Returned status.

SubmitPersonIdRequest

Input message that defines parameters for SubmitPersonId.

SubmitPersonIdRequest
Field	Type	Description
call_session_id	string	Mandatory. The call session unique ID, returned by StartIVRSession.
person_id	string	Mandatory. The identified person ID.
first_name	string	Optional. Person’s first name.
last_name	string	Optional. Person’s last name.
custom_data	repeated SubmitPersonIdRequest.CustomDataEntry	Optional. List of custom application data in key-value pairs.

SubmitPersonIdRequest.CustomDataEntry

SubmitPersonIdRequest.CustomDataEntry
Field	Type	Description
key	string
value	string

SubmitPersonIdResponse

Output message that defines parameters returned by SubmitPersonId.

SubmitPersonIdResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. Returned status.

ivrbot/ivr_bot_messages.proto

CallerAttributes

Caller attributes that will be attached to the audio segment.

CallerAttributes
Field	Type	Description
channel_index	int32	Mandatory. The caller channel.
person_id	string	Mandatory. Person id.

DetectAudioSpoofingProgressInformation

Detect Audio Spoofing progress information.

DetectAudioSpoofingProgressInformation
Field	Type	Description
audio_validity	nuance.biosec.v1.AudioValidity	Optional. Validity of the audio used for the operation. This indicates the current status of the audio being processed. The value may change until the processing is fully completed.

DetectFraudstersProgressInformation

Detect Fraudsters progress information.

DetectFraudstersProgressInformation
Field	Type	Description
audio_validity	nuance.biosec.v1.AudioValidity	Optional. Validity of the audio used for the operation. This indicates the current status of the audio being processed. The value may change until the processing is fully completed.

EnrollProgressInformation

Enroll progress information.

EnrollProgressInformation
Field	Type	Description
enroll_status	EnrollStatus	Optional. Status of the enroll operation.

OptInInfo

Opt-in information.

OptInInfo
Field	Type	Description
timestamp	google.protobuf.Timestamp	Mandatory. When the person opted-in.

OptOutInfo

Opt-out information.

OptOutInfo
Field	Type	Description
timestamp	google.protobuf.Timestamp	Mandatory. When the person opted-out.
reason	string	Optional. The provided opt-out reason.
offer_opt_in_time	google.protobuf.Timestamp	Mandatory. When opt-in can be enabled.
offer_opt_in	bool	Mandatory. True when opt-out duration has passed.

ProcessAudioForEnrollProgressInformation

Process audio for enroll progress information message

ProcessAudioForEnrollProgressInformation
Field	Type	Description
current_net_audio	google.protobuf.Duration	Optional. Current net audio.
min_net_audio_required_for_enroll	google.protobuf.Duration	Optional. Minimum net audio required for enrollment. The value for this field is expected to be lower or equal to min_net_audio_required_for_train field.
min_net_audio_required_for_train	google.protobuf.Duration	Optional. Minimum net audio required for training. The value for this field is expected to be higher or equal to min_net_audio_required_for_enroll field.
max_net_audio_required_for_enroll	google.protobuf.Duration	Optional. Maximum net audio required for enrollment.
audio_validity	nuance.biosec.v1.AudioValidity	Optional. Validity of the audio used for the operation. This indicates the current status of the audio being processed. The value may change until the processing is fully completed.

ProgressInformation

Progress information message

ProgressInformation
Field	Type	Description
progress_status	ProgressStatus	Mandatory. Biometric operation progress status.
One of progress_information_details:		Optional. Progress information for specific operation.
process_audio_for_enroll_progress_information	ProcessAudioForEnrollProgressInformation	Optional. Process audio for enroll progress information.
verify_progress_information	VerifyProgressInformation	Optional. Verify progress information.
detect_audio_spoofing_progress_information	DetectAudioSpoofingProgressInformation	Optional. Detect Audio Spoofing progress information.
detect_fraudsters_progress_information	DetectFraudstersProgressInformation	Optional. Detect Fraudsters progress information.
enroll_progress_information	EnrollProgressInformation	Optional. Enroll progress information.
train_progress_information	TrainProgressInformation	Optional. Train progress information.

SessionDecision

Session biometric decision

SessionDecision
Field	Type	Description
decision	nuance.biosec.v1.Decision	Mandatory. The session final decision.
decision_reason	DecisionReason	Optional. The reason for decision failure.

TrainProgressInformation

Train progress information.

TrainProgressInformation
Field	Type	Description
train_status	nuance.biosec.v1.TrainStatus	Optional. Status of the training operation.

VerifyProgressInformation

Verify progress information.

VerifyProgressInformation
Field	Type	Description
audio_validity	nuance.biosec.v1.AudioValidity	Optional. Validity of the audio used for the operation. This indicates the current status of the audio being processed. The value may change until the processing is fully completed.

VoicePrintLockInfo

Person’s voiceprint lock information.

VoicePrintLockInfo
Field	Type	Description
locked	bool	Mandatory. Person’s voiceprint lock status.
locked_by	string	Optional. User that locked this person’s voiceprint.
reason	string	Optional. Voiceprint lock reason text.
mismatch_counter	google.protobuf.Int32Value	Optional. Mismatch counter that triggers locking the voiceprint.
timestamp	google.protobuf.Timestamp	Optional. Voiceprint lock timestamp.
lock_reason	LockReason	Optional. Specifies the standard locking reason.

ivrbot/ivr_bot_enums.proto

DecisionReason

Decision reason for voiceprint, convoprint and audio spoofing biometric factors.

Name	Number	Description
DECISION_REASON_UNSPECIFIED	0	Decision reason is not specified (all factors).
DECISION_REASON_INTERNAL_ERROR	1	An error occurred while making the decision (all factors).
DECISION_REASON_AUDIO_OK	2	Audio is valid (voiceprint and audio spoofing factors).
DECISION_REASON_NOT_ENOUGH_AUDIO	3	Processing requires more audio segments than provided (voiceprint and audio spoofing factors).
DECISION_REASON_INVALID_AUDIO	4	Audio format is invalid or not supported (voiceprint and audio spoofing factors).
DECISION_REASON_AUDIO_TOO_SHORT	5	Audio does not contain the amount of speech required to complete the process (voiceprint and audio spoofing factors).
DECISION_REASON_AUDIO_TOO_SOFT	6	Audio speech level is lower than the level required to complete the process (voiceprint and audio spoofing factors).
DECISION_REASON_AUDIO_TOO_LOUD	7	Audio is too loud and causes saturation (voiceprint and audio spoofing factors).
DECISION_REASON_AUDIO_TOO_NOISY	8	Audio SNR (Signal to Noise Ratio) is too low (voiceprint and audio spoofing factors).
DECISION_REASON_MULTI_SPEAKERS_DETECTED	9	Multiple speakers are detected (not supported).
DECISION_REASON_SYNTHETIC_SPEECH_DETECTED	10	Synthetic speech is detected (audio spoofing factor).
DECISION_REASON_PLAYBACK_INDICATION	11	Playback is detected (audio spoofing factor).
DECISION_REASON_TONE_DETECTED	12	Tone is detected (not supported).
DECISION_REASON_WRONG_PASSPHRASE	13	Wrong passphrase is used (not supported).
DECISION_REASON_FRAUDSTER_INDICATION	14	A fraud attempt probably occurred (voiceprint and convoprint factors).
DECISION_REASON_VOICEPRINT_MATCH	15	This is probably an authentic person (voiceprint factor).
DECISION_REASON_VOICEPRINT_MISMATCH	16	This is probably not an authentic person (voiceprint factor).
DECISION_REASON_VOICEPRINT_UNCERTAIN	17	Could not determine if this is the authentic person (voiceprint factor).
DECISION_REASON_UNRELIABLE_DECISION_THRESHOLDS	18	The system could not reach a reliable decision (audio spoofing factor).
DECISION_REASON_TEXT_OK	19	Text is valid (convoprint factor).
DECISION_REASON_INVALID_TEXT	20	Text format is invalid or not supported (convoprint factor).
DECISION_REASON_CONVOPRINT_MATCH	21	This is probably the authentic person (convoprint factor).
DECISION_REASON_CONVOPRINT_NO_MATCH	22	This is probably not the authentic person (convoprint factor).
DECISION_REASON_CONVOPRINT_UNCERTAIN	23	Could not determine if this is the authentic person (convoprint factor).
DECISION_REASON_NO_RISK_DETECTED	24	Risk is not detected (convoprint factor).
DECISION_REASON_NO_SCORES	25	No available scores (convoprint factor).

EnrollStatus

Specifies the current enrollment status of a person’s voiceprint.

Name	Number	Description
ENROLL_STATUS_UNSPECIFIED	0	Enroll status is not set.
ENROLL_STATUS_READY	1	Ready for enrollment.
ENROLL_STATUS_TRAINED	2	Ready for verification.
ENROLL_STATUS_PARTIALLY_ENROLLED	3	Missing additional audio segments.
ENROLL_STATUS_NOT_ENROLLED	4	Not enrolled.

LockReason

The standard lock reasons.

Name	Number	Description
LOCK_REASON_UNSPECIFIED	0	Use to initialize the fields.
LOCK_REASON_CONSECUTIVE_MISMATCHES	1	The print is locked due to too many consecutive mismatches
LOCK_REASON_OTHER	100	The print is locked due to a reason that is not standard. Details on the reason are available in another field.

ProgressStatus

Biometric operation progress status.

Name	Number	Description
PROGRESS_STATUS_UNSPECIFIED	0	The biometric operation was not specified.
PROGRESS_STATUS_STARTED	1	The biometric operation started.
PROGRESS_STATUS_IN_PROGRESS	2	The biometric operation in progress.
PROGRESS_STATUS_COMPLETED	3	The biometric operation completed.

RecordingSide

Listing of the possible recording sides. The side 1 could be the caller, and side 2 could be the agent, or vice versa, which depends on the configuration in the recorder.

Name	Number	Description
RECORDING_SIDE_UNSPECIFIED	0
RECORDING_SIDE_1	1
RECORDING_SIDE_2	2
RECORDING_SIDE_ALL	10