GitHubContribute in GitHub: Edit online

copyright: years: 2017, 2023 lastupdated: "2023-01-08"

Advanced JSON configuration properties

You can use a JSON configuration file to define certain properties for individual tenants, rather than configuring environment variables that apply across the entire deployment.

Important: The multi-tenant configuration properties are related to Docker environment variables in the Voice Gateway configuration. If a value isn't defined in the JSON configuration file, some values of the related Docker environment variables are used as noted in the following sections.

Configuring multitenancy is supported in Version 1.0.0.2 and later.

Example JSON configuration file

For example, the following JSON file configures a tenant at the number 234-555-6789 as a self-service agent that publishes reporting events, plus another tenant at 234-555-7890 on the myhost.com host whose details are not shown.

To deploy this configuration, you must set the file path to your JSON configuration file as the MULTI_TENANT_CONFIG_FILE environment variable in your Voice Gateway deployment configuration file.

{
"tenants": [{
"tenantURI": "2345556789",
"description": "Voice Gateway Demo US",
"whitelistFromUri": "8765554321",
"putCallerOnHoldOnTransfer": "false",
"conversation": {
"url": "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}",
"workspaceID": "a23de67h-e527-40d5-a867-5c0ce9e72d0d",
"apikey": "{apikey}",
"tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token"
			},
"stt": {
"credentials": {
"url": "https://api.us-south.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}",
"apikey": "{apikey}",
"tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token"
				},
"config": {
"model": "en-US_NarrowbandModel",
"profanity_filter": true,
"smart_formatting": true
				},
"broadbandConfig": {
"model": "en-US_BroadbandModel",
"profanity_filter": true,
"smart_formatting": true
				},
"bandPreference": "broadband",
"confidenceScoreThreshold": 0.2,
"echoSuppression": true,
"bargeInResume": true,
"trackLatency": false
			},
"tts": {
"cacheTimeToLive": 336,
"credentials": {
"url": "https://api.us-south.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}",
"apikey": "{apikey}",
"tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token"
				},
"config": {
"voice": "en-US_MichaelVoice"
				}
			},
"reporting": {
"url": "http://10.10.10.10:8080",
"username": "john.smith",
"password": "HcmzFp1kec1P",
"cdrEventInd": "cdr",
"convEventInd": "conv",
"transcriptionEventInd": "transcription"
			},
"smsPipe": {
"url": "http://host:port/sms.gateway/smsPipe",
"username": "tR3qNZ12-u53qmz93",
"password": "Qz34x05e",
"tenantPhoneNumber": "+18765554321"
			},
"enableOutboundCalls": true,
"outboundCalls": {
"statusWebhook": "http://need.example.webhook.url.com/",
"tenantURI": "same as tenant URI above?",
"connectTimeout": 3,
"readTimeout": 5,
        "maxRetyNo": 2
      },
"restAPI": {
        "username": "exampleusername",
        "password": "examplepassword"
      },
"mediaEncryption": {
"encryptionType": "srtp",
"forceMediaEncryption": true
    }
  },
    {
"tenantURI": "2345557890@example.com"
		}
	]
}
  1. Add your tenant configuration to the Voice Gateway configuration, and deploy your environment. For more information, see Deploying a multi-tenant JSON configuration.

Important: The multi-tenant configuration properties are related to Docker environment variables in the Voice Gateway configuration. If a value isn't defined in the configuration JSON file, some values of the related Docker environment variables are used as noted in the following sections.

Back to the beginning

Required tenant properties

Table 1. Required JSON properties for configuring a tenant
JSON property Description Related environment variable
tenantURI A unique tenant identifier, such as a phone number. Must match the SIP To URI in the SIP INVITE request that starts the call. Each tenant must include a tenantURI.

Optional tenant properties

You can define the following configuration properties for each tenant individually. The properties are optional, but if you do want to define them, they must be defined as JSON properties. The values of the related Docker environment variables are not used.

