Contribute in GitHub:

API for SMS Gateway

You can control SMS Gateway behavior and the flow of an SMS session by exchanging actions and state variables with the IBM Watson™ Assistant service. Action tags initiate actions that SMS Gateway takes during a conversation session, and state variables are sent by SMS Gateway to indicate session characteristics.

Action tags

To initiate actions in SMS Gateway, you can define action tags in a Watson Assistant dialog node in JSON format on the output property. For each action, define an smsAction property, which contains two parts: a command property, and an optional parameter property where you can define attributes for commands that require them.

For example, when a node that contains the following action is triggered, it sets the session timeout to 200 seconds.

{
  "output": {
    "smsAction": {
      "command": "setSessionTimeoutCount",
      "parameters":{
            "count": 200
       }
    }
  }
}

When a node that contains smsActSendMedia is triggered, MMS messaging is enabled.

{
  "output": {
    "smsAction": {
          "command": "smsActSendMedia",
          "parameters":{
            "mediaURL": [
              "https://exampleonly.com/media/l4JyRqcDU93S334KQ/first.gif",
              "https://exampleonly.com/media/tK9wGsGc72LcznCSeU/second.gif"
            ]
         }  
      }
   }   
}

The following table lists the actions that you can specify in the Watson Assistant dialog and any attributes that you can define for each action.

Table 1. Actions that you can initiate from Watson Assistant
Action command	Description	Attributes
`setSessionTimeoutCount`	Updates the session timeout	`count`: Time in seconds
`smsActForceNoInputTurn`	Forces a new turn in the conversation without waiting for input from the user. SMS Gateway sends a message request with `smsNoInputTurn` in the text field so that you can map this request to an intent in your dialog.	None
`smsActSetConversationConfig`	Applies a set of parameters to configure a Watson Assistant workspace or service orchestration engine. Learn more in Dynamically configuring the Watson Assistant service or service orchestration engine.	All of the following parameters are supported. For more information, see Advanced JSON configuration properties for SMS Gateway. `url` `workspaceID` `username` `password` `convApiVersion` `apikey` `tokenAuthEnabled` `tokenServiceProviderURL` `conversationFailedReplyMessage` `convConnectTimeout` `convReadTimeout` `convMaxRetryNo` `convRetryInterval`
`terminateSession`	Terminates the associated session	N/A
`smsActSendMedia`	Enables MMS messaging	`mediaURL`: Specifies a JSON array of publicly accessible media URLs that are sent to the user.
`smsActSetDisambiguationConfig`	Applies a set of parameters for the `suggestion` response type. Learn more in Handling Watson Assistant response types. Version 1.0.6 and later.	`prefixText`: the text that will be prepended to each label in a Watson Assistant `suggestion` response.
`smsActSetOptionsConfig`	Applies a set of parameters for the `options` response type. Learn more in Handling Watson Assistant response types. Version 1.0.6 and later.	`prefixText`: the text that will be prepended to each label in a Watson Assistant `option` response.

State variables sent by SMS Gateway

To indicate a change of state in the SMS session, SMS Gateway sends context variables each message request to Watson Assistant. Because the Watson Assistant dialog is stateless, all state is maintained at SMS Gateway between exchanges with Watson Assistant. This means that for each Watson Assistant turn within a chat session, the context section is passed to Watson Assistant, processed or updated by the dialog, and received back from Watson Assistant.

For example, for a basic turn in the SMS session that uses only required values, the SMS Gateway sends the following context object.

{
  "context": {
    "smsTenantPhoneNumber": "+12345556789",
    "smsUserPhoneNumber": "+18765554321",
    "smsSessionID": "a23de67h-e527-40d5-a867-5c0ce9e72d0d"
  }
}

The following state variables are sent from SMS Gateway in the message request. The smsTenantPhoneNumber, smsUserPhoneNumber, smsUserData, and smsSessionTimeoutCount values are pulled directly from the session REST API.

Table 2. Context variables sent by SMS Gateway
State variable	Description
`smsTenantPhoneNumber`	The SMS Gateway tenant phone number that the user is messaging.
`smsUserPhoneNumber`	The phone number of the user that is exchanging messages with SMS Gateway.
`smsUserData`	Data in JSON format to be passed verbatim to the service orchestration engine or Watson Assistant service. This variable is sent only if the session is started from the SMS Gateway tenant and the data is sent through the REST API.
`smsSessionTimeoutCount`	The session timeout value. This variable is sent only if the timeout value is defined through the REST API.
`smsError`	When SMS Gateway fails to send an SMS message, this variable contains details about the error that occurred.
`smsSessionID`	The GUID for the related SMS Gateway session.
`smsMedia`	The `arraylist` of `mediaURL` and corresponding `mediaContentType`. This context variable is cleared at the end of each conversation turn.

Text keywords

Certain events trigger SMS Gateway to send a text keyword in the message request to Watson Assistant. You can use these text keywords for further processing in a service orchestration engine or analysis.

The following table lists the exact text value that is sent from SMS Gateway and the event that triggers it.

Table 3. Text values sent by SMS Gateway
Text value	Event
`smsError`	Sent if an error occurs when sending an outbound SMS message to the SMS provider.
`smsResponseTimeout`	Sent if a session timeout occurs when the user does not respond in time that is set by `smsSessionTimeoutCount`.

Variables set in the Watson Assistant dialog

You can set the following state variables within the Watson Assistant dialog to modify the SMS Gateway behavior. If a variable that has a related configuration environment variable isn't set, the value from the related environment variable is used.

Table 4. Variables set in the Watson Assistant dialog
State variable name	Expected value	Description	Related environment variable
`smsConversationResponseTimeout`	Time in ms	The amount of time in milliseconds that SMS Gateway waits to receive a response from the Watson Assistant service. If the time is exceeded, SMS Gateway reattempts to contact the Watson Assistant service. If the service still can't be reached, the SMS response fails. Version 1.0.0.5a and later.	`WATSON_CONVERSATION_READ_TIMEOUT`

Handling Watson Assistant response types

Learn about how various Watson Assistant response types are supported in the SMS Gateway. For more information, see Handling Watson Assistant response types.