Contribute in GitHub:

Integrating with SMS Gateway

You can configure IBM® Voice Gateway to integrate with SMS Gateway to enable SMS messaging between customers and a voice agent during a voice call.

Voice Gateway integrates with SMS Gateway in an ongoing voice call with a caller. After receiving an smsActSendSMS action from Watson Assistant, Voice Gateway uses the REST APIs provided by SMS Gateway to create a logical channel. This channel, called an SMS pipe, contains a unique reference for that caller and the tenant agent number along with context related to the SMS exchange.

The Voice Gateway uses the SMS pipe reference to send the outbound message provided in the smsActSendSMS request to SMS Gateway. Next, this message is forwarded to the caller to initiate an SMS messaging interaction. When the caller responds to Voice Gateway with an SMS message, the inbound message is sent to SMS Gateway, which forwards it to Voice Gateway. When the voice call completes or when Voice Gateway uses the REST API to delete the pipe, it ends the SMS messaging interaction.

SMS messages can be exchanged between Voice Gateway and a caller by using the SMS Gateway integration to route SMS messages to Voice Gateway through the SMS Pipe.

See Using the REST API to control SMS sessions to find code examples and descriptions of the SMS Gateway REST API operations.

Before you begin

Deploy your Voice Gateway instances. See Getting Started with Voice Gateway.

Important: The SMS Gateway integration requires that you create and configure the required Watson services in your Voice Gateway deployment.
Deploy your SMS Gateway instances. See Getting Started with SMS Gateway.

Configuring integration between SMS Gateway and Voice Gateway

To create the integration with SMS Gateway, you must complete the following steps.

Configure your Voice Gateway deployment
Add the vgwActSendSMS action to your Watson Assistant dialog
Add the required intents to handle the inbound messages to your Watson Assistant dialog
Integrate security certificates for your Voice Gateway and SMS Gateway servers

Configuring your Voice Gateway deployment

SMS Gateway integration is supported in both single tenant deployments and JSON configured multi-tenant Voice Gateway deployments. For both deployments, WEB_HOOK_HOST and HTTP_HOST are required configuration variables in your deployment configuration file.

Multi-tenant JSON configurations: The following example shows how to enable Voice Gateway to integrate with SMS Gateway for a particular tenant. See Configuring tenants in a multi-tenant JSON configuration.

{
  "smsPipe": {
      "url": "https://host:port/sms.gateway/smsPipe",
      "username": "U53rnam3",
      "password": "pa55c0d3",
      "tenantPhoneNumber": "+12345556789",
      "readTimeout": 5,
      "connectTimeout": 2,
      "expirationInterval": 1200,
      "enableInboundSMS": true
    }
  }

Single tenant deployment: The following example shows how to enable Voice Gateway to integrate with SMS Gateway for a particular tenant. See Configuration environment variables for Voice Gateway.

      - SMS_GW_URL=https://host:port/sms.gateway/smsPipe
      - SMS_GW_USERNAME=U53rnam3
      - SMS_GW_PASSWORD=pa55c0d3
      - TENANT_PHONE_NUMBER=+12345556789
      - ENABLE_INBOUND_SMS=`True`
      - SMS_GW_READ_TIMEOUT=5


      - WEB_HOOK_HOST=vgwHostName
      - HTTP_HOST=*

Find the public IP address for your SMS Gateway deployment in IBM Cloud

To configure the url parameter or SMS_GW_URL environment variable for SMS Gateway deployments in IBM Cloud Kubernetes Service, you can use the ibmcloud cs workers command.

ibmcloud login --sso

1. Find the IP address for your cluster.
  ``` {: codeblock}
ibmcloud cs workers <cluster_name_or_id>

Use the IP address to compose the url or SMS_GW_URL value in the format http://<public IP>:port/sms.gateway/smsPipe.

SMS_GW_URL=http://100.11.11.11:99999/sms.gateway/smsPipe

  If your Voice Gateway and SMS Gateway deployments are running in the same node, you can use the service name instead of the public IP address.

  ``` {: codeblock}