Table 2. Optional JSON properties for configuring a tenant
JSON property Description Related environment variable
acceptTransferRejectCodes A comma-separated list of the error response codes that are treated as successful responses when processing a NOTIFY request during a call transfer. By default all codes in [200-299] are successful responses. If a response code in a NOTIFY request isn't in this range, the transfer process fails. You can extend the list of successful responses by adding this attribute. Version 1.0.0.6 and later. ACCEPT_TRANSFER_REJECT_CODES
conversationFailedReplyMessage Message streamed to the caller when a call is being transferred / disconnected due to a failure of one of the Watson services. Change the default message if no default target is configured. CONVERSATION_FAILED_REPLY_MESSAGE
conversationFailedReplyAudioURL A URL to an audio file that is played if the Text to Speech service can't be contacted when the Voice Gateway attempts to play back the conversationFailedReplyMessage message. CONVERSATION_FAILED_REPLY_AUDIO_URL
customSIPInviteHeader A SIP header field to extract from incoming SIP INVITE requests. When set, the value of the specified SIP header is passed to Watson Assistant in the vgwSIPCustomInviteHeader state variable. CUSTOM_SIP_INVITE_HEADER
customSIPInviteHeaders A comma separated list of SIP header fields to extract from incoming SIP INVITE requests. When set, the values of the specified SIP headers are passed to Watson Assistant in the vgwSIPCustomInviteHeaders state variable. CUSTOM_SIP_INVITE_HEADERS
customSIPRECSessionField A SIPREC metadata field whose value is used as the global session ID. The value of the specified SIPREC metadata field is used in all audit messages and is passed to Watson Assistant in the vgwSessionID state variable. If the configured field can't be found in the metadata, then the customSIPSessionHeader JSON property is used to determine the global session identifier. Possible values for the custom SIPREC session field include gcid, callid, and session_id. Version 1.0.0.6a and later. CUSTOM_SIPREC_SESSION_FIELD
customSIPSessionHeader A custom session ID header pulled from the SIP INVITE request. The value represents the global session ID that is used in all Voice Gateway audit logs related to the session. CUSTOM_SIP_SESSION_HEADER
description A description of the tenant, such as how it's used. Optional, but recommended. None
disconnectCallOnTransferFailure Determines whether to disconnect the call when the call transfer fails. When set to false, Voice Gateway initiates a conversation turn by sending "vgwCallTransferFailed" text to Watson Assistant. Then, Watson Assistant can either disconnect the call or transfer it to a different destination as configured in the dialog. Set to true by default. Version 1.0.0.2 and later. DISCONNECT_CALL_ON_TRANSFER_FAILURE
finalUtteranceTimeout Time in milliseconds that Voice Gateway waits to receive a final utterance from the Speech to Text service. The timeout occurs if Voice Gateway does not receive a final utterance within specified time limit, even if hypotheses continue to be generated. When the timeout occurs, Voice Gateway sends Watson Assistant a text update with the word "vgwFinalUtteranceTimeout" to indicate that no final utterance was received. Version 1.0.0.4c and later. FINAL_UTTERANCE_TIMEOUT
notifyConversationOnFilteredUtterances When the property is set to true, Voice Gateway initiates a new turn to Watson Assistant with the word "vgwSTTResultFiltered" to indicate that the utterance has been filtered due to low confidence level. Version 1.0.2 and later. NOTIFY_CONVERSATION_ON_FILTERED_UTTERANCES
notifyConversationOnNetworkEvents When set to true and a network error is detected, Voice Gateway initiates a turn to the Watson Assistant service with the text "vgwNetworkWarningMessage". The vgwNetworkWarnings state variable contains a list of the network events that happened during the current turn. If the flag is set to false, a list of the network events that happened during the current turn is sent in the next turn event in the vgwNetworkWarnings state variable. Version 1.0.0.5 and later. NOTIFY_CONVERSATION_ON_NETWORK_EVENTS
notifyConversationOnMediaChange Media capabilities can change in the middle of a call when a caller sends re-INVITE or UPDATE requests. When the property is set to true, Voice Gateway initiates a new turn to Watson Assistant with the word vgwMediaCapsChanged to indicate that media capabilities were successfully updated. NOTIFY_CONVERSATION_ON_MEDIA_CHANGE
postResponseTimeout Time in milliseconds to wait for a new utterance after the response is played back to the caller. If this value is exceeded, Watson Assistant receives a text update with the word "vgwPostResponseTimeout" to indicate that a timeout occurred. Set to 7000 ms by default. POST_RESPONSE_TIMEOUT
putCallerOnHoldOnTransfer Set to false if you don't want to place the caller on hold while the call is transferred. Version 1.0.0.3 and later. PUT_CALLER_ON_HOLD_ON_TRANSFER
sendOnFirstTurn Contains a comma-separated list of the settings to send to the Watson Assistant service in the first turn request. All settings in this list must be configured in the general section. Version 1.0.0.6 and later. SEND_ON_FIRST_TURN_TO_CONVERSATION
sendProvisionalResponse Set to false for the tenant to not send a 180 Ringing response while it processes an incoming call. Version 1.0.0.3 and later. SEND_PROVISIONAL_RESPONSE
sendSIPCallIDToConversation When true, the SIP call ID is passed to Watson Assistant in the vgwSIPCallID state variable. Set to false by default. SEND_SIP_CALL_ID_TO_CONVERSATION
sendSIPRequestURIToConversation When true, the SIP request URI is passed to Watson Assistant in the vgwSIPRequestURI state variable. Set to false by default. SEND_SIP_REQUEST_URI_TO_CONVERSATION
sendSIPToUriToConversation When true, the SIP To URI is passed to Watson Assistant in the vgwSIPToURI state variable. Set to false by default. SEND_SIP_TO_URI_TO_CONVERSATION
sendSIPFromUriToConversation When true, the SIP From URI is passed to Watson Assistant in the vgwSIPFromURI state variable. Set to false by default. SEND_SIP_FROM_URI_TO_CONVERSATION
sendSiprecMetadataToSTT When true, the SIPREC metadata will be sent to STT when a session is established. Set to false by default. Version 1.0.3.0 and later. SEND_SIPREC_METADATA_TO_STT
transferDefaultTarget Identifies the target transfer to endpoint. Must be valid SIP or tel URI (e.g. sip:10.10.10.10). This default transfer target is used only when a failure occurs and the call transfer target can't be obtained from the Watson Assistant API. TRANSFER_DEFAULT_TARGET
transferDefaultCustomHeaders A list of custom SIP headers that will be sent outbound with a REFER or BYE if an internal error occurs. Version 1.0.4 and later.

