Contribute in GitHub:

Configuration environment variables for SMS Gateway

You can configure SMS Gateway by defining Docker environment variables. Where you specify the environment variables depends on where you deploy the gateway:

Docker: Set the variables in the docker-compose.yml file that you create when you first deploy SMS Gateway on Docker.
Kubernetes on IBM Cloud: Set the variables as name-value pairs in the deploy.json file that you create as part of deploying SMS Gateway to Kubernetes in IBM Cloud.

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

Multi-tenant JSON configuration: Tenant configuration is specified and stored in a separate JSON file, which is then referenced in the SMS Gateway configuration. Only configuration that isn't related to a tenant, such as the core deployment 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 SMS Gateway JSON configuration.

Core deployment configuration environment variables
Tenant configuration environment variables

Core deployment configuration environment variables

The following tables list the environment variables that you can define to configure the SMS Gateway environment. These values are used across the entire deployment.

General deployment configuration

Table 1. General deployment environment variables
Environment variable	Default value	Description
`MULTI_TENANT_CONFIG_FILE`	N/A	The path to a JSON file for configuring a multi-tenant JSON configuration.

Caching server configuration

Highly available environments require that you set up either a Redis caching server or an IBM WebSphere eXtreme Scale Liberty Deployment (XSLD) caching server, to store session state.

Redis caching server

Table 2. Environment variables for configuring Redis caching server
Environment variable	Default value	Description
`REDIS_ENABLED`	`false`	Set to `true` to enable deploying SMS Gateway with a Redis caching server.
`REDISSON_CONFIG_FILE`	N/A	Provide a path to the file which provides the configuration for the Redis connection.

XSLD caching server

Table 3. Environment variables for configuring XSLD caching server
Environment variable	Default value	Description
`XS_ENABLED`	`false`	Set to `true` to enable deploying SMS Gateway with an XSLD caching server.
`XS_CATALOG_ENDPOINTS`	N/A	A comma-separated list of endpoints for all catalog servers in the data grid, specified in host:port format. For example, `cat01.port.client:4809, 9.123.4.5:4809`.
`XS_USERNAME`	N/A	Important: Must be set to `xsadmin`, which is a build-in administrator credential for the XSLD caching server.
`XS_PASSWORD`	N/A	A password for the XSLD container. If you deploy multiple XSLD containers, the same password must be used for each container.
`XS_TRANSPORT_TYPE`	`TCP/IP`	The transport type for connecting to the XSLD container. Specify `TCP/IP` for unsecured connections or `SSL-Required` if SSL is configured for all catalog servers.

Logging and tracing configuration

