GitHubContribute in GitHub: Edit online

copyright: years: 2017, 2021 lastupdated: "2021-04-14"

Advanced JSON configuration properties for SMS Gateway

You can use JSON configuration properties to define tenant configuration for one or more tenants. By using configuration properties JSON objects, you can customize configurations for your different SMS Gateway tenants.

Important: The multi-tenant JSON configuration properties are used instead of the Docker environment variables in the core SMS Gateway configuration. The related environment variables are shown only to map the functionality of each variable.

Example JSON configuration file

For example, the following JSON configures a tenant for Car insurance assistance at the number +1-234-555-6789 which has enabled basic HTTP authentication for the SMS provider webhook and sending requests from the SMS Gateway REST API. The code example also has the configuration for another tenant at +1-876-555-4321 for Homeowners insurance assistance, whose details are not shown.

{
     "tenants": [
      {
        "tenantPhoneNumber": "+12345556789",
        "description": "Car insurance assistance",
        "allowSessionCreateViaSMS": "false",
        "timeoutForSession": "3600",
        "conversationFailedReplyMessage": "We can't respond to your message.",
        "convReadTimeout": "30000",
        "convConnectTimeout": "30000",
        "smsProviderConnectTimeout": "30000",
        "smsProviderReadTimeout": "30000",
        "smsProviderMaxRetryNo" : "2",
        "smsProvideRetryInterval" : "2000",
        "convMaxRetryNo" : "2",
        "convRetryInterval" : "2000",
        "conversation": {
          "url": "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}",
          "username": "9h7f54cb-d9ed-46b3-8492-e9a9bf555021",
          "apikey": "{apikey}",
          "tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token"
        },
        "smsProvider": {
          "url": "https://api.twilio.com",
          "username": "A23de67h0236e5e7c7f1ead4499h7f54cb",
          "password": "9h7f54cb3b1d3736e19ac64aa23de67h"
        },
        "reporting":{
          "url": "http://myresteventserver.ibm.com/",
          "username": "myRestAdmin",
          "password": "myRestTokenOrPassword",
          "transcriptionEventInd": "transcription",
          "usageEventInd" : "usage",
          "usageCloudant": {
            "url": "http://usageCloudantURL.bluemix.cloudant.com/",
            "dbName": "myDBName",
            "username": "myAdmin",
            "password": "myTokenOrPassword",
            "apiKey": "myApiKey",
            "usageEventInd": "usage"
          },
          "transcriptionCloudant": {
            "url": "http://transcriptionCloudantURL.bluemix.cloudant.com/",
            "dbName": "myDBName",
            "username": "myAdmin",
            "password": "myTokenOrPassword",
            "apiKey": "myApiKey",
            "eventInd": "transcription"
          },
       },
        "webHookCredentials": {
          "username": "myUserName",
          "password": "p4ssw0rd"
        },
        "controlCredentials": {
          "username": "myRESTAPIuser",
          "password": "Pa55w0rd"
        }
      },
     {
        "tenantPhoneNumber": "+18765554321",
        "description": "Homeowners insurance assistance",
      }    	
      ]
    }

Required general tenant properties

Table 1. Required JSON properties for SMS Gateway tenants.
JSON property Description Related environment variable
tenantPhoneNumber The phone number provisioned from the SMS provider. Use the exact number format that the SMS provider requires. TENANT_PHONE_NUMBER
conversation The connection configuration for your Watson Assistant service instance. See Properties for the conversation Object N/A
smsProvider A JSON object of configuration properties for the SMS provider. See Properties for the conversation Object N/A

Back to the beginning

Properties for the conversation object

The conversation object configures the connection to Watson Assistant. The object must be defined for each tenant.

Table 2. 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
convApiVersion The version of the Watson Assistant API to use. The default value is 2017-05-26. WATSON_CONVERSATION_API_VERSION
apikey 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_APIKEY
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
tokenAuthEnabled 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_AUTH_ENABLED
tokenServiceProviderURL The url where the authentication token will be requested from. Version 1.0.1.0 and later. WATSON_CONVERSATION_TOKEN_SERVICE_PROVIDER_URL

Back to the beginning

Properties for the smsProvider object

The required smsProvider object configures the connection to the SMS provider. The object must be defined for each tenant, and the properties have no default value.

Table 3. JSON properties for the smsProvider object
JSON property Description Related environment variable
smsProviderType Type of SMS Provider, which dictates the web APIs to use for sending and receiving SMS messages. The supported types are twilio and intelepeer. Default is twilio. SMS_PROVIDER_TYPE
explicitURL The exact endpoint URL of the SMS provider API for sending messages. For example, specify 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 property supersedes the url property. If you specify this property, any value specified for url is ignored.		 SMS_PROVIDER_EXPLICIT_URL
url The shortened endpoint URL for the SMS provider messaging API. For example, on this variable you can specify the Twilio URL as https://api.twilio.com.

If you specify this property, don't also specify explicitURL.		 SMS_PROVIDER_URL
username The SMS provider user name credential. For Twilio, the user name credential maps to the Account SID. SMS_PROVIDER_USERNAME
password The SMS provider password credential. For Twilio, this value maps to the Auth Token. SMS_PROVIDER_PASSWORD

Back to the beginning

Optional tenant properties

You can define the optional following configuration properties for each tenant individually.

