GitHubContribute in GitHub: Edit online

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

Configuration environment variables for Voice Gateway

You can configure IBM® Voice Gateway by defining Docker environment variables. Where you specify the environment variables depends on where you deploy the Voice Gateway:

These docker-compose.yml and deploy.json files each contain examples of how to configure the environment variables.

Advanced JSON configuration: Tenant configuration is specified and stored in a separate JSON file, which is then referenced from an environment variable in the Voice Gateway Docker configuration. Configuration that isn't related to a tenant, such as server configuration, is specified through the Docker environment variables. For detailed information about which settings to configure in the JSON file, see Configuring tenants in a multi-tenant JSON configuration and Advanced JSON configuration properties.

Important: For any configuration changes to take effect, you must save the configuration file and then redeploy the Voice Gateway.

Although you can define both the SIP Orchestrator and the Media Relay in a single file, each component uses distinct environment variables, which are outlined in the following sections.

SIP Orchestrator environment variables

The following tables list all Docker environment variables that can be used to configure the SIP Orchestrator.

Core deployment configuration

The following environment variables apply across the entire deployment, regardless of how many tenants Voice Gateway is hosting. For both single-tenant environments and multi-tenant JSON configurations, define these variables in the deployment configuration.

General deployment configuration

Table 1. General deployment configuration environment variables for the SIP Orchestrator container
Environment variable Default value Description
MEDIA_RELAY_HOST localhost:8080 Host name of the Media Relay, which the WebSocket server and UDP socket are bound to. Typically set to the Media Relay service name (e.g. vgw.media.relay:8080).
MULTI_TENANT_CONFIG_FILE None The path to a JSON file for configuring a multi-tenant JSON configuration. Version 1.0.0.2 and later.
NOTIFY_CONVERSATION_ON_FILTERED_UTTERANCES false 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_NETWORK_EVENTS false When set to true and a 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_MEDIA_CHANGE false 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.
SEND_ON_FIRST_TURN_TO_CONVERSATION None Contains a comma-separated list of the environment variables that need to be sent to the Watson Assistant service in the first turn request. Use this to set the Cloud Function username and password by sending the private.my_credentials.username and private.my_credentials.password state variables. Versions 1.0.0.6 and later.
SIP_HOST None External IP of the SIP Orchestrator Docker container where the SIP server is listening. Typically set to ${EXTERNAL_IP}.
SIP_PORT 5060 External SIP port for User Datagram Protocol (UDP). Must be set to the same value as the SIP_PORT_TCP environment variable.
SIP_PORT_TCP 5060 External SIP port for Transmission Control Protocol (TCP). Must be set to the same value as the SIP_PORT environment variable.
SIP_PORT_TLS 5061 External SIP port for Transport Layer Security (TLS).
USE_OPTIMAL_CONFIGURATION false 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. Versions 1.0.0.6c and later.
OPTIMAL_CONFIGURATION_VERSION The most recent version Specifies the Voice Gateway version of the optimal configuration settings to be used. For example, 1.0.0.6c. Versions 1.0.0.6.c and later.
JMS_PORT 7276 The unsecured port that the messaging engine listens on to accept the incoming requests. The messaging engine is used for internal communication only. Change the default setting only if a port conflict exists. Versions 1.0.2.2 and later.
JMS_PORT_SSL 7286 The secured port that the messaging engine listens on to accept incoming requests. The messaging engine is used for internal communication only. Change the default setting only if a port conflict exists. Versions 1.0.2.2 and later.

Back to beginning

Logging and tracing configuration

Learn more about configuring logging and tracing in Troubleshooting and support.

Table 2. Environment variables for configuring logging and tracing
Environment variable Default value Description
LOG_LEVEL info (Version 1.0.2 and later) audit (prior to Version 1.0.2) The log level for the SIP Orchestrator. Valid values for 1.0.2 onward, from least information to most information, are: off, severe, warning, info, fine, finest, and all. Prior to 1.0.2, the valid options are: off, severe, warning, audit, fine, finest, and all. When set to fine, finest, or all, the logs might contain sensitive PHI, PII, and PCI DSS data.
LOG_MAX_FILES 5 The maximum number of log files, trace files, and exception summary log files. When this limit is reached, the oldest file is deleted and a new file is created. For example, when this variable is set to 5, the SIP Orchestrator can generate up to 5 message logs, 5 trace logs, and 5 exception summaries.
LOG_MAX_FILE_SIZE 100 The maximum size in megabytes (MB) that a log file can reach before a new file is created.
ENABLE_AUDIT_MESSAGES true Set to false to disable audit messages.
ENABLE_TRANSCRIPTION_AUDIT_MESSAGES false Set to true to enable audit transcription messages. Note that when these messages are enabled, they are printed to the logs and might contain sensitive PHI, PII, and PCI DSS data.
LATENCY_REPORTING_THRESHOLD 1000 Threshold in milliseconds for reporting round-trip Watson Assistant latency.
RELAY_LATENCY_REPORTING_THRESHOLD 1000 Threshold in milliseconds for reporting Media Relay related latencies. Specifically, Text to Speech latency reporting is currently supported.
WLP_SKIP_UMASK false The server sets the log file permissions to deny access to other users when set to false. Set to true to give read access to other users.

Back to beginning

Security and proxy configuration

Learn more about configuring security in Securing Voice Gateway.

Table 3. Environment variables for configuring security
Environment variable Default value Description
PROXY_HOST None Defines the host of the forward proxy server.
PROXY_PORT None Defines the port of the forward proxy server.
PROXY_USERNAME None User name for proxy authentication. Version 1.0.0.3 and later.
PROXY_PASSWORD None Password for proxy authentication. Version 1.0.0.3 and later.
SSL_KEY_TRUST_STORE_FILE JVM trust store The location of the truststore file that contains trusted certificates of certification authorities (CAs). Prior to Version 1.0.2, served as both truststore and keystore. Starting with Version 1.0.2, you can use separate files for truststore and keystore.
SSL_FILE_TYPE JKS The file type of the truststore file. Valid values are JKS, JCEKS, and PKCS12.
SSL_PASSPHRASE changeit The passphrase that is used to secure the truststore file.
SSL_KEY_STORE_FILE SSL_KEY_TRUST_STORE_FILE The location of the keystore file that contains the Voice Gateway certificate, including its private key. If not configured, the SSL_KEY_TRUST_STORE_FILE is served as both keystore and truststore. Version 1.0.2 and later.
SSL_KEY_PASSPHRASE SSL_PASSPHRASE The passphrase that is used to secure the keystore file. Version 1.0.2 and later.
SSL_KEY_FILE_TYPE SSL_FILE_TYPE The file type of the keystore file. Valid values are JKS, JCEKS, and PKCS12. Version 1.0.2 and later.
WHITELIST_FROM_URI None This configuration can be defined at the tenant level. See General tenant configuration.
WHITELIST_TO_URI None When defined, Voice Gateway accepts only calls that contain the specified string (such as a phone number) in the SIP To URI. In Version 1.0.0.3 and later, if the string isn't found in the To header field, Voice Gateway searches the Request-URI value.
TRUSTED_IP_LIST None A comma-separated list of IP addresses. When defined, the Voice Gateway accepts only calls from the specified IP addresses. All communications from other sources are rejected, including calls and OPTIONS messages that are sent to monitor Voice Gateway. Version 1.0.0.1 and later.
WHITELIST_SIPREC_ATTR_NAME None When defined, Voice Gateway accepts only calls that contain the specified attribute in the SIPREC metadata. The attribute value must match to the value specified in the WHITELIST_SIPREC_ATTR_VALUE environment variable. Version 1.0.2 and later.
WHITELIST_SIPREC_ATTR_VALUE None The environment variable is mandatory when WHITELIST_SIPREC_ATTR_NAME is configured. When defined, Voice Gateway accepts only calls that contain the attribute specified in WHITELIST_SIPREC_ATTR_NAME with the value specified in this variable in the SIPREC metadata. Version 1.0.2 and later.