Example:
{
"transferDefaultCustomHeaders": {
"Custom-Header1": "123",
"Custom-Header2": "456"
}
}		 None
transferFailedReplyMessage If disconnectCallOnTransferFailure is set to True, the message streamed to the caller if the call transfer fails. TRANSFER_FAILED_REPLY_MESSAGE
transferFailedReplyAudioURL A URL to an audio file that is played if the Text to Speech service can't be contacted when the Voice Gateway attempts to play back the transferFailedReplyMessage message. TRANSFER_FAILED_REPLY_AUDIO_URL
useOptimalConfiguration Specifies whether to use the optimal configuration for the release. When set to true, the optimal configuration settings are used for the Voice Gateway version that is defined in the OPTIMAL_CONFIGURATION_VERSION environment variable or optimalConfigurationVersion JSON property. Set to false by default. Versions 1.0.0.6c and later. USE_OPTIMAL_CONFIGURATION
optimalConfigurationVersion Specifies the Voice Gateway version of the optimal configuration settings to be used. For example, 1.0.0.6c. Set to the most recent version by default. Versions 1.0.0.6.c and later. OPTIMAL_CONFIGURATION_VERSION
whitelistFromUri When defined, Voice Gateway accepts only calls that contain the specified string (such as a phone number) within the SIP From URI. WHITELIST_FROM_URI
type Possible values include agentAssist, selfService, and continuousRecognition. agentAssist is the default value for agent assist and SIPREC sessions. selfService is the default value for self service sessions. When the tenant type is set to agentAssist or continuousRecognition, speech recognition is open for the life of the call, rather than on a per conversational turn basis. Transcriptions from speech recognition are queued up whenever there is an existing outgoing request to the Watson Assistant or SOE. TENANT_TYPE
URIs A list of Tel / SIP URIs that are associated with that tenant. When an incoming call can't be mapped to the configured tenant URI, Voice Gateway looks for a match in this list. Example: "URIs": [
{
"name": "dc-office",
"uri": "111111111"
},
{
"name": "nyc-office",
"uri": "222222222"
}
]		 N/A
whitelistSiprecAttrName When defined, Voice Gateway accepts only calls that contain the specified attribute in the SIPREC metadata. This attribute value must match the value specified in the whitelistSiprecAttrValue attribute. WHITELIST_SIPREC_ATTR_NAME
whitelistSiprecAttrValue The attribute is mandatory when whitelistSiprecAttrName is configured. When defined, Voice Gateway accepts only calls that contain the attribute specified in whitelistSiprecAttrName with the value that matches the value specified in this attribute in the SIPREC metadata. WHITELIST_SIPREC_ATTR_VALUE
disconnectCallOnNoUserInputTurnCount Informs the Voice Gateway whether to disconnect the call on consecutive post response timeouts. Determines the number of consecutive post response timeouts to allow before the call is disconnected. Version 1.0.6 or later. DISCONNECT_CALL_ON_NO_USER_INPUT_TURN_COUNT

Back to the beginning

Properties for the conversation object

The IBM Watson™ Assistant service that you want to use for each tenant must be defined as JSON properties. The values of the related Docker environment variables are not used.

As with other configuration methods, both the conversation object and the wva object can't be defined within a single tenant.

Table 3. JSON properties for the conversation object
JSON property Description Related environment variable
url The url credential for Watson Assistant. WATSON_CONVERSATION_URL
workspaceID The Workspace ID for the Watson Assistant API. WATSON_CONVERSATION_WORKSPACE_ID
username The username credential for Watson Assistant. WATSON_CONVERSATION_USERNAME
password The password credential for Watson Assistant. WATSON_CONVERSATION_PASSWORD
apikey The API key, apikey, credential for your Watson Assistant service. You can configure connections with Watson services either by using apikey and setting tokenServiceProviderUrl to https://iam.cloud.ibm.com/identity/token, or by using both username and password Only available for the Sydney region. Version 1.0.0.6a and later. WATSON_CONVERSATION_APIKEY
apiVersion The version of the Watson Assistant API to use. Possible values include v1 and v2. v2 is supported in Version 1.0.1 and later. WATSON_CONVERSATION_API_VERSION
bearerToken The authentication token that will be used when making requests to the Watson Assistant service. Version 1.0.3.0 and later. N/A
connectTimeout Time in seconds that Voice Gateway waits to establish a socket connection with Watson Assistant. If the time is exceeded, Voice Gateway reattempts to connect with Watson Assistant. If the service still can't be reached, the call fails. Set to 5 seconds by default. Version 1.0.0.3 and later. WATSON_CONVERSATION_CONNECT_TIMEOUT
connectionKeepAliveEnabled true or false. Set to true by default. Specifies whether a connection to Watson Assistant service is kept open or closed after each request or response.
Note: Connection reuse isn't supported. A connection is closed after each request or response. When keep-alive is enabled, it might cause issues with some REST servers that expect a connection to remain open. You can turn off keep-alive by setting this to false. 1.0.0.7a and later.		 WATSON_CONVERSATION_CONNECTION_KA_ENABLED
readTimeout Time in seconds that Voice Gateway waits for a response from Watson Assistant. If the time is exceeded, Voice Gateway reattempts to contact Watson Assistant. If the service still can't be reached, the call fails. Set to 5 seconds by default. WATSON_CONVERSATION_READ_TIMEOUT
tokenAuthEnabled Enables token authentication for Watson Assistant. Disabled by default. Version 1.0.0.5a and later. WATSON_CONVERSATION_TOKEN_AUTH_ENABLED
tokenServiceProviderUrl This is the actual URL of the token authentication service for the Watson Assistant service. You might need to map this URL to a different one for routing purposes. Version 1.0.0.5a and later. WATSON_CONVERSATION_TOKEN_SERVICE_PROVIDER_URL
tokenServiceUrl This is the service URL that is embedded in the token request. Version 1.0.0.5a and later. WATSON_CONVERSATION_TOKEN_SERVICE_URL
providers Configurations for multiple service providers, which supports root level service configuration. Version 1.0.0.6 and later.
  • name: The name of your service instance.
  • You can configure the same JSON properties in the providers level as in the conversation object root level. This includes properties the url, workspaceID, username, password, tokenAuthEnabled, tokenServiceProviderUrl, and tokenServiceUrl properties.
See Configuring multiple service providers.		 N/A
providerSelectionPolicy In the event of service failure, the process by which Voice Gateway changes active Watson Assistant service instances when the tenant has multiple providers configured. Voice Gateway switches to the next provider in the list only when a conversation error occurs on the first turn to the Watson Assistant service. Once a call is established, Voice Gateway does not switch to another conversation provider in the middle of a call. Set to sequential by default. N/A
httpHeaders A JSON map that includes the name and value of HTTP headers. These HTTP header fields are added in the outbound REST requests to Watson Assistant. N/A
assistantID Watson Assistant ID for the Watson Assistant version 2 API. The assistant ID is used only by the Watson Assistant version 2 API. Voice Gateway version 1.0.1 and later. WATSON_ASSISTANT_ID
useStatelessAPI true or false. Specifies whether Voice Gateway uses the Watson Assistant stateless message method when calling the Assistant v2 API. By default, the stateful message method is used. For more information about the difference between the stateful and stateless message methods, see the Watson Assistant documentation. Version 1.0.7.0 and later. WATSON_CONVERSATION_USE_STATELESS_API

