Contribute in GitHub:

Call failure handling in Voice Gateway

In general, when a call to Voice Gateway encounters a problem that causes it to fail, Voice Gateway has two behaviors depending on whether a transfer target is defined or not. For transfers, it's recommended to configure a default transfer target so that if it fails to connect to Watson Assistant or a Service Orchestration Engine, the call will still be transferred. Call failure handling described below applies both when the call is being setup and calls that are active.

If a transfer target is defined

In this case, IBM Voice Gateway will send a SIP REFER to initiate a transfer on any failure condition to a defined transfer target. On failure it will execute the following steps and transfer out the call:

Attempt to synthesize and play to the caller the text specified in the CONVERSATION_FAILED_REPLY_MESSAGE environment variable configuration (conversationFailedReplyMessage for Advanced JSON Configuration)
If it can't synthesize audio due to the Text-To-Speech service not being available it will instead stream to the caller a WAV file from the URL specified in the CONVERSATION_FAILED_REPLY_AUDIO_URL environment variable configuration (conversationFailedReplyAudioURL for Advanced JSON Configuration)
Places the caller on hold and initiates a transfer using SIP REFER.

In the case where the transfer fails, IBM Voice Gateway will attempt to synthesize and play to the caller the text specified in TRANSFER_FAILED_REPLY_MESSAGE environment variable configuration (transferFailedReplyMessage for Advanced JSON Configuration.

Important: The only scenario where a SIP REFER isn't sent, is when IBM Voice Gateway can't allocate a UDP port for media, it will respond to a SIP INVITE request with a 302 Moved Temporarily response and includes the transfer target in the contact header, which routes the call to the defined endpoint.

If no transfer target is defined

In the case that no transfer target is defined, on any error condition Voice Gateway will:

Attempt to synthesize and play to the caller the text specified in the CONVERSATION_FAILED_REPLY_MESSAGE environment variable configuration (conversationFailedReplyMessage for Advanced JSON Configuration).
If it can't synthesize audio due to the Text-To-Speech service not being available it will instead stream to the caller a WAV file from the URL specified in the CONVERSATION_FAILED_REPLY_AUDIO_URL (conversationFailedReplyAudioURL for Advanced JSON Configuration).
End the call with a SIP BYE request to the caller.

Configure a Default Transfer Target

Configure a default transfer target so that the call can be transferred in the event of a call failure and a transfer target can't be obtained from the Watson Assistant workspace.

`DEFAULT_TRANSFER_TARGET=<sip-address-of-target-to-transfer-to>`

Or through through the Advanced JSON Configuration:

{
	"tenants": [{
			"tenantURI": "2345556789",
			"description": "Voice Gateway Demo US",
			"whitelistFromUri": "8765554321",
			"putCallerOnHoldOnTransfer": "false",
      "transferDefaultTarget": "<sip-address-of-target-to-transfer-to>"
			"conversation": {
        ...
			},
			"stt": {
        ...
			},
			"tts": {
        ...
			}
  }]
}

Configuring default custom headers

Use the transferDefaultCustomHeaders multi-tenant configuration attribute in order to configure a list of default custom header fields to be added to a REFER or a BYE request, when a call is transferred due to an internal error.

For example,

{
  "transferDefaultCustomHeaders": {
    "Custom-Header1": "123",
    "Custom-Header2": "456"
  }
}

See Advanced JSON configuration properties for more details.