Table 4. Environment variables for configuring logging and tracing
Environment variable	Default value	Description
`ENABLE_TRANSCRIPTION_MESSAGES`	`false`	Set to `true` to enable transcription messages. For transcription messages to be logged, the `LOG_LEVEL` environment variable must also be set to `finest`. 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 latency to the Watson Assistant service.
`LOG_LEVEL`	`info`	The level of information that is output to the logs. Valid values from least information to most information are `off`, `fatal`, `severe`, `warning`, `info`, `fine`, `finest`, and `all`. Note that 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, SMS Gateway 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.
`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.
`MASK_CALLER_ID_FROM_MESSAGES`	`false`	To mask caller ID information in the SMS Gateway message logs, set this variable to `true` in the `deploy script` file. By default, the SMS Gateway will show the caller ID information in the message logs. The following example shows masked caller ID information when this variable is set to `true`. `CWSMS0001I: The requested SMS session was created between the tenant and the user. tenantID = +18888888888 userID = ***`

Proxy configuration to the SMS provider

Table 5. Environment variables for configuring the proxy server for the SMS provider
Environment variable	Default value	Description
`SMS_PROXY_TYPE`	`HTTP`	The forward proxy server type for connections to the SMS provider.
`SMS_PROXY_HOST`	N/A	The host name of a forward proxy server for connections to the SMS provider.
`SMS_PROXY_PORT`	N/A	The port of the forward proxy server for connections to the SMS provider.
`SMS_PROXY_USERNAME`	N/A	The user name for the forward proxy server for connections to the SMS provider. Specify this variable only if the proxy server requires authentication.
`SMS_PROXY_PASSWORD`	N/A	The password for the forward proxy server for connections to the SMS provider. Specify this variable only if the proxy server requires authentication.

Proxy configuration to the Watson Assistant service

Table 6. Environment variables for configuring the proxy server for the Watson Assistant service
Environment variable	Default value	Description
`WCS_PROXY_TYPE`	`HTTP`	The forward proxy server type for the connections to the Watson Assistant service.
`WCS_PROXY_HOST`	N/A	The host name of a forward proxy server for connections to the Watson Assistant service.
`WCS_PROXY_PORT`	N/A	The port of the forward proxy server for connections to the Watson Assistant service.
`WCS_PROXY_USERNAME`	N/A	The user name for the forward proxy server for connections to the Watson Assistant service. Specify this variable only if the proxy server requires authentication.
`WCS_PROXY_PASSWORD`	N/A	The password for the forward proxy server for connections to the Watson Assistant service. Specify this variable only if the proxy server requires authentication.

Proxy configuration to the Cloudant

Table 7. Proxy configuration to the Cloudant
Environment variable	Default value	Description
`CLOUDANT_PROXY_USERNAME`	None	Specifies the user name for the forward proxy server for connections to the Cloudant service. Specify this variable only if the proxy server requires authentication.
`CLOUDANT_PROXY_PASSWORD`	None	Specifies the password for the forward proxy server for connections to the Cloudant service. Specify this variable only if the proxy server requires authentication.
`CLOUDANT_PROXY_URL`	None	Specifies the host name and port number of a forward proxy server for connections to the Cloudant service. Example: `http://cloudant-proxy.com:80`

SSL and TLS encryption configuration

Table 8. Environment variables for configuring SSL and TLS encryption
Environment variable	Default value	Description
`SSL_TRUST_STORE_FILE`	Provided by the container Java™ SDK	The file that contains the trusted keys for the outbound SSL connections, including connections to the Watson Assistant service, a service orchestration engine, the SMS provider, or XSLD caching server.
`SSL_TRUST_PASSPHRASE`	N/A	The passphrase that was used to secure the `SSL_TRUST_STORE_FILE` truststore file.
`SSL_TRUST_FILE_TYPE`	`JKS`	The format of the `SSL_TRUST_STORE_FILE`.
`SSL_KEY_STORE_FILE`	N/A	The keystore file that contains the trusted keys for inbound SSL connections.
`SSL_KEY_PASSPHRASE`	N/A	The passphrase that was used to secure the `SSL_KEY_STORE_FILE` keystore file.
`SSL_KEY_FILE_TYPE`	`JKS`	The format of the `SSL_KEY_STORE_FILE`.

Environment variables for configuring the readiness probe

Table 9. Environment variables for configuring the readiness probe
Environment variable	Default value	Description
`SMS_ADMIN_USERNAME`	None	Specifies the user name for the admin to authenticate the readiness probe request.
`SMS_ADMIN_PASSWORD`	None	Specifies the password for the admin to authenticate the readiness probe request.

Tenant configuration environment variables

For single-tenant environments, you can define the following environment variables in the configuration. In multi-tenant JSON configurations, these environment variables are ignored because the properties are defined in a separate JSON file.

General tenant configuration