To configure the tenant to connect to Watson Assistant through a service orchestration engine (SOE), configure the SOE on the properties instead. If the SOE is configured to require authentication, specify the user name and password for HTTP basic authentication.

Table 4. JSON properties for connecting to a service orchestration engine
JSON property Description Related environment variable
url The exact URL to the service orchestration engine. WATSON_CONVERSATION_URL
username The plain-text user name for the service orchestration engine. Required only if authentication is enabled in the SOE. WATSON_CONVERSATION_USERNAME
password The plain-text password for the service orchestration engine. Required only if authentication is enabled in the SOE. WATSON_CONVERSATION_PASSWORD

Back to the beginning

Properties for the wva object

Note: You can't create new instances of Watson Virtual Agent after June 19, 2018. This service was removed from the IBM Cloud Catalog on March 19, 2019.

The Watson Virtual Agent chatbot that you want to use for each tenant must be defined as JSON properties. The values of the related Docker environment variables are not used. To connect to Virtual Agent through a service orchestration engine (SOE), configure the SOE on the conversation object.

As with other configuration methods, both the conversation object and the wva object can't be defined within a single tenant.

Table 5. JSON properties for the wva object
JSON property Description Related environment variable
wvaURL The url credential for the Watson Virtual Agent API. WATSON_VA_URL
wvaBotID The bot_id credential for the Watson Virtual Agent API. WATSON_VA_BOT_ID
wvaClientId The authentication key for the X-IBM-Client-Id header field for API calls to Watson Virtual Agent. WATSON_VA_CLIENT_ID
wvaClientSecret The authentication key for the X-IBM-Client-Secret header field for API calls to Watson Virtual Agent. WATSON_VA_CLIENT_SECRET

Back to the beginning

Properties for the stt object

The stt object contains configuration for either the Speech to Text service or the speech recognition services enabled by the Speech to Text Adapter. If a JSON property isn't defined, the value of the related Docker environment variable is used.

You can define the following properties to configure the Speech to Text service.

Table 6. JSON properties for the stt object
JSON property Description Related environment variable
credentials Credentials for the Speech to Text service. See The credentials property for the stt object
config Parameters for the Speech to Text service. See the WebSockets API reference for the Speech to Text Service. See Speech to Text (WATSON_STT) variables in the Media Relay configuration
broadbandConfig Parameters for the Speech To Text service when broadband audio is enabled. Required only when bandPreference is set to broadband. At minimum, the language model must be defined on the model property. For a full list of properties, see the WebSockets API reference for the Speech to Text Service. Version 1.0.0.4 and later. See broadband environment variables in Enabling broadband support
bandPreference Defines which audio band to prefer when negotiating audio codecs in the session. Set to broadband to use broadband audio when possible. The default value is narrowband. Version 1.0.0.4 and later. WATSON_STT_BAND_PREFERENCE
disableFirstTurnBargeIn Set this value to true to disable speech barge-in on the first conversation turn. Version 1.0.2.0 and later. WATSON_STT_DISABLE_FIRST_TURN_BARGE_IN
bargeInResume Set to true to resume playing back audio after barge-in if the confidence score of the final utterance is lower than the threshold specified by the confidenceScoreThreshold property. Version 1.0.0.5 and later. BARGE_IN_RESUME
confidenceScoreThreshold Confidence threshold of messages from the Speech to Text service. Messages with a confidence score that are under the threshold are not forwarded to Watson Assistant. The default value of 0 means that all responses will be used. The recommended values are between 0 and 1. WATSON_STT_CONFIDENCE_SCORE_THRESHOLD
connectionTimeout Time in seconds that Voice Gateway waits to establish a socket connection with the Watson Speech to Text service. If the time is exceeded, Voice Gateway reattempts to connect with the Watson Speech to Text service. If the service still can't be reached, the call fails. Version 1.0.0.5 and later. WATSON_STT_CONNECTION_TIMEOUT
requestTimeout Time in seconds that Voice Gateway waits to establish a speech recognition session with the Watson Speech to Text service. If the time is exceeded, Voice Gateway reattempts to connect with the Watson Speech to Text service. If the service still can't be reached, the call fails. Version 1.0.0.5 and later. WATSON_STT_REQUEST_TIMEOUT
echoSuppression Indicates whether to suppress results from Speech to Text that might occur from an echo of Text to Speech synthesis. Version 1.0.0.4c and later. ECHO_SUPPRESSION
providers Configurations for multiple service providers, which supports root level service configuration. Version 1.0.0.6 and later.
  • name: The name of your service instance.
  • providerType: Defines the speech provider as mrcpv2 or watson. Default is watson. Version 1.0.0.7 and later.
  • config: Required configuration defintions for either WatsonSpeechtoTextConfig or MrcpRecognizerConfig. Version 1.0.0.7 and later.
  • If you're using IBM® Speech to Text, you must configure the credentials property. You can also configure the same JSON properties in the providers level as in the conversation object root level. This includes properties such as url, workspaceID, username, password, tokenAuthEnabled, tokenServiceProviderUrl, and tokenServiceUrl properties.
