copyright: years: 2018, 2023 lastupdated: "2023-01-04"
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.
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.
- Log in to IBM Cloud.
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
orSMS_GW_URL
value in the formathttp://<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.