Table 10. General tenant environment variables
Environment variable	Default value	Description
`TENANT_PHONE_NUMBER`	N/A	For single-tenant deployments, the phone number provisioned from the SMS provider. Use the exact number format that the SMS provider requires. All messages are sent to and from this number.
`ALLOW_SESSION_CREATE_VIA_SMS`	`false`	Whether users can start a new messaging session by sending a message to SMS Gateway. Set to `true` to enable.
`CONVERSATION_FAILED_REPLY_MESSAGE`	`Unable to respond to the SMS message due to an error`	The default response message that is sent to the message receiver if the Watson Assistant service isn't available.
`SMS_PROVIDER_CONNECT_TIMEOUT`	`10000`	The time in milliseconds that SMS Gateway waits to establish a socket connection with the SMS provider. If the SMS provider can't be reached, the transaction fails.
`SMS_PROVIDER_READ_TIMEOUT`	`10000`	The time in milliseconds that SMS Gateway waits for a response from the SMS provider. If the SMS provider can't be reached, the transaction fails.
`SMS_PROVIDER_MAX_RETRY_NUM`	`2`	The maximum number of times that SMS Gateway retries to connect with an SMS service provider if there is a connection failure.
`SMS_PROVIDER_RETRY_INTERVAL`	`0`	The amount of time in milliseconds that SMS Gateway waits between retry attempts to connect with an SMS service provider after a connection failure.
`TIMEOUT_FOR_SESSION`	`3600`	The time in seconds after which the session expires if SMS Gateway does not receive a response from the user.
`WATSON_CONVERSATION_CONNECT_TIMEOUT`	`10000`	The time in milliseconds that SMS Gateway waits to establish a socket connection with the Watson Assistant service. If the service can't be reached, the transaction fails.
`WATSON_CONVERSATION_READ_TIMEOUT`	`5000`	The time in milliseconds that SMS Gateway waits for a response from the Watson Assistant service. If the service can't be reached, the transaction fails.
`WATSON_CONVERSATION_MAX_RETRY_NUM`	`2`	The maximum number of times that SMS Gateway retries to connect with Watson Assistant if there is a connection failure.
`WATSON_CONVERSATION_RETRY_INTERVAL`	`0`	The amount of time in milliseconds that SMS Gateway waits between retry attempts to connect with Watson Assistant after a connection failure.
`NOTIFY_ON_SESSION_TIMEOUT`	`true`	Use this variable if the Watson Assistant or SOE does not handle the expiration of the session(s) for the tenant. For the tenant, set this variable to `false`. By default, the SMS Gateway will notify the Watson Assistant/SOE that the session is expired by sending `smsResponseTimeout` in the text.

Watson Assistant service configuration

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

Table 11. Environment variables for configuring the Watson Assistant service
Environment variable	Default value	Description
`WATSON_CONVERSATION_WORKSPACE_ID`	N/A	The ID of your Watson Assistant workspace. This ID is separate from the service credentials and is listed in the Watson Assistant tool under the workspace details. If you connect to the Watson Assistant service through a service orchestration engine, don't specify this variable.
`WATSON_CONVERSATION_USERNAME`	N/A	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 user name for the SOE if it requires authentication.
`WATSON_CONVERSATION_PASSWORD`	N/A	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`	N/A	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`	`2017-05-26`	The version of the Watson Assistant API to use. SMS Gateway supports Watson Assistant API versions `2017-05-26` and `2016-09-20`.
`WATSON_CONVERSATION_APIKEY`	N/A	The API key, `apikey`, credential for your Watson Assistant service. You can configure connections with Watson services either by using `WATSON_CONVERSATION_APIKEY` and setting `WATSON_CONVERSATION_TOKEN_SERVICE_PROVIDER_URL` to `https://iam.cloud.ibm.com/identity/token`, or configuring `WATSON_CONVERSATION_USERNAME` as `apikey` and `WATSON_CONVERSATION_PASSWORD` with the value of `apikey`. Version 1.0.1.0 and later.
`WATSON_CONVERSATION_TOKEN_AUTH_ENABLED`	`false`	Enables token authentication to the Watson Assistant service. The default is `false`, which enables basic authentication. Version 1.0.1.0 and later.
`WATSON_CONVERSATION_TOKEN_SERVICE_PROVIDER_URL`	`https://gateway.watsonplatform.net/authorization/api/v1/token`	The url where the authentication token will be requested from. Version 1.0.1.0 and later.

SMS provider configuration