See Configuring multiple service providers. For information about configuring an MRCP server, see Configuring services with MRCPv2		 N/A
providerSelectionPolicy In the event of service failure, the process by which Voice Gateway changes active Speech to Text service instances when the tenant has multiple providers configured. Voice Gateway switches to the next provider in the list only when an error occurs on the first turn to the service. Once a call is established, Voice Gateway does not switch to another speech to text provider in the middle of a call. Set to sequential by default. N/A
trackLatency When set to true, the Media Relay tracks the response latency with energy detection. The latency is the amount of elapsed time in milliseconds between when the Media Relay detects silence in caller speech to when the Media Relay receives a final result from Speech to Text. Version 1.0.0.8 and later. STT_TRACK_LATENCY

Back to the beginning

The credentials property for the stt object

Table 7. Configuration details about the attributes for the credentials JSON property.
Attribute Description Related environment variable
url The url credential for the Speech to Text service API WATSON_STT_URL
username The username credential for the Speech to Text service WATSON_STT_USERNAME
password The password credential for the Speech to Text service WATSON_STT_PASSWORD
apikey The API key, apikey, credential for your Speech to Text service. You can configure connections with Watson services either by using the apikey and setting tokenServiceProviderUrl to https://iam.cloud.ibm.com/identity/token, or by using both username and password. Version 1.0.0.6a and later. WATSON_STT_APIKEY
bearerToken The authentication token that will be used when making requests to the Speech To Text service. Version 1.0.3.0 and later. N/A
tokenAuthEnabled You can enable token authentication by changing the tokenAuthEnabled to true. See Enabling user name and password based token authentication for Watson services. Version 1.0.0.5a and later. WATSON_STT_TOKEN_AUTH_ENABLED
tokenServiceProviderUrl The value of this credential is the URL of the token authentication service for Speech to Text.Version 1.0.0.5a and later. WATSON_STT_TOKEN_SERVICE_PROVIDER_URL
tokenServiceUrl The service URL embedded in the token request. Version 1.0.0.5a and later. WATSON_STT_TOKEN_SERVICE_URL

Back to the beginning

Properties for the Speech to Text adapter

If you deployed Voice Gateway with the Speech to Text Adapter, define the following properties instead:

Table 8. JSON properties for the Google Cloud Speech API
JSON property Description Related environment variable
config Parameters for the Google Cloud Speech API RecognitionConfig request. For a full list of parameters, see the RecognitionConfig API documentation. See Google Cloud Speech (GOOGLE_SPEECH) variables in the Speech to Text Adapter configuration
thirdPartyCredentials Contents of a Google Cloud project service account JSON file. GOOGLE_APPLICATION_CREDENTIALS

Back to the beginning

Properties for the tts object

If a JSON property isn't defined, the value of the related Docker environment variable is used.

Table 9. JSON properties for the tts object
JSON property Description Related environment variable
credentials Credentials for the IBM® Text to Speech service. See The credentials property for the tts object
config Parameters for the IBM® Text to Speech service. See WebSockets API reference for Watson Text to Speech Service. See Text to Speech (WATSON_TTS) variables in the Media Relay configuration
jitterBufferDelay The amount of time in milliseconds to buffer before playing back audio from the Text to Speech service. This buffer accounts for any jitter in the streaming audio. WATSON_TTS_JITTER_BUFFER_DELAY
connectionTimeout Time in seconds that Voice Gateway waits to establish a socket connection with the Watson Text to Speech service. If the time is exceeded, Voice Gateway reattempts to connect with the Watson Text to Speech service. If the service still can't be reached, the call fails. Version 1.0.0.5 and later. WATSON_TTS_CONNECTION_TIMEOUT
requestTimeout Time in seconds that Voice Gateway waits to establish a speech synthesis session with the Watson Text to Speech service. If the time is exceeded, Voice Gateway reattempts to connect with the Watson Text to Speech service. If the service still can't be reached, the call fails. Version 1.0.0.5 and later. WATSON_TTS_REQUEST_TIMEOUT
cacheTimeToLive The time in hours to cache responses from the Text to Speech service to improve playback response time. When enabled, all Text to Speech responses are cached unless they are excluded in the Watson Assistant dialog. TTS_CACHE_TIME_TO_LIVE
providers Configurations for multiple service providers, which supports root level service configuration. Version 1.0.0.6 and later.
  • name: The name of your service instance.
  • providerType: Defines the speech provider as mrcpv2 or watson. Default is watson. Version 1.0.0.7 and later.
  • config: Required configuration definitions for either WatsonTexttoSpeechConfig or MrcpSpeechConfig. Version 1.0.0.7 and later.
  • If you're using IBM® Text to Speech, you must configure the credentials property. You can also configure the same JSON properties in the providers level as in the conversation object root level. This includes properties such as url, workspaceID, username, password, tokenAuthEnabled, tokenServiceProviderUrl, and tokenServiceUrl properties.
See Configuring multiple service providers. For information about configuring an MRCP server, see Configuring services with MRCPv2		 N/A
providerSelectionPolicy In the event of service failure, the process by which Voice Gateway changes active Text to Speech service instances when the tenant has multiple providers configured. Voice Gateway switches to the next provider in the list only when a conversation error occurs on the first turn to the Text to Speech service. Once a call is established, Voice Gateway does not switch to another provider in the middle of a call. Set to sequential by default. N/A

Back to the beginning

Properties for the Text to Speech adapter

If you deployed Voice Gateway with the Text to Speech Adapter, define the following properties:

Table 10. JSON properties for the Google Cloud Text-to-Speech API
JSON property Description Related environment variable
config Parameters for the Google Cloud Text-To-Speech API SynthesizeSpeechRequest message. For a full list of parameters, see the SynthesizeSpeechRequest API documentation. See Google Cloud Text-To-Speech (GOOGLE_TTS) variables in the Text to Speech Adapter configuration.
thirdPartyCredentials Contents of a Google Cloud project service account JSON file. GOOGLE_APPLICATION_CREDENTIALS

The credentials property for the tts object