Back to beginning

SIP session configuration

Some of the following environment variables enable values to be passed between Voice Gateway and Watson Assistant using state variables. Learn more in API for self-service agents.

Table 4. Environment variables for configuring SIP session and call flow
Environment variable Default value Description
ACCEPT_TRANSFER_REJECT_CODES None A comma-separated list of the error codes that are treated as a successful response when Voice Gateway processes NOTIFY requests during a call transfer. By default all codes in [200-299] are successful responses. If a response code in a NOTIFY request isn't between [200-299], the transfer process fails. You can extend the list of successful responses by adding this configuration attribute. Version 1.0.0.6 and later.
CUSTOM_SIP_INVITE_HEADER None 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_HEADERS None 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_SESSION_HEADER Call-ID A SIP header field whose value is used as the global session ID. The value of the specified SIP header is used in all audit messages and is passed to Watson Assistant in the vgwSessionID state variable.
CUSTOM_SIPREC_SESSION_FIELD gcid 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 CUSTOM_SIP_SESSION_HEADER environment variable 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.
POST_RESPONSE_TIMEOUT 7000 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.
SESSION_INACTIVITY_TIMEOUT 2 Time in minutes that a session can be inactive. When the timeout expires, the Voice Gateway ends the session.
SEND_PROVISIONAL_RESPONSE true This configuration can be defined at the tenant level. See General tenant configuration.
SEND_SIP_CALL_ID_TO_CONVERSATION false When true, the SIP call ID is passed to Watson Assistant in the vgwSIPCallID state variable.
SEND_SIP_REQUEST_URI_TO_CONVERSATION false When true, the SIP request URI is passed to Watson Assistant in the vgwSIPRequestURI state variable.
SEND_SIP_TO_URI_TO_CONVERSATION false When true, the SIP To URI is passed to Watson Assistant in the vgwSIPToURI state variable.
SEND_SIP_FROM_URI_TO_CONVERSATION false When true, the SIP From URI is passed to Watson Assistant in the vgwSIPFromURI state variable.
CONVERSATION_FAILED_REPLY_MESSAGE Call being transferred to an agent due to a technical problem. Good bye. Message streamed to the caller when a call is being transferred / disconnected due to a failure of one of the Watson services. You might want to change the default message if no default target is configured.
CONVERSATION_FAILED_REPLY_AUDIO_URL None 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 CONVERSATION_FAILED_REPLY_MESSAGE message.
TRANSFER_DEFAULT_TARGET None 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_FAILED_REPLY_MESSAGE Call transfer to an agent failed. Please try again later. Good bye. Message streamed to the caller if the call transfer fails when DISCONNECT_CALL_ON_TRANSFER_FAILURE is set to true.
TRANSFER_FAILED_REPLY_AUDIO_URL None 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 TRANSFER_FAILED_REPLY_MESSAGE message.
DISCONNECT_CALL_ON_TRANSFER_FAILURE true 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. Must be enabled for `Version 1.0.0.2 and later. See Transferring upon failure.
PUT_CALLER_ON_HOLD_ON_TRANSFER true This configuration can be defined at the tenant level. See General tenant configuration.
CMR_HEALTH_CHECK_FAIL_ERR_CODE None The error code to send in a SIP OPTIONS response when the Voice Gateway is temporarily unavailable. By default, OPTION messages are ignored when a failure occurs.
DISCONNECT_CALL_ON_NO_USER_INPUT_TURN_COUNT -1 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.

Back to beginning

Tenant configuration

The following environment variables define tenant-specific configuration. Define these variables in the deployment configuration only for single-tenant deployments to Docker and IBM Cloud Kubernetes Service. For deployments that use JSON configurations, tenant configuration is instead defined in the separate JSON file. For detailed information, see Configuring tenants in a multi-tenant JSON configuration.

General tenant configuration

Table 5. General tenant configuration environment variables
Environment variable Default value Description
DISABLE_STT_DURING_PLAYBACK false Determines whether to pause all speech-to-text processing while playing back audio, which disables speech barge-in for the duration that the audio is played. When set to true, Voice Gateway pauses speech-to-text processing before it starts a playback transaction. When the transaction completes, Voice Gateway resumes speech-to-text processing. For more information, see Configuring barge-in. Version 1.0.0.4c and later.
FINAL_UTTERANCE_TIMEOUT None 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.
PUT_CALLER_ON_HOLD_ON_TRANSFER true Determines whether to place the caller on hold while the call is transferred. Some service providers, such as the AT&T® 8YY service, fail transfers if this setting is enabled. If the call anchor point puts both call legs on hold during a transfer, set this variable to false. Version 1.0.0.3 and later.
SEND_PROVISIONAL_RESPONSE true Determines whether Voice Gateway sends a 180 Ringing response while it processes an incoming call, before it sends a 200 OK or error response. When set to false, Voice Gateway does not send the 180 Ringing response and sends only the 200 OK or error response. Version 1.0.0.3 and later.
SEND_SIPREC_METADATA_TO_STT false Possible values are true and false. When set to true, the SIPREC metadata will be sent to STT when a session is established. Version 1.0.3.0 and later.
TENANT_TYPE agentAssist for agent assist and SIPREC sessions, selfService for self service sessions. Possible values include agentAssist, selfService, and continuousRecognition. 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.
WHITELIST_FROM_URI None When defined, Voice Gateway accepts only calls that contain the specified strings (such as a phone number) in the SIP From URI. You can define multiple strings in a comma-separated list.

Back to beginning

SMS Pipe deployment configuration for SMS Gateway integration

Table 6. SMS Gateway integration environment variables
Environment variable Default value Description
ENABLE_INBOUND_SMS False 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.
SMS_GW_URL None SMS Gateway server URL to send requests to, such as https://SMShost:port/sms.gateway/smsPipe. For example, https://10.10.10.10:9043/sms.gateway/smsPipe Version 1.0.0.6 and later.
SMS_GW_USERNAME None 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_PASSWORD None 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_PIPE_EXPIRATION_INTERVAL 1200 Interval in seconds after which an SMS pipe expires. Set to 1200 seconds (20 minutes) by default. Version 1.0.0.6 and later.
TENANT_PHONE_NUMBER None Optional. The tenant phone number, such as "+12222222222". If undefined and the tenant phone number isn't defined in the smsActSendSMS action, Voice Gateway uses the called tenant phone number by default. Version 1.0.0.6 and later.
WEB_HOOK_HOST None The IP address or hostname of the Voice Gateway server where SMS Gateway sends SMS messages. Typically, this is the node IP address associated with the local Voice Gateway server instance. This IP address or hostname must be accessible from your SMS Gateway instance. Version 1.0.0.6 and later.
SMS_GW_CONNECT_TIMEOUT 5 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. Version 1.0.0.6 and later.
SMS_GW_READ_TIMEOUT 5 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. Version 1.0.0.6 and later.

Back to beginning

Voice Gateway web interface configuration

Table 7. Environment variables to configure Voice Gateway web interface integration
Environment variable Default value Description
HTTP_HOST localhost By default, HTTP_HOST is set to localhost to protect the web interface and to limit access to only the local host. When you need to allow inbound SMS messages or the REST API, set to * so the HTTP interface is accessible from an external server. If you set HTTP_HOST to *, you can protect the web interface by setting ADMIN_PASSWORD and ADMIN_USER so that only the configured, authenticated user has access to it.
HTTP_PORT 9080 The external HTTP port. Version 1.0.0.6 and later.
HTTPS_PORT 9443 The external HTTPS port. Version 1.0.0.6 and later.
ADMIN_USERNAME None User name used to protect the web interface exposed by HTTP_HOST. Version 1.0.0.6 and later.
ADMIN_PASSWORD None Password used to protect the we interface exposed by HTTP_HOST. Version 1.0.0.6 and later.

Back to beginning

Reporting event configuration

Learn more about configuring Voice Gateway to generate reporting events for analytics in Reporting events.

Table 8. Environment variables for configuring reporting events
Environment variable Default value Description
REPORTING_URL None Host name of the Splunk HEC server or HTTP server that receives the events.
REPORTING_USERNAME None Authorization name used for basic authentication. For Splunk HEC, this value can be any string.
REPORTING_PASSWORD None Authorization password used for basic authentication. For Splunk HEC, set this value to the Splunk generated token.
REPORTING_CDR_EVENT_INDEX None A string that identifies the event as a call detail record (CDR), such as cdr. The specified value is included in the index field of all CDR events. This variable must be defined to generate CDR events.
REPORTING_CONVERSATION_EVENT_INDEX None 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. This variable must be defined to generate Watson Assistant turn events.
REPORTING_CONVERSATION_REQUEST_EVENT_INDEX None 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 sending a request to Watson Assistant. This variable must be defined to generate Watson Assistant turn events prior to sending a request to Watson Assistant.
REPORTING_TRANSCRIPTION_EVENT_INDEX None 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. This variable must be defined to generate transcription events. Version 1.0.0.2 and later.
REPORTING_CDR_EVENT_SOURCE_TYPE None Determines which value to use for the source field in CDR events. The options are conversationID for conversation ID and vgwSessionID for global session identifier. 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_EVENT_SOURCE_TYPE conversationID Determines which value to use for the source field in Watson Assistant response events. The options are conversationID and vgwSessionID. Version 1.0.6 and later.
REPORTING_CONVERSATION_REQUEST_EVENT_SOURCE_TYPE None 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_TRANSCRIPTION_EVENT_SOURCE_TYPE None Determines which value to use for the source field in transcription events. The opptions are conversationID and vgwSessionID. If not specified, it is defined as e164 for a telephone number, conversation ID for a Watson Assistant workspace, or sipURI for a SIP URI, or sms for SMS messages. Version 1.0.6 and later.
REPORTING_CDR_CLOUDANT_URL None The URL where your IBM Cloudant instance for storing CDR events is hosted. Version 1.0.0.5d and later.
REPORTING_CDR_CLOUDANT_ACCOUNT None For CDR event reporting, a string that defines your IBM Cloudant account name, if the user name and account name are different. In IBM Cloudant, user name and account name are usually the same. Version 1.0.0.5d and later.
REPORTING_CDR_CLOUDANT_USERNAME None For CDR event reporting, user name associated with your IBM Cloudant credentials. Version 1.0.0.5d and later.
REPORTING_CDR_CLOUDANT_PASSWORD None For CDR event reporting, password associated with your IBM Cloudant credentials. Version 1.0.0.5d and later.
REPORTING_CDR_CLOUDANT_APIKEY None The API key, apikey, credential for your IBM Cloudant service. Configure REPORTING_CDR_CLOUDANT_APIKEY with your API key and and set REPORTING_CDR_CLOUDANT_URL to your IBM Cloudant service URL, https://3a14b-15g9-67aa-bluemix.cloudant.com. Otherwise, you can configure REPORTING_CDR_CLOUDANT_USERNAME and REPORTING_CDR_CLOUDANT_PASSWORD. 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. For information about API keys, see IBM Cloudant: API keys. Version 1.0.0.7 and later.
REPORTING_CDR_CLOUDANT_DB_NAME None The name of the IBM Cloudant database for your CDR events. Version 1.0.0.5d and later.
REPORTING_CDR_CLOUDANT_EVENT_INDEX None A string that identifies the event as a call detail record (CDR), such as cdr. The specified value is included in the index field of all CDR events that are reported to your IBM Cloudant database. This variable must be defined to generate CDR events to publish in your database. Version 1.0.0.5d and later.
REPORTING_TRANSCRIPTION_CLOUDANT_ACCOUNT None For transcription event reporting, a string that defines the IBM Cloudant account name, if the user name and account name are different. In IBM Cloudant, user name and account name are usually the same. Version 1.0.0.6 and later.
REPORTING_TRANSCRIPTION_CLOUDANT_URL None The URL where your IBM Cloudant instance for storing transcription events is hosted. Version 1.0.0.5d and later.
REPORTING_TRANSCRIPTION_CLOUDANT_USERNAME None For transcription event reporting, user name associated with your IBM Cloudant credentials. Version 1.0.0.6 and later.
REPORTING_TRANSCRIPTION_CLOUDANT_PASSWORD None For transcription event reporting, password associated with your IBM Cloudant credentials. Version 1.0.0.6 and later.
REPORTING_TRANSCRIPTION_CLOUDANT_APIKEY None The API key, apikey, credential for your IBM Cloudant service. Configure REPORTING_TRANSCRIPTION_CLOUDANT_APIKEY with your API key and and set REPORTING_TRANSCRIPTION_CLOUDANT_URL your IBM Cloudant service URL, https://3a14b-15g9-67aa-bluemix.cloudant.com. Otherwise, you can configure REPORTING_TRANSCRIPTION_CLOUDANT_USERNAME and REPORTING_TRANSCRIPTION_CLOUDANT_PASSWORD. 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. For information about how to find your service credentials, see IBM Cloudant: API keys. Version 1.0.0.7 and later.
REPORTING_TRANSCRIPTION_CLOUDANT_DB_NAME None The name of the IBM Cloudant database for your transcription events. Version 1.0.0.6 and later.
REPORTING_TRANSCRIPTION_CLOUDANT_EVENT_INDEX None 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 that are reported to your IBM Cloudant database. This variable must be defined to generate transcription events to publish in your database. Version 1.0.0.6 and later.
REPORTING_CONVERSATION_CLOUDANT_ACCOUNT None For Watson Assistant turn event reporting, a string that defines the IBM Cloudant account name, if the user name and account name are different. In IBM Cloudant, user name and account name are usually the same. Version 1.0.0.6 and later.
REPORTING_CONVERSATION_CLOUDANT_URL None The URL where your IBM Cloudant instance for storing conversation turn events is hosted. Version 1.0.0.5d and later.
REPORTING_CONVERSATION_CLOUDANT_USERNAME None For Watson Assistant turn event reporting, user name associated with your IBM Cloudant credentials. Version 1.0.0.6 and later.
REPORTING_CONVERSATION_CLOUDANT_PASSWORD None For Watson Assistant turn event reporting, password associated with your IBM Cloudant credentials. Version 1.0.0.6 and later.
REPORTING_CONVERSATION_CLOUDANT_APIKEY None The API key, apikey, credential for your IBM Cloudant service. Configure REPORTING_CONVERSATION_CLOUDANT_APIKEY with your API key and and set REPORTING_CONVERSATION_CLOUDANT_URL to your IBM Cloudant service URL, https://3a14b-15g9-67aa-bluemix.cloudant.com. Otherwise, you can configure REPORTING_CONVERSATION_CLOUDANT_USERNAME and REPORTING_CONVERSATION_CLOUDANT_PASSWORD. 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. For information about how to find your service credentials, see IBM Cloudant: API keys. Version 1.0.0.7 and later.
REPORTING_CONVERSATION_CLOUDANT_DB_NAME None The name of the IBM Cloudant database for your Watson Assistant turn events. Version 1.0.0.6 and later.
REPORTING_CONVERSATION_CLOUDANT_EVENT_INDEX None A string that identifies the event as a Watson Assistant turn event, such as conversation. The specified value is included in the index field of all turn events that are reported to your IBM Cloudant database. This variable must be defined to generate transcription events to publish in your database. Version 1.0.0.6 and later.
REPORTING_MASK_CALLER_ID false Indicates whether to mask the caller ID from the CDR and transcription reports.

Back to beginning

Watson Assistant service and service orchestration engine configuration

The IBM Watson™ Assistant service provides the core artificial intelligence for self-service agents. Rather than connecting directly to Watson Assistant, you can integrate a service orchestration engine to expand the agent's capabilities. Learn more in Connecting through a service orchestration engine.

All watsonplatform.net URLs are deprecated. Override default values that refer to these URLs with the correct values.

Table 9. Environment variables for configuring Watson Assistant or service orchestration engine
Environment variable Default value Description
WATSON_CONVERSATION_WORKSPACE_ID None Workspace ID for the Watson Assistant API. For information about how to find the workspace ID, see Developing your application in the Watson Assistant documentation.
WATSON_CONVERSATION_USERNAME None The username credential for your Watson Assistant service. Note that this value isn't your IBM Cloud user name. For information about how to find your service credentials, see Service credentials for Watson services.

For service orchestration engines, use this variable to specify the username for the SOE if it requires authentication.
WATSON_CONVERSATION_PASSWORD None The password credential for your Watson Assistant service. Note that this value isn't your IBM Cloud password. For information about how to find your service credentials, see Service credentials for Watson services.

For service orchestration engines, use this variable to specify the password to the SOE if it requires authentication.
WATSON_CONVERSATION_URL None The url credential for the Watson Assistant service API, such as https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}. For information about how to find your service credentials, see Service credentials for Watson services.

For service orchestration engines, use this variable to specify the exact URL to the SOE.
WATSON_CONVERSATION_API_VERSION v1 if WATSON_CONVERSATION_WORKSPACE_ID is configured. v2 if WATSON_ASSISTANT_ID is configured. The version of Watson Assistant API to use. Voice Gateway supports Watson Assistant API version 1 and version 2. Version 2 is only supported in Voice Gateway version 1.0.1 and later.
WATSON_CONVERSATION_USE_STATELESS_API 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. This option applies only when WATSON_CONVERSATION_API_VERSION=v2. 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_APIKEY None The API key, apikey, credential for your Watson Assistant service. For information about how to find your service credentials, see Service credentials for Watson services. To configure connections with Watson services, you must either configure both WATSON_CONVERSATION_USERNAME and WATSON_CONVERSATION_PASSWORD, or configure WATSON_CONVERSATION_APIKEY. If you configure an API key, the default value for WATSON_CONVERSATION_TOKEN_SERVICE_PROVIDER_URL changes to https://iam.cloud.ibm.com/identity/token. Version 1.0.0.6a and later.
WATSON_CONVERSATION_READ_TIMEOUT 5 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.
WATSON_CONVERSATION_CONNECT_TIMEOUT 5 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. Version 1.0.0.3 and later.
WATSON_CONVERSATION_CONNECTION_KA_ENABLED true 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 re-use 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_TOKEN_AUTH_ENABLED false Enables token authentication to the Watson Assistant service. The default is false, which enables basic authentication. See Enabling token authentication for Watson services. Version 1.0.0.5a and later.
WATSON_CONVERSATION_TOKEN_SERVICE_PROVIDER_URL https://gateway.watsonplatform.net/authorizatioNonepi/v1/token The url where the authentication token will be requested from. If an API key is configured using WATSON_CONVERSATION_APIKEY, the default value for WATSON_CONVERSATION_TOKEN_SERVICE_PROVIDER_URL becomes https://iam.cloud.ibm.com/identity/token. Version 1.0.0.5a and later.
WATSON_CONVERSATION_TOKEN_SERVICE_URL None The service URL that is embedded in the token request, such as https://iam.cloud.ibm.com/identity/token. Version 1.0.0.5a and later.
If token authentication is enabled, but WATSON_CONVERSATION_TOKEN_SERVICE_URL is undefined, the value for WATSON_CONVERSATION_URL is used by default.
WATSON_ASSISTANT_ID None Watson Assistant ID for the Watson Assistant version 2 API. The assistant ID is used only by the Watson Assistant version 2 API. Version 1.0.1 and later

Back to beginning

Watson Virtual Agent configuration

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.

Table 10. Environment variables for configuring Virtual Agent
Environment variable Default value Description
WATSON_VA_URL None The url credential for the Watson Virtual Agent API. Version 1.0.0.2 and later.
WATSON_VA_BOT_ID None The bot_id credential for the Watson Virtual Agent API. Version 1.0.0.2 and later.
WATSON_VA_CLIENT_ID None The authentication key for the X-IBM-Client-Id header field for API calls to Watson Virtual Agent. Version 1.0.0.2 and later.
WATSON_VA_CLIENT_SECRET None The authentication key for the X-IBM-Client-Secret header field for API calls to Watson Virtual Agent. Version 1.0.0.2 and later.

Back to beginning

Outbound calls environment variables

The following table lists the environment variables you can use to configure outbound calls:

Table 11. Environment variables for configuring outbound calling
Environment variable Default value Description
REST_API_USERNAME None Optional. Username for REST API calls authentication. Version 1.0.2 and later.
REST_API_PASSWORD None Optional. Password for REST API calls authentication. Version 1.0.2 and later.
OUTBOUND_CALLS_TENANT_URI None Optional. Tenant SIP / Tel URI. Set in a From header field of an outbound call in case the respective field isn't provided through the REST API. Version 1.0.2 and later.
OUTBOUND_CALLS_FROM_IMMUTABLE false When the property is set to true, Voice Gateway uses the value configured in the OUTBOUND_CALLS_TENANT_URI environment variable 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 OUTBOUND_CALLS_TENANT_URI environment variable has to be configured. Version 1.0.4 and later.
OUTBOUND_CALLS_ENFORCE_ROUTE None Must be a valid SIP or SIPS URI. When configured, Voice Gateway sends all outbound calls to the URI specified in that environment variable. It acts as an outbound proxy as defined in RFC 3261. Version 1.0.4 and later.
ENABLE_OUTBOUND_CALLS False Optional. True/False. Enables or disables the outbound calls feature. When set to 'False,' REST API calls are rejected with a 403 error response. Version 1.0.2 and later.
OUTBOUND_CALLS_STATUS_WEBHOOK None Optional. HTTP / HTTPS URL for asynchronous notifications. Version 1.0.2 and later.
OUTBOUND_CALLS_STATUS_WEBHOOK_USERNAME None Optional. Username to be used for authentication when sending notifications to a webhook. Version 1.0.2 and later.
OUTBOUND_CALLS_STATUS_WEBHOOK_PASSWORD None Optional. Password to be used for authentication when sending notifications to a webhook. Version 1.0.2 and later.
OUTBOUND_CALLS_STATUS_WEBHOOK_CONNECT_TIMEOUT 5 Optional. Time in seconds that Voice Gateway waits to establish a socket connection with the WEB hook. If the time is exceeded, Voice Gateway attempts to reconnect. Version 1.0.2 and later.
OUTBOUND_CALLS_STATUS_WEBHOOK_READ_TIMEOUT 5 Optional. Time in seconds that Voice Gateway waits for a response from the WEB hook. If the time is exceeded, Voice Gateway attempts to reconnect. Version 1.0.2 and later.
OUTBOUND_CALLS_STATUS_WEBHOOK_MAX_RETRY_NUM 2 Optional. The maximum number of times that Voice Gateway attempts to connect with the WEB hook due to connection failure. Version 1.0.2 and later.

Outbound calls SIP authentication environment variables

Table 12. Environment variables for configuring SIP authentication for outbound calls
Environment variable Default value Description
SIP_AUTH_OUTBOUND_USERNAME None Optional. A username to be used for SIP Digest authentication in outbound calls. Version 1.0.4 and later.
SIP_AUTH_OUTBOUND_PASSWORD None Optional. A password to be used for SIP Digest authentication in outbound calls. Version 1.0.4 and later.

Back to beginning

Inbound calls SIP authentication environment variables

The following table lists the environment variables that you can use to configure inbound calls with SIP authentication:

Table 13. Environment variables for configuring SIP authentication for inbound calls
Environment variable Default value Description
SIP_AUTH_USERNAME None Optional. A username to be used for SIP Digest authentication. Version 1.0.4 and later.
SIP_AUTH_PASSWORD None Optional. A password to be used for SIP Digest authentication. Version 1.0.4 and later.
SIP_AUTH_REALM None A realm to be used for SIP Digest authentication. Version 1.0.4 and later.
SIP_AUTH_USE_AUTH_INT false 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.

Back to beginning

Monitoring REST API environment variables

The following table lists the environment variables that you can use to configure monitoring:

Table 14. Environment variables for configuring the monitoring REST API
Environment variable Default value Description
METRICS_SAMPLING_INTERVAL 600 Optional. The interval in seconds when the metrics are to be updated. Version 1.0.2 and later.
ENABLE_METRICS_AUTH false Optional. Indicates whether to enable authentication for the monitoring endpoint. When set to true, the endpoint is protected with credentials. Use the ADMIN_USERNAME and ADMIN_PASSWORD environment variables to configure the user name and password for authentication. Version 1.0.2 and later.

Back to beginning

Media Relay environment variables

The following tables list all Docker environment variables that can be used to configure the Media Relay.

Core deployment configuration

The following environment variables apply across the entire deployment, regardless of how many tenants Voice Gateway is hosting. For both single-tenant environments and multi-tenant JSON configurations, define these variables in the deployment configuration.

General deployment configuration

Table 15. General deployment configuration environment variables for the Media Relay container
Environment variable Default value Description
MEDIA_RELAY_WS_HOST 0.0.0.0 The IP address or host name that the Media Relay listens to requests from the SIP Orchestrator on. The Media Relay binds to the WebSocket server at this address.
MEDIA_RELAY_WS_PORT 8080 The port that the SIP Orchestrator uses to open a WebSocket session.
RTP_UDP_PORT_RANGE '16384-16394' Port range for UDP, set as a String. Note: If RTP_UDP_PORT_RANGE is set to a low port range with a high number of workers, you may see errors in the MediaRelay logs (CWSMR0101E error codes).
SDP_ADDRESS localhost The address to use in the Answer SDP for SIP.
CLUSTER_WORKERS 0 Number of cluster workers to spawn. When set to 0, a number of workers equal to one less than the number of CPUs is spawned.
MAX_SESSIONS 0 The maximum number of simultaneous media sessions that the Media Relay handles before it stops the creation of new media sessions. If this variable isn't defined, it's set to the number of ports defined on the RTP_UDP_PORT_RANGE variable.
WATSON_STT_STREAMING_FRAME_SIZE 100 Specifies the frame size in milliseconds of the audio that is sent to the Speech to Text service. Version 1.0.0.5 and later.
STT_TRACK_LATENCY false 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.
RTP_CODECS None A comma-separated list of codecs that the Media Relay supports during an RTP session. For example, to only use PCMU, set it as RTP_CODECS=PCMU. Only PCMU, PCMA, and G722 are supported. Version 1.0.0.6a and later.
EXTERNAL_AUDIO_TRANSFORMS None A comma-separated list of websocket URLs that point to external codec services that will be used for encoding and decoding the audio of a call. For example, to connect to a codec service on localhost that's listening on port 3500, set it as EXTERNAL_AUDIO_TRANSFORMS=ws://localhost:3500. For more information, see External Codec Services. Version 1.0.3.0 and later.

Back to beginning

Logging and tracing configuration

Learn more about configuring logging and tracing in Troubleshooting and support.

Table 16. Environment variables for configuring logging and tracing
Environment variable Default value Description
MEDIA_RELAY_LOG_LEVEL INFO The log level. Set the log level to INFO, DEBUG, or TRACE. Note that when set to DEBUG or TRACE, the logs might contain sensitive PHI, PII, and PCI DSS data.
MEDIA_RELAY_LOG_ROTATION_FILE_COUNT 10 The number of Media Relay log files to keep in rotation for the Bunyan logging module.
MEDIA_RELAY_LOG_ROTATION_PERIOD 1d The period at which the Bunyan logging module rotates the log files. By default, log files are rotated on a 24-hour basis.
RTP_PACKET_LOSS_REPORTING_THRESHOLD 1000 The number of lost packets that are detected before the Media Relay logs a warning message. Version 1.0.0.1 and later.

Back to beginning

Recording configuration

Learn more about configuring call recording in Recording call audio.

Table 17. Environment variables for configuring recording
Environment variable Default value Description
ENABLE_RECORDING false Set to true to enable call audio recording on the Media Relay. Note that recordings might contain sensitive PHI, PII, and PCI DSS data.
STEREO_RECORDING false Set to true to record the call audio into left and right channels. Audio from the Watson Text To Speech server or the call center agent is recorded to the left channel, and audio from the caller is recorded to the right channel. To enable stereo recording, ENABLE_RECORDING must also be set to true. Version 1.0.0.4 and later.

Back to beginning

RTCP configuration

Learn more about monitoring RTP audio streaming by using the RTP Control Protocol (RTCP) in Monitoring RTP audio streams by using RTCP.

Table 18. Environment variables for configuring RTCP
Environment variable Default value Description
ENABLE_RTCP false Set to true to enable use of the RTP Control Protocol (RTCP) to monitor RTP audio streaming. When RTCP is enabled, warnings that were generated during the call and network summaries with audio stream statistics are included in call detail record (CDR) reporting events. Version 1.0.0.5 and later.
RTCP_MAX_JITTER_THRESHOLD 30 The maximum jitter in milliseconds between received RTP packets before a warning is triggered. If this maximum is exceeded, Voice Gateway issues a warning for the affected inbound or outbound audio stream. Version 1.0.0.5 and later.
RTCP_MAX_PACKET_LOSS_THRESHOLD 5 The maximum percentage of lost packets before a warning is triggered. If this maximum is exceeded, Voice Gateway issues a warning for the affected inbound or outbound audio steam. Version 1.0.0.5 and later.

Back to beginning

Security and proxy configuration

Learn more about configuring security in Securing Voice Gateway.

Table 19. Environment variables for configuring security
Environment variable Default value Description
PROXY_TYPE http Defines the protocol to use for the proxy connection.
PROXY_HOST None Host of the forward proxy server.
PROXY_PORT None Port of the forward proxy server.
PROXY_USERNAME None User name for proxy authentication.
PROXY_PASSWORD None Password for proxy authentication.
WATSON_STT_ENABLE_PROXY true Indicates whether connections to the Watson Speech to Text service are routed through the configured proxy. Version 1.0.0.1a and later.
WATSON_TTS_ENABLE_PROXY true Indicates whether connections to the Watson Text to Speech service are routed through the configured proxy. Version 1.0.0.1a and later.
MUSIC_ON_HOLD_ENABLE_PROXY false Indicates whether connections to any music on hold or one-time audio URLs are routed through the configured proxy. Version 1.0.0.1a and later.
SSL_CLIENT_PKCS12_FILE None The location of a PKCS #12 file that contains cryptographic information, such as private keys, certificates, and trusted certificate authorities.
SSL_CLIENT_PASSPHRASE None The passphrase that was used to secure the PKCS #12 file.
SSL_CLIENT_CA_CERTIFICATE_FILE None The location of a PEM file that contains trusted certificate authorities and self-signed certificates.

Back to beginning

Tenant configuration

The following environment variables define tenant-specific configuration. Define these variables in the deployment configuration only for single-tenant deployments to Docker and IBM Cloud Kubernetes Service. For multi-tenant JSON configurations, tenant configuration is instead defined in the separate JSON file. For detailed information, see Configuring tenants in a multi-tenant JSON configuration.

Watson Speech to Text service configuration

All watsonplatform.net URLs are deprecated. Override default values that refer to these URLs with the correct values.

Table 20. Environment variables for configuring the Speech to Text service
Environment variable Default value Description
WATSON_STT_USERNAME None The username credential for the Watson Speech to Text service. Note that this value isn't your IBM Cloud user name. For information about how to find your service credentials, see Service credentials for Watson services.
WATSON_STT_PASSWORD None The password credential for the Watson Speech to Text service. Note that this value isn't your IBM Cloud password. For information about how to find your service credentials, see Service credentials for Watson services.
WATSON_STT_URL https://stream.watsonplatform.net/speech-to-text/api The url credential for the Watson Speech to Text service API. For information about how to find your service credentials, see Service credentials for Watson services.
WATSON_STT_TOKEN_AUTH_ENABLED false Enables token authentication to the Speech to Text service. The default is false, which enables basic authentication. See Enabling user name and password based token authentication for Watson services. Version 1.0.0.5a and later.
WATSON_STT_TOKEN_SERVICE_PROVIDER_URL https://stream.watsonplatform.net/authorizatioNonepi/v1/token The url where the authentication token will be requested from. If an API key is configured using WATSON_STT_APIKEY, the default value for WATSON_STT_TOKEN_SERVICE_PROVIDER_URL becomes https://iam.cloud.ibm.com/identity/token. Version 1.0.0.5a and later.
WATSON_STT_TOKEN_SERVICE_URL https://stream.watsonplatform.net/speech-to-text/api This is the service URL that is embedded in the token request. Version 1.0.0.5a and later.
WATSON_STT_APIKEY None The API key, apikey, credential for your Speech to Text service. For information about how to find your service credentials, see Service credentials for Watson services. To configure connections with Watson services, you must either configure both WATSON_STT_USERNAME and WATSON_STT_PASSWORD, or configure WATSON_STT_APIKEY. If you configure an API key, the default value for WATSON_STT_TOKEN_SERVICE_PROVIDER_URL changes to https://iam.cloud.ibm.com/identity/token. Version 1.0.0.6a and later.
WATSON_STT_MODEL en-US_NarrowbandModel The Watson Speech to Text model. By default, only narrowband models are supported. The default narrowband model is best for offline decoding of telephone speech. To use a broadband model in Version 1.0.0.4 and later, see Enabling broadband audio.
WATSON_STT_BASE_MODEL_VERSION None A version of the Speech to Text model to use, such as en-US_NarrowbandModel.v2017-11-15. Set this variable only if you want to use a specific version of the model instead of the latest version. For more information, see Base model version. Replaced WATSON_STT_MODEL_VERSION in 1.0.6 release.
WATSON_STT_OPTOUT None Set to true to opt out of saving data that passes through the Speech to Text service on Watson servers.
WATSON_STT_MAXALTERNATIVES None The number of speech recognition alternatives to return from the Speech to Text service. By default, the value from the Speech to Text service is used.
WATSON_STT_CONFIDENCE_SCORE_THRESHOLD 0 Confidence threshold of messages from the Speech to Text service. Messages with a confidence score that is under the threshold will not be used as a response. The default value of 0 means that all responses will be used. The recommended values are between 0 and 1.
WATSON_STT_MODEL_CUSTOMIZATION_ID None Used to set a custom language model for recognition. Deprecated Version 1.0.1.0 and later, use WATSON_STT_LANGUAGE_CUSTOMIZATION_ID instead.
WATSON_STT_LANGUAGE_CUSTOMIZATION_ID None Used to set a custom language model for recognition. Version 1.0.1.0 and later.
WATSON_STT_PROFANITY_FILTER None Set to true to filter profanity on the transcripts that come from the Watson Speech to Text service. By default, the value from the Speech to Text service is used.
WATSON_STT_SMART_FORMATTING true Indicates whether dates, times, series of digits and numbers, phone numbers, currency values, and Internet addresses are to be converted into more readable, conventional representations in the final transcript of a recognition request.
WATSON_STT_CONNECTION_TIMEOUT 5 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_REQUEST_TIMEOUT 5 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_DISABLE_FIRST_TURN_BARGE_IN false Set this value to true to disable speech barge-in on the first conversation turn. Version 1.0.2.0 and later.
BARGE_IN_RESUME false 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 WATSON_STT_CONFIDENCE_SCORE_THRESHOLD variable. For more information, see Configuring barge-in. Version 1.0.0.5 and later.
ECHO_SUPPRESSION false Set to true 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.

Back to beginning

Configure the following environment variables only if you want to use a broadband model. For more information, see Enabling broadband audio.

Table 21. Environment variables for configuring broadband audio for the Speech to Text service
Environment variable Default value Description
WATSON_STT_BAND_PREFERENCE narrowband Defines which audio band to prefer when negotiating audio codecs in the session. Set to broadband to use broadband audio when possible. Version 1.0.0.4 and later.
WATSON_STT_BROADBAND_MODEL None The Speech to Text model. Version 1.0.0.4 and later.
WATSON_STT_BROADBAND_BASE_MODEL_VERSION None A version of the Speech to Text model to use, such as en-US_NarrowbandModel.v2017-11-15. Set this variable only if you want to use a specific version of the model instead of the latest version. For more information, see Base model version. Replaced WATSON_STT_BROADBAND_MODEL_VERSION in 1.0.6 release.
WATSON_STT_BROADBAND_OPTOUT None Set to true to opt out of saving data that passes through the Speech to Text service on Watson servers. Version 1.0.0.4 and later.
WATSON_STT_BROADBAND_MAXALTERNATIVES None The number of speech recognition alternatives to return from the Speech to Text service. By default, the value from the Speech to Text service is used. Version 1.0.0.4 and later.
WATSON_STT_BROADBAND_MODEL_CUSTOMIZATION_ID None Used to set a custom language model for recognition. Version 1.0.0.4 and later. Deprecated Version 1.0.1.0 and later, use WATSON_STT_BROADBAND_LANGUAGE_CUSTOMIZATION_ID instead.
WATSON_STT_BROADBAND_LANGUAGE_CUSTOMIZATION_ID None Used to set a custom language model for recognition. Version 1.0.1.0 and later.
WATSON_STT_BROADBAND_PROFANITY_FILTER None Set to true to filter profanity on the transcripts that come from the Speech to Text service. By default, the value from the Speech to Text service is used. Version 1.0.0.4 and later.
WATSON_STT_BROADBAND_SMART_FORMATTING None Indicates whether dates, times, series of digits and numbers, phone numbers, currency values, and Internet addresses are to be converted into more readable, conventional representations in the final transcript of a recognition request. Version 1.0.0.4 and later.

Back to beginning

Watson Text to Speech service configuration

All watsonplatform.net URLs are deprecated. Override default values that refer to these URLs with the correct values.

Table 22. Environment variables for configuring the Text to Speech service
Environment variable Default value Description
WATSON_TTS_USERNAME None The username credential for your Watson Text to Speech service. Note that this value isn't your IBM Cloud user name. For information about how to find your service credentials, see Service credentials for Watson services.
WATSON_TTS_PASSWORD None The password credential for your Watson Text to Speech service instance. Note that this value isn't your IBM Cloud password. For information about how to find your service credentials, see Service credentials for Watson services.
WATSON_TTS_URL https://stream.watsonplatform.net/text-to-speech/api The url credential for the Watson Text to Speech service API. For information about how to find your service credentials, see Service credentials for Watson services.
WATSON_TTS_TOKEN_AUTH_ENABLED false Enables token authentication to the Text to Speech service. The default is false, which enables basic authentication. See Enabling user name and password based token authentication for Watson services. Version 1.0.0.5a and later.
WATSON_TTS_TOKEN_SERVICE_PROVIDER_URL https://stream.watsonplatform.net/authorizatioNonepi/v1/token The URL where the token is requested from. If an API key is configured using WATSON_TTS_APIKEY, the default value for WATSON_TTS_TOKEN_SERVICE_PROVIDER_URL becomes https://iam.cloud.ibm.com/identity/token. Version 1.0.0.5a and later.
WATSON_TTS_TOKEN_SERVICE_URL https://stream.watsonplatform.net/text-to-speech/api This is the service URL that is embedded in the token request. Version 1.0.0.5a and later.
WATSON_TTS_APIKEY None The API key, apikey, credential for your Text to Speech service. For information about how to find your service credentials, see Service credentials for Watson services. To configure connections with Watson services, you must either configure both WATSON_TTS_USERNAME and WATSON_TTS_PASSWORD, or configure WATSON_TTS_APIKEY. If you configure an API key, the default value for WATSON_TTS_TOKEN_SERVICE_PROVIDER_URL changes to https://iam.cloud.ibm.com/identity/token. Version 1.0.0.6a and later.
WATSON_TTS_VOICE en-US_AllisonVoice Voice used by the Text to Speech service.
WATSON_TTS_OPTOUT None Set to true to opt out of saving data that passes through the Text to Speech service on Watson servers. To opt out, the Media Relay sends the X-Watson-Learning-Opt-Out parameter on HTTP Rest calls to the service.
WATSON_TTS_JITTER_BUFFER_DELAY 200 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_MODEL_CUSTOMIZATION_ID None Used to set a custom voice model for text to speech.
WATSON_TTS_CONNECTION_TIMEOUT 5 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_REQUEST_TIMEOUT 5 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.
TTS_CACHE_TIME_TO_LIVE 0 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 by setting the vgwExcludeFromTTSCache API state variable. Note that responses that contain sensitive PHI, PII, and PCI DSS data will be cached unless you explicitly exclude them from caching. The default value of 0 means that responses are not cached. Version 1.0.0.1 and later.

Back to beginning

Media stream security configuration

Table 23. Environment variables for configuring media stream security
Environment variable Default value Description
ENABLE_SRTP_INBOUND false Optional. A Boolean that allows media encryption to be used for inbound calls. If the environment variable is set to false, all inbound calls that request media protection are denied. The environment variable applies to inbound calls.
MEDIA_ENCRYPTION_TYPE srtp Optional. The type of media encryption to use for Real-time Transport Protocol (RTP) packets. Secure Real-time Transport Protocol (SRTP) is supported through Session Description Protocol (SDP) only. The srtp value is the value for this support. The environment variable applies to outbound calls. To disable encryption, set the environment variable to none.
FORCE_MEDIA_ENCRYPTION false Optional. A Boolean that forces media encryption to be used for all calls. If the environment variable is set to true, all inbound calls that do not request media protection are denied. Additionally, all outbound calls are made with media protection requested. The environment variable applies to inbound and outbound calls.

Back to beginning

Speech to Text Adapter environment variables

General deployment configuration

The following table lists the environment variables you can use to configure the Speech to Text Adapter container:

Table 24. Speech to Text Adapter environment variables
Environment variable Default value Description
PORT 4000 The port to listen on for requests from the Media Relay.
LOG_LEVEL debug The log level for the Speech to Text Adapter. Set the log level to info, debug, or trace. Note that when set to debug or trace, the logs might contain sensitive PHI, PII, and PCI DSS data.
GOOGLE_APPLICATION_CREDENTIALS None The path to the service account credentials related to the Google Cloud project. This file must be mounted on a volume in the stt.adapter container.
GOOGLE_SPEECH_RECOGNITION_CONFIG None The path to a JSON file that defines values for the Google Cloud Speech RecognitionConfig API.
GOOGLE_SPEECH_LANGUAGE_CODE en-US Set the expected language of the audio from the caller as a BCP-47 language tag, such as en-US. This variable is analogous to the language_code field of the Cloud Speech RecognitionConfig API.

Note that for your self-service agent to be fully functional in a language, it must also be supported by the other services that are integrated with Voice Gateway. See Supported languages for details.
GOOGLE_SPEECH_MAX_ALTERNATIVES None The number of speech recognition alternatives to return from the Google Cloud Speech API. This variable is analogous to the max_alternatives field of the Cloud Speech RecognitionConfig API.
GOOGLE_SPEECH_PROFANITY_FILTER None Set to true to filter profanity on the transcripts that come from the Google Cloud Speech API. This variable is analogous to the profanity_filter field of the Cloud Speech RecognitionConfig API.

Back to beginning

Security and proxy configuration

Learn more about configuring security in Securing Voice Gateway.

Table 25. Environment variables for configuring Speech to Text Adapter security
Environment variable Default value Description
STT_ADAPTER_USERNAME None A user name that enables basic authentication on the Speech To Text Adapter for connections coming from Voice Gateway.
STT_ADAPTER_PASSWORD None A password for basic authentication on the Speech To Text Adapter for connections coming from Voice Gateway.
PROXY_TYPE http Defines the protocol to use for the proxy connection, either http or https.
PROXY_HOST None Host of the forward proxy server.
PROXY_PORT None Port of the forward proxy server.
PROXY_USERNAME None User name for proxy authentication.
PROXY_PASSWORD None Password for proxy authentication.
SSL_SERVER_PKCS12_FILE None The location of a PKCS #12 file that contains cryptographic information, such as private keys, certificates, and trusted certificate authorities. Specify this environment variable to secure the connection from the Media Relay.
SSL_SERVER_PASSPHRASE None The passphrase that was used to secure the PKCS #12 file.

Back to beginning

Text to Speech Adapter environment variables

General deployment configuration

The following table lists the environment variables you can use to configure the Text to Speech Adapter container:

Table 26. Text To Speech Adapter environment variables
Environment variable Default value Description
PORT 4000 The port to listen on for requests from the Media Relay.
LOG_LEVEL debug The log level for the Text To Speech Adapter. Set the log level to info, debug, or trace. Note that when set to debug or trace, the logs might contain sensitive PHI, PII, and PCI DSS data.
GOOGLE_APPLICATION_CREDENTIALS None The path to the service account credentials related to the Google Cloud project. This file must be mounted on a volume in the tts.adapter container.
GOOGLE_TTS_VOICE_LANGUAGE_CODE en-US Set the expected language of the voice as a BCP-47 language tag, such as en-US. This variable is analogous to the language_code field of the Cloud Text-To-Speech VoiceSelectionParams API.

Note that for your self-service agent to be fully functional in a language, it must also be supported by the other services that are integrated with Voice Gateway. See Supported languages for details.
GOOGLE_TTS_VOICE_NAME None The name of the voice. This variable is analogous to the name field of the Cloud Text-To-Speech VoiceSelectionParams.
GOOGLE_TTS_VOICE_SSML_GENDER None The preferred gender of the voice. This variable is analogous to the ssml_gender field of the Cloud Text-To-Speech VoiceSelectionParams.
GOOGLE_TTS_AUDIO_CONFIG_SPEAKING_RATE None Optional speaking rate/speed. This variable is analogous to the speaking_rate field of the Cloud Text-To-Speech AudioConfig.
GOOGLE_TTS_AUDIO_CONFIG_PITCH None Optional speaking pitch. This variable is analogous to the pitch field of the Cloud Text-To-Speech AudioConfig.
GOOGLE_TTS_AUDIO_GAIN_DB None Optional volume gain (in dB) of the normal native volume supported by the specific voice. This variable is analogous to the volume_gain_db field of the Cloud Text-To-Speech AudioConfig.

Back to beginning

Security and proxy configuration

Learn more about configuring security in Securing Voice Gateway.

Table 27. Environment variables for configuring Text To Speech Adapter security
Environment variable Default value Description
TTS_ADAPTER_USERNAME None A user name that enables basic authentication on the Text To Speech Adapter for connections coming from Voice Gateway.
TTS_ADAPTER_PASSWORD None A password for basic authentication on the Text To Speech Adapter for connections coming from Voice Gateway.
PROXY_TYPE http Defines the protocol to use for the proxy connection, either http or https.
PROXY_HOST None Host of the forward proxy server.
PROXY_PORT None Port of the forward proxy server.
PROXY_USERNAME None User name for proxy authentication.
PROXY_PASSWORD None Password for proxy authentication.
SSL_SERVER_PKCS12_FILE None The location of a PKCS #12 file that contains cryptographic information, such as private keys, certificates, and trusted certificate authorities. Specify this environment variable to secure the connection from the Media Relay.
SSL_SERVER_PASSPHRASE None The passphrase that was used to secure the PKCS #12 file.

Back to beginning