Table 12. Environment variables for configuring the SMS provider
Environment variable	Default value	Description
`SMS_PROVIDER_TYPE`	`twilio`	Defines the web API to use to send and receive SMS messages. Currently supported types are `twilio` and `intelepeer`.
`SMS_PROVIDER_EXPLICIT_URL`	N/A	The exact endpoint URL of the SMS provider API for sending messages. For example, specify a RestcommONE URL as `https://cloud.restcomm.com/restcomm/2012-04-24/Accounts/<YourAccountSID>/SMS/Messages.json`, and a Twilio URL as `https://api.twilio.com/2010-04-01/Accounts/<YourAccountSID>/Messages.json`. The URL is used exactly as specified to connect to your SMS provider. This variable supersedes the `SMS_PROVIDER_URL` variable. If you specify this variable, any value specified for `SMS_PROVIDER_URL` is ignored.
`SMS_PROVIDER_URL`	N/A	The shortened endpoint URL for the SMS provider messaging API. For example, on this variable you can specify the RestcommONE URL as `https://cloud.restcomm.com/restcomm/` or a Twilio URL as `https://api.twilio.com`. If you specify this variable, don't also specify `SMS_PROVIDER_EXPLICIT_URL`.
`SMS_PROVIDER_USERNAME`	N/A	The SMS provider user name credential, which typically maps to the account SID.
`SMS_PROVIDER_PASSWORD`	N/A	The SMS provider password credential, which typically maps to the Auth Token.
`SMS_PROVIDER_TOKEN`	N/A	A long-living token that is allocated typically by the CPaaS provider. Configure the token to never expire if possible. It is needed when you set up an IntelePeer-based SMS provider. It is not needed for a Twilio provider.

HTTP Basic authentication configuration for the REST API and SMS provider webhook

Table 13. Environment variables for configuring HTTP Basic authentication
Environment variable	Default value	Description
`CTRL_TENANT_USERNAME`	N/A	A user name that enables basic authentication to use the REST API. When this variable is defined, users must authenticate when they send REST API requests.
`CTRL_TENANT_PASSWORD`	N/A	A password for basic authentication send REST API message requests.
`SMS_WEBHOOK_USERNAME`	N/A	A user name that enables basic authentication for sending message requests from the SMS provider. This value must be provided as part of the webhook URL in the SMS provider configuration.
`SMS_WEBHOOK_PASSWORD`	N/A	A password for basic authentication to send message requests from the SMS provider. This value must be provided as part of the webhook URL in the SMS provider configuration.

Environment variables for reporting events in SMS Gateway

Table 14. SMS Reporting environment variables.
Environment variable	Default value	Description
SMSGW_HOST	"9.42.89.143"	Required to enable reporting. Either the host name or IP address value that is included in the report. In a Kubernetes multi-tenant configuration environment, this value is set to the `podIP` value.
ENABLE_LIMIT_ON_REPORTING_BACKUP_FILES_PER_TENANT	false	Enable or disable a limit on the number of files that can be backed up for the reporting events .
REPORTING_USAGE_MAX_BACKUP_FILES_PER_TENANT	100	When the enable limit property is set to `true`, the default is set to 100 files for usage reports per tenant
REPORTING_TRANSCRIPTION_MAX_BACKUP_FILES_PER_TENANT	1000	When the enable limit property is set to `true`, default is set to 1000 for transcription reports per tenant.
MAX_EVENTS_TO_BATCH	500	The maximum reporting events that can be batched per tenant when publishing once.

Environment variables for publishing reporting events in a REST server