Table 11. Configuration details about the attributes for the credentials JSON property.
Attribute Description Related environment variable
url The url credential for the Text to Speech service API WATSON_TTS_URL
username The username credential for the Text to Speech service WATSON_TTS_USERNAME
password The password credential for the Text to Speech service WATSON_TTS_PASSWORD
apikey The API key, apikey, credential for your Text to Speech service. You can configure connections with Watson services either by using apikey and setting tokenServiceProviderUrl to https://iam.cloud.ibm.com/identity/token, or by using both username and password. Version 1.0.0.6a and later. WATSON_TTS_APIKEY
bearerToken The authentication token that will be used when making requests to the Text To Speech service. Version 1.0.3.0 and later. N/A
tokenAuthEnabled You can enable token authentication by changing the tokenAuthEnabled to true. See Enabling user name and password based token authentication for Watson services. Version 1.0.0.5a and later. WATSON_TTS_TOKEN_AUTH_ENABLED
tokenServiceProviderUrl The value of this credential is the URL of the token authentication service for Text to Speech.Version 1.0.0.5a and later. WATSON_TTS_TOKEN_SERVICE_PROVIDER_URL
tokenServiceUrl The service URL embedded in the token request. Version 1.0.0.5a and later. WATSON_TTS_TOKEN_SERVICE_URL

Back to the beginning

Properties for the reporting object

To enable reporting in a tenant, the reporting server and event type must be defined as JSON properties. The values of the related Docker environment variables are not used.

Table 12. JSON properties for the reporting object
JSON property Description Related environment variable
url Host name of the Splunk HEC server or REST server that receives the events. REPORTING_URL
username Authorization name used for basic authentication. For Splunk HEC, this value can be any string. REPORTING_USERNAME
password Authorization password used for basic authentication. For Splunk HEC, set this value to the Splunk generated token. REPORTING_PASSWORD
cdrEventInd To generate call detail record (CDR) events, define a string that identifies the event as a CDR, such as cdr. The specified value is included in the index field of all CDR events. If a value isn't defined, CDR events are not generated. REPORTING_CDR_EVENT_INDEX
convEventInd To generate Watson Assistant turn events, define a string that identifies the event as a Watson Assistant turn event, such as conv. The specified value is included in the index field of all Watson Assistant turn events. If a value isn't defined, Watson Assistant turn events are not generated. REPORTING_CONVERSATION_EVENT_INDEX
convRequestEventInd A string that identifies the event as a Watson Assistant turn event, such as convRequest. When configured, an event is generated prior to sending a turn request to Watson Assistant. The specified value is included in the index field of all Watson Assistant turn events that are generated prior to a turn request. This variable must be defined to generate Watson Assistant turn events prior to sending a request to Watson Assistant. REPORTING_CONVERSATION_REQUEST_EVENT_INDEX
transcriptionEventInd To generate transcription events, define a string that identifies the event as a transcription event, such as transcription. The specified value is included in the index field of all transcription events. If a value isn't defined, transcription events are not generated. REPORTING_TRANSCRIPTION_EVENT_INDEX
cdrEventSourceType Determines which value to use for the source field in CDR events. The options are conversationID and vgwSessionID. If not specified, it is defined as e164 for a telephone number or sipURI for a SIP URI. Version 1.0.6 and later. REPORTING_CDR_EVENT_SOURCE_TYPE
convEventSourceType Determines which value to use for the source field in Watson Assistant response events. The options are conversationID and vgwSessionID. By default, set to conversationID. Version 1.0.6 and later. REPORTING_CONVERSATION_EVENT_SOURCE_TYPE
convRequestEventSourceType Determines which value to use for the source field in Watson Assistant request events. The options are conversationID and vgwSessionID. If not specified, it is defined as e164 for a telephone number or sipURI for a SIP URI. Version 1.0.6 and later. REPORTING_CONVERSATION_REQUEST_EVENT_SOURCE_TYPE
transcriptionEventSourceType Determines which value to use for the source field in transcription events. The options are conversationID and vgwSessionID. If not specified, it is defined as e164 for a telephone number, conversationID for a Watson Assistant workspace, sipURI for a SIP URI, or sms for SMS messages. Version 1.0.6 and later. REPORTING_TRANSCRIPTION_EVENT_SOURCE_TYPE
cdrCloudant To publish CDR events in an IBM Cloudant noSQL database, provide the authorization information and host information. Version 1.0.0.5d and later. See The cdrCloudant property of the reporting object. N/A
convCloudant To publish Watson Assistant turn events in an IBM Cloudant noSQL database, provide the authorization information and host information. Version 1.0.0.6 and later. See The convCloudant property of the reporting object. N/A
trancriptionCloudant To publish transcription events in an IBM Cloudant noSQL database, provide the authorization information and host information. Version 1.0.0.6 and later. See The transcriptionCloudant property of the reporting object. N/A
maskCallerID Indicates whether ro mask the called ID from the CDR and transcription reports The default value is false. REPORTING_MASK_CALLER_ID

Back to the beginning

The cdrCloudant property of the reporting object

Use the cdrCloudant property to configure publishing Call Detail Record (CDR) turn events to an IBM Cloudant database.

Table 13. Configuration details about the attributes for the cdrCloudant JSON property.
Attribute Description Related environment variable
account The name of the IBM Cloudant account, if it's different from the user name REPORTING_CDR_CLOUDANT_ACCOUNT
url The URL where your IBM Cloudant instance for storing CDR events is hosted. Version 1.0.0.5d and later. REPORTING_CDR_URL
username If you use IBM Cloudant, the user name associated with your account service credentials REPORTING_CDR_CLOUDANT_USERNAME
password If you use IBM Cloudant, the password for your account service credentials REPORTING_CDR_CLOUDANT_PASSWORD
apikey The API key, apikey, credential for your IBM Cloudant service. When you create your IBM Cloudant instance, you can allow access by using either the IAM only option or the Combination of user name/password OR API Key option. You can configure connections with IBM Cloud services either by using apikey and setting url to your IBM Cloudant service URL, such as https://3a14b-15g9-67aa-bluemix.cloudant.com. Or, by using both username and password. Version 1.0.0.7 and later. REPORTING_CDR_CLOUDANT_APIKEY
dbName IBM Cloudant database name REPORTING_CDR_CLOUDANT_DB_NAME
eventInd To generate call detail record (CDR) events for your IBM Cloudant database, define a string that identifies the event as a CDR, such as cdr. The specified value is included in the index field of all CDR events in your database. If a value isn't defined, CDR events are not generated REPORTING_CDR_CLOUDANT_EVENT_INDEX

Back to the beginning

The convCloudant property of the reporting object

Use the convCloudant property to configure publishing Watson Assistant turn events to an IBM Cloudant database.

Table 14. Configuration details about the attributes for the convCloudant JSON property.
Attribute Description Related environment variable
account The name of the IBM Cloudant account, if it's different from the user name REPORTING_CONVERSATION_CLOUDANT_ACCOUNT
url The URL where your IBM Cloudant instance for storing turn events is hosted. Version 1.0.0.5d and later. REPORTING_CONVERSATION_URL
username If you use IBM Cloudant, the user name associated with your account service credentials REPORTING_CONVERSATION_CLOUDANT_USERNAME
password If you use IBM Cloudant, the password for your account service credentials REPORTING_CONVERSATION_CLOUDANT_PASSWORD
apikey The API key, apikey, credential for your IBM Cloudant service. When you create your IBM Cloudant instance, you can allow access by using either the IAM only option or the Combination of user name/password OR API Key option. You can configure connections with IBM Cloud services either by using apikey and setting url to your IBM Cloudant service URL, such as https://3a14b-15g9-67aa-bluemix.cloudant.com. Or, by using both username and password. Version 1.0.0.7 and later. REPORTING_CONVERSATION_CLOUDANT_APIKEY
dbName IBM Cloudant database name REPORTING_CONVESATION_CLOUDANT_DB_NAME
eventInd To generate Watson Assistant turn events for your IBM Cloudant database, define a string that identifies the event as a Watson Assistant turn, such as conversation. The specified value is included in the index field of all Watson Assistant turn events in your IBM Cloudant database. If a value isn't defined, Watson Assistant turn events are not generated. REPORTING_CONVERSATION_CLOUDANT_EVENT_INDEX

Back to the beginning

The transcriptionCloudant property of the reporting object

Use the transcriptionCloudant property to configure publishing transcription events to an IBM Cloudant database.

Table 15. Configuration details about the attributes for the transcriptionCloudant JSON property.
Attribute Description Related environment variable
account The name of the IBM Cloudant account, if it's different from the user name. REPORTING_TRANSCRIPTION_CLOUDANT_ACCOUNT
url The URL where your IBM Cloudant instance for storing transcription events is hosted. Version 1.0.0.5d and later. REPORTING_TRANSCRIPTION_URL
username If you use IBM Cloudant, the user name associated with your account service credentials. REPORTING_TRANSCRIPTION_CLOUDANT_USERNAME
password If you use IBM Cloudant, the password for your account service credentials. REPORTING_TRANSCRIPTION_CLOUDANT_PASSWORD
apikey The API key, apikey, credential for your IBM Cloudant service. When you create your IBM Cloudant instance, you can allow access by using either the IAM only option or the Combination of user name/password OR API Key option. You can configure connections with IBM Cloud services either by using apikey and setting url to your IBM Cloudant service URL, such as https://3a14b-15g9-67aa-bluemix.cloudant.com. Or, by using both username and password. Version 1.0.0.7 and later. REPORTING_TRANSCRIPTION_CLOUDANT_APIKEY
dbName IBM Cloudant database name REPORTING_TRANSCRIPTION_CLOUDANT_DB_NAME
eventInd To generate transcription events for your IBM Cloudant database, define a string that identifies the event as a transcription event, such as transcription. The specified value is included in the index field of all transcription events in your database. If a value isn't defined, transcription events are not generated. REPORTING_TRANSCRIPTION_CLOUDANT_EVENT_INDEX

Back to the beginning

Properties for the sipAuth object

To enable SIP authentication for inbound calls in a tenant, the SIP authentication JSON properties must be defined.

Table 16. JSON properties for the sipAuth object
JSON property Description Related environment variable
username A username to be used for SIP Digest authentication. Version 1.0.4 and later. SIP_AUTH_USERNAME
password A password to be used for SIP Digest authentication. Version 1.0.4 and later. SIP_AUTH_PASSWORD
realm A realm to be used for SIP Digest authentication. Version 1.0.4 and later. SIP_AUTH_REALM
useAuthInt Optional. true/false. Specifies the authentication integrity auth-int quality of protection (QOP) for digest authentication. Digest authentication defines two types of QOP: auth and auth-int. By default, auth is used. If the value is set to true, the auth-int QOP is used, which is the highest level of protection. Version 1.0.4 and later. SIP_AUTH_USE_AUTH_INT

Back to the beginning

Properties for the smsPipe object

To enable SMS messaging integration during a call, you can configure a tenant with information about your SMS Gateway instance. See Integrating SMS Gateway with Voice Gateway.