Table 4. Optional JSON properties for configuring a tenant
JSON property Default Description Related environment variable
allowSessionCreateViaSMS false Whether users can start a new messaging session by sending a message to SMS Gateway. Set to true to enable. ALLOW_SESSION_CREATE_VIA_SMS
timeoutForSession 3600 The time in seconds after which the session expires if SMS Gateway does not receive a response from the user. TIMEOUT_FOR_SESSION
notifyOnSessionTimeout 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. NOTIFY_ON_SESSION_TIMEOUT
conversationFailedReplyMessage SystemError reaching Voice Agent on failure. The default response message that is sent to the message receiver if Watson Assistant isn't available. CONVERSATION_FAILED_REPLY_MESSAGE
convConnectTimeout 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_CONNECT_TIMEOUT
convReadTimeout 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_READ_TIMEOUT
convMaxRetryNo 2 The maximum number of times that SMS Gateway retries to connect with Watson Assistant if there is a connection failure. WATSON_CONVERSATION_MAX_RETRY_NUM
convRetryInterval 0 The amount of time in milliseconds that SMS Gateway waits between retry attempts to connect with Watson Assistant after a connection failure. WATSON_CONVERSATION_RETRY_INTERVAL
smsProviderConnectTimeout 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_CONNECT_TIMEOUT
smsProviderReadTimeout 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_READ_TIMEOUT
smsProviderMaxRetryNo 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_MAX_RETRY_NUM
smsProvideRetryInterval 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. SMS_PROVIDER_RETRY_INTERVAL
reportingConnectTimeout 5000 For publishing reporting to a REST server, the time in milliseconds that SMS Gateway waits to establish a socket connection with the reporting server. If the server can't be reached, the reports are backed up and sent again later. REPORTING_CONNECTION_TIMEOUT
reportingReadTimeout 5000 For publishing reporting to a REST server, the time in milliseconds that SMS Gateway waits for a response from the reporting server. If the server can't be reached, the reports are backed up and sent again later. REPORTING_RECEIVE_TIMEOUT

Back to the beginning

Properties for publishing reporting events

Properties for publishing reporting events to a REST server

The following values can be added to your deployment file to customize how your SMS Gateway publishes reporting events to a REST server.

Table 5. JSON properties for reporting to a Rest server
JSON property Description Related environment variable
url Host name of the Splunk HEC server or HTTP 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
transcriptionEventInd 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 reporting events. This variable must be defined to generate transcription reporting events. REPORTING_TRANSCRIPTION_EVENT_INDEX
usageEventInd 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. REPORTING_USAGE_EVENT_INDEX

Back to the beginning

Properties for publishing transcription reporting events to IBM Cloudant

The following values can be added to your deployment file to customize how your SMS Gateway publishes reporting events to IBM Cloudant.

Table 6. JSON properties for publishing transcription reporting events to IBM Cloudant
JSON property Description Related environment variable
url A string aggregating the other credential information into a single URL, value will be available from the IBM Cloudant instance service credentials. REPORTING_TRANSCRIPTION_CLOUDANT_URL
dbName The name of the IBM Cloudant database for your transcription reporting events. REPORTING_TRANSCRIPTION_CLOUDANT_DB_NAME
account For transcription reporting events, 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. REPORTING_TRANSCRIPTION_CLOUDANT_ACCOUNT
username For transcription reporting events, user name associated with your IBM Cloudant service credentials. REPORTING_TRANSCRIPTION_CLOUDANT_USERNAME
password For transcription reporting events, password associated with your IBM Cloudant service credentials. REPORTING_TRANSCRIPTION_CLOUDANT_PASSWORD
apikey For transcription reporting events, apikey associated with your IBM Cloudant service credentials. REPORTING_TRANSCRIPTION_CLOUDANT_API_KEY
eventInd 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 reporting events that are reported to your IBM Cloudant database. This variable must be defined to generate transcription reporting events. REPORTING_TRANSCRIPTION_CLOUDANT_EVENT_INDEX

Back to the beginning

Properties for publishing usage reporting events to IBM Cloudant

Table 7. JSON properties for publishing usage reporting events to IBM Cloudant
JSON property Description Related environment variable
url The URL where your IBM Cloudant instance for storing usage reporting events is hosted. REPORTING_USAGE_CLOUDANT_URL
dbName For usage reporting events, user name associated with your IBM Cloudant service credentials. REPORTING_USAGE_CLOUDANT_DB_NAME
account For usage reporting events, account name associated with your IBM Cloud are usually the same. REPORTING_USAGE_CLOUDANT_ACCOUNT
username For usage reporting events, user name associated with your IBM Cloudant service credentials. REPORTING_USAGE_CLOUDANT_USERNAME
password For usage reporting events, password associated with your IBM Cloudant service credentials. REPORTING_USAGE_CLOUDANT_PASSWORD
apikey For usage reporting events, apikey associated with your IBM Cloudant service credentials. REPORTING_USAGE_CLOUDANT_API_KEY
eventInd 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. REPORTING_USAGE_CLOUDANT_EVENT_INDEX

Back to the beginning

Properties for the webHookCredentials object

The optional webHookCredentials object enables HTTP basic authentication for the SMS provider webhook to SMS Gateway.

Table 8. JSON properties for the webHookCredentials object
JSON property Description Related environment variable
username 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_USERNAME
password 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. SMS_WEBHOOK_PASSWORD

Back to the beginning

Properties for the controlCredentials object

The optional controlCredentials object enables HTTP basic authentication for sending requests from the SMS Gateway REST API.

Table 9. JSON properties for the controlCredentials object
JSON property Description Related environment variable
username 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_USERNAME
password A password for basic authentication send REST API message requests. CTRL_TENANT_PASSWORD

Back to the beginning