Table 15. Environment variables for connection and event indexes
Environment variable	Example value	Description
`REPORTING_URL`	`https://myresteventserver.ibm.com`	Host name of the Splunk HEC server or HTTP server that receives the events.
`REPORTING_USERNAME`	`14feeb-d29c-48a0-1276bab3`	Authorization name used for basic authentication. For Splunk HEC, this value can be any string.
`REPORTING_PASSWORD`	`e11bea167aed827399d55725c45`	Authorization password used for basic authentication. For Splunk HEC, set this value to the Splunk generated token.
`REPORTING_TRANSCRIPTION_EVENT_INDEX`	`transcription`	A string that identifies the event as a transcription reporting event, such as transcription. The specified value is included in the index field of all transcription reporting events. This variable must be defined to generate transcription reporting events.
`REPORTING_USAGE_EVENT_INDEX`	`usage`	A string that identifies the event as a usage event, such as usage. The specified value is included in the index field of all usage reporting events. This variable must be defined to generate usage reporting events.

Environment variables for publishing reporting events to IBM Cloudant

Transcription reporting event environment variables for IBM Cloudant

Table 16. Variables for publishing transcription reporting events to IBM Cloudant
Environment variable	Example value	Description
`REPORTING_TRANSCRIPTION_CLOUDANT_URL`	`https://transcriptionCloudantURL.com`	A string aggregating the other credential information into a single URL, value is available from the IBM Cloudant instance service credentials.
`REPORTING_TRANSCRIPTION_CLOUDANT_DB_NAME`	`sms-trans-db`	The name of the IBM Cloudant database for your transcription reporting events.
`REPORTING_TRANSCRIPTION_CLOUDANT_ACCOUNT`	`ABC`	For transcription reporting events, a string that defines the IBM Cloudant account name, if the user name and account name are different. To IBM Cloudant, user name and account name are usually the same.
`REPORTING_TRANSCRIPTION_CLOUDANT_USERNAME`	`eb14feeb-d29c-48a0-1276bab37f75`	For transcription reporting events, user name associated with your IBM Cloudant service credentials.
`REPORTING_TRANSCRIPTION_CLOUDANT_PASSWORD`	`eb14feeb-d29c-48a0-1276bab37f75`	For transcription reporting events, password associated with your IBM Cloudant service credentials.
`REPORTING_TRANSCRIPTION_CLOUDANT_API_KEY`	`ObrVygb8Gf0M1Qji4vgqr-nNgHjv`	For transcription reporting events, apikey associated with your IBM Cloudant service credentials.
`REPORTING_TRANSCRIPTION_CLOUDANT_EVENT_INDEX`	`transcription`	A string that identifies the event as a transcription reporting event, such as transcription. The specified value is included in the index field of all transcription reporting events that are reported to your IBM Cloudant database. This variable must be defined to generate transcription reporting events to publish in your database when using single tenant configuration.

Usage reporting event environment variables for IBM Cloudant

Table 17. Variables for publishing usage reporting events to IBM Cloudant
Environment variable	Example value	Description
`REPORTING_USAGE_CLOUDANT_URL`	`https://usageCloudantURL.com`	The URL where your IBM Cloudant instance for storing usage reporting events is hosted.
`REPORTING_USAGE_CLOUDANT_DB_NAME`	`sms-usage-db`	For usage reporting events, user name associated with your IBM Cloudant service credentials.
`REPORTING_USAGE_CLOUDANT_ACCOUNT`	`ABC`	For usage reporting events, account name associated with your IBM Cloud are usually the same.
`REPORTING_USAGE_CLOUDANT_USERNAME`	`eb14feeb-d29c-48a0-1276bab37f75`	For usage reporting events, user name associated with your IBM Cloudant service credentials.
`REPORTING_USAGE_CLOUDANT_PASSWORD`	`eb14feeb-d29c-48a0-1276bab37f75`	For usage reporting events, password associated with your IBM Cloudant service credentials.
`REPORTING_USAGE_CLOUDANT_API_KEY`	`ObrVygb8Gf0M1Qji4vgqr-nNgHjv`	For usage reporting events, apikey associated with your IBM Cloudant service credentials.
`REPORTING_USAGE_CLOUDANT_EVENT_INDEX`	`usage`	A string that identifies the event as a usage event, such as usage. The specified value is included in the index field of all usage reporting events that are reported to your IBM Cloudant database. This variable must be defined to generate usage reporting events to publish in your database when using single tenant configuration.