Table 17. JSON properties for the smsPipe object
JSON property Description Related environment variable
connectTimeout Time in seconds that Voice Gateway waits to establish a socket connection with SMS Gateway. If the time is exceeded, Voice Gateway reattempts to connect with SMS Gateway. If the service still can't be reached, Voice Gateway notifies the conversation service that an SMS message can't be sent. Set to 5 seconds by default Version 1.0.0.6 and later. SMS_GW_CONNECT_TIMEOUT
enableInboundSMS Determines whether an inbound SMS message is expected from a caller. Set to True or False. When set to True, an SMS pipe is created. Otherwise, only outbound SMS messages to a caller are supported. Optional. Version 1.0.0.6 and later. ENABLE_INBOUND_SMS
password SMS Gateway server password for authentication. This needs to be same value as set in password in the SMS Gateway tenant controlCredentials object configuration. See Properties for the controlCredentials object. Version 1.0.0.6 and later. SMS_GW_PASSWORD
username SMS Gateway server username for authentication. This must be set to the same value as the username in the SMS Gateway tenant controlCredentials object configuration. See Properties for the controlCredentials object. Version 1.0.0.6 and later. SMS_GW_USERNAME
expirationInterval Interval in seconds after which an SMS pipe expires. Set to 1200 seconds (20 minutes) by default. Version 1.0.0.6 and later. SMS_PIPE_EXPIRATION_INTERVAL
readTimeout Time in seconds that Voice Gateway waits for a response from SMS Gateway. If the time is exceeded, Voice Gateway reattempts to contact SMS Gateway. If the service still can't be reached, Voice Gateway notifies the conversation service that an SMS message can't be sent. Set to 5 seconds by default. Version 1.0.0.6 and later. SMS_GW_READ_TIMEOUT
tenantPhoneNumber Optional. The tenant phone number, such as "+12222222222". Version 1.0.0.6 and later. TENANT_PHONE_NUMBER
url SMS Gateway server URL to send requests to. For example, http://host:port/sms.gateway/smsPipe, with host and port defined. Version 1.0.0.6 and later. SMS_GW_URL

Back to the beginning

Properties for the outboundCalls object

To enable outbound calling in a tenant, the outbound calling JSON properties must be defined.

Table 18. JSON properties for the outboundCalls object
JSON property Description Related environment variable
enableOutboundCalls Optional. true/false. Enables or disables the outbound call feature. Set to false by default. Version 1.0.2 and later. ENABLE_OUTBOUND_CALLS
statusWebhook Optional. HTTP/HTTPS URL to be used for asynchronous notifications. Version 1.0.2 and later. OUTBOUND_CALLS_STATUS_WEBHOOK
statusWebhookUsername Optional. An username to be used for authentication when sending notifications to a webhook. Version 1.0.2 and later. OUTBOUND_CALLS_STATUS_WEBHOOK_USERNAME
statusWebhookPassword Optional. A password to be used for authentication when sending notifications to a webhook. Version 1.0.2 and later. OUTBOUND_CALLS_STATUS_WEBHOOK_PASSWORD
tenantURI Optional. Tenant SIP/Telephone URI. This value will be used in the From header of an outbound call if no provisioned as part of the REST API call. Version 1.0.2 and later. OUTBOUND_CALLS_TENANT_URI
fromImmutable When the property is set to true, Voice Gateway uses the value configured in the tenantURI JSON property when constructing a From header field for outbound calls instead of the from attribute provided through the REST API. When the property is set to true, the tenantURI property or OUTBOUND_CALLS_TENANT_URI environment variable has to be configured. Version 1.0.4 and later. OUTBOUND_CALLS_FROM_IMMUTABLE
connectTimeout Optional. Time in seconds that Voice Gateway waits to establish a socket connection with the WEB hook. If this value is exceeded, Voice Gateway attempts to reconnect. Set to 5 seconds by default. Version 1.0.2 and later. OUTBOUND_CALLS_STATUS_WEBHOOK_CONNECT_TIMEOUT
readTimeout Optional. Time in seconds that Voice Gateway waits for a response from the WEB hook. If this value is exceeded, Voice Gateway attempts to reconnect. Set to 5 seconds by default. Version 1.0.2 and later. OUTBOUND_CALLS_STATUS_WEBHOOK_READ_TIMEOUT
maxRetryNo Optional. The maximum number of times that Voice Gateway attempts to connect with the WEB hook due to connection failure. Set to 2 by default. Version 1.0.2 and later. OUTBOUND_CALLS_STATUS_WEBHOOK_MAX_RETRY_NUM
username Optional. The user name for the REST API calls authentication. Version 1.0.2 and later. REST_API_USERNAME
password Optional. The password for the REST API call authentication. Version 1.0.2 and later. REST_API_PASSWORD
sipAuth Optional. A JSON object for SIP Digest authentication credentials to be used for outbound calls. Version 1.0.4 and later. See the table below. None
JSON property Description Related environment variable
username A username to be used for SIP Digest authentication in outbound calls. Version 1.0.4 and later. SIP_AUTH_OUTBOUND_USERNAME
password A password to be used for SIP Digest authentication in outbound calls. Version 1.0.4 and later. SIP_AUTH_OUTBOUND_PASSWORD
{: caption="Table 18a. Properties for the sipAuth JSON object for outbound calls" caption-side="top"}

Back to the beginning

Properties of the mediaEncryption object

The mediaEncryption object contains configuration properties for the securing media streams. If a JSON property is not defined, the value of the related Docker environment variable is used. Version 1.0.3.0 and later.

Table 19. Properties for the mediaEncryption object
Property Description Related environment variable
enableSrtpInbound Optional. true or false. Applies to inbound calls. Boolean that enables or disables the use of media encryption for inbound calls for the tenant. If false then it will reject inbound calls requesting encryption. Set to false by default. Version 1.0.4 and later. ENABLE_SRTP_INBOUND
encryptionType Optional. String that determines the type of media encryption to be used. Only SRTP through SDP is supported. The environment variable applies to outbound calls. To disable encryption, set the environment variable to none. The default value is srtp. Version 1.0.3 and later. MEDIA_ENCRYPTION_TYPE
forceMediaEncryption Optional. true or false. Determines whether media encryption MUST be used for inbound and outbound calls. The default value is false. Version 1.0.3 and later. FORCE_MEDIA_ENCRYPTION

Back to the beginning