- SMS_GW_URL=http://sms-gateway:9080/sms.gateway/smsPipe

Adding the `vgwActSendSMS` action and configuring intents

The SMS message text that you want to send can be sent from either your Watson Assistant dialog or your SOE using the vgwActSendSMS command. When the dialog node is triggered during a conversation session, Voice Gateway sends the SMS message to the caller. To define the message, add the following action in the JSON of the dialog node response. See vgwActSendSMS in Action tags, Defining actions and states, and the samples in Resources for SMS Gateway for examples and information about customizing Watson Assistant, SMS Gateway, and Voice Gateway.

{
"command" : "vgwActSendSMS",
"parameters" : {
"message" : "This is a test message"
}
}

Receiving an SMS message from SMS Gateway

After receiving an SMS message, Voice Gateway initiates a turn and sends Watson Assistant a text update with the word "vgwSMSMessage" to indicate that an SMS message was received from the caller.

To ensure that there is no interruption in conversation with the caller after receiving an SMS message, Voice Gateway verifies whether there is an ongoing voice transaction to avoid unintended barge-ins. If Voice Gateway is currently collecting utterances or dual-tone multi-frequency signaling from the caller, it waits for the current transaction to complete.

Once collection is complete or if timeout occurs, Voice Gateway then initiates a turn to the Watson Assistant service.

If no input from the caller is detected, Voice Gateway immediately initiates a turn to the Watson Assistant service, and sends the "vgwSMSMessage" text update.

Handling failures when the SMS message can't send

If an SMS message can't be sent to the caller, Voice Gateway immediately initiates a turn event to the Watson Assistant service. The Watson Assistant service receives a text update with the word, "vgwSMSFailed" to indicate that an SMS message can't be sent the caller. You can customize how Voice Gateway responds by creating an intent for #vgwSMSFailed to handle the failure message with an appropriate response. See Connecting through a services orchestration engine.

Managing Watson Assistant contexts when sending and receiving SMS messages from Voice Gateway

Since SMS and voice are two distinct channels for communicating with a caller, it's important to maintain independent contexts for each channel. Voice Gateway saves the current workspace context that is received with the response from Watson Assistant that includes vgwActSendSMS. When the caller replies with an SMS message, Voice Gateway then passes this context back to Watson Assistant or the SOE. This context is passed to Watson Assistant in the vgwSMSContext state variable. The SOE or workspace can then access the related context of the inbound SMS message and determine the purpose of the message.

Optional parameters

You can provide optional parameters that define integration configuration with SMS Gateway in the Watson Assistant dialog. If you define configuration parameters within the vgwActSendSMS action, they override the Voice Gateway tenant configuration. See the vgwActSendSMS entry in Action tags and state variables in Voice Gateway for the list of parameters that you can define.

Integrating security certificates

When an inbound message arrives at SMS Gateway, the message is sent to Voice Gateway on the URL that Voice Gateway provides when it creates the SMS Pipe request to SMS Gateway. The Voice Gateway URL is generated by using the values that are provided in the WEB_HOOK_HOST and HTTP_PORT or HTTPS_PORT configuration variables. The URL scheme is based on the value of the SMS_GW_URL configuration variable. For example, when the scheme that is used in the SMS_GW_URL variable is https, then the Voice Gateway URL also uses the https scheme. The SMS Gateway server URL can also be provided through the Watson Assistant API.

When an inbound message arrives at SMS Gateway, the message is sent to this URL. You can secure the request from Voice Gateway to the SMS Gateway REST API by defining the SMS Gateway server URL with the SMS_GW_URL or url value in the deployment configuration.

To encrypt data passing between your integrated SMS Gateway and Voice Gateway instances, you must configure security certificates for each.

Generate a signer certificate for each of your SMS Gateway servers and Voice Gateway servers.
In Voice Gateway, add the signer certificate from each SMS Gateway to each Voice Gateway server key file. See Securing Voice Gateway.
In SMS Gateway, add the signer certificate from each Voice Gateway to each SMS Gateway server key file. See Configuring SSL and TLS encryption for SMS Gateway.