Contribute in GitHub:

Getting started with SMS Gateway

Follow these steps to create and deploy a basic cognitive SMS agent either on-premises or in the cloud.

1. Choose an SMS provider and create a phone number

Your SMS agent needs a phone number that supports SMS capabilities so that it can send and receive messages. SMS Gateway supports Telestax RestcommONE and Twilio® Programmable SMS.

For RestcommONE:

Create a RestcommONE account on the Telestax website.
From your RestcommONE console, go to Numbers > Register Number > Provider Number.
In the Country field, enter United States. Select the state and area code, and click the magnifying glass search icon.
Review the list of numbers. Accept a phone number by clicking Register.

For Twilio:

Create an account on the Twilio website.
From the Twilio console, go to All products and services > Phone Numbers. On the Getting Started page, click Get your first Twilio phone number.
Review the suggested phone number, which includes SMS capabilities. Accept the phone number by clicking Choose this number.

2. Create a Watson Assistant skill

SMS Gateway connects to the IBM Watson™ Assistant service, which provides the intelligence behind your SMS agent. Watson Assistant analyzes the message text, maps it to intents or capabilities, and provides a response according to a dialog that you create.

Sign up for an IBM Cloud account, and create the Watson Assistant service.
Add a skill (formerly called "workspace") with a dialog.

You can quickly get started by importing the sample conversation JSON file from the sms/conversation folder in the sample.voice.gateway GitHub repository. To learn more about importing JSON files, see Creating a dialog skill in the Watson Assistant documentation.

If you build your own dialog instead of using the sample, ensure that your dialog includes a node with the conversation_start condition and node with a default response.

3. Deploy SMS Gateway

Deploy SMS Gateway to one of the following environments:

4. Configure the SMS request webhook in your SMS provider

Defining the SMS request URL, or webhook, tells your SMS provider where to forward SMS messages to SMS Gateway.

In the console for your SMS provider, find the field where you specify the URL for SMS requests.

For RestcommONE:
1. In the RestcommONE console, select Numbers and then select your phone number.
2. In the SMS Request field, select RCML URL from the drop-down menu.
For Twilio:
1. In the Twilio console, go to Manage Numbers > Active Numbers and select your phone number.
2. Under Messaging on the Configure tab, find the A message comes in field, and select Webhook.
In the text field, enter one of the following URLs, where host-address is the host name or IP of your deployment:
- Secured connection:

https://host-address:9443/sms.receiver/SmsRecv

  * Unsecured connection:
  ```
http://host-address:9080/sms.receiver/SmsRecv

For additional security, you can configure authentication for the webhook as described in Configure authentication for the SMS provider webhook.

5. Test your deployment

To test your deployment, you can create a session by using the SMS Gateway REST API, or you can send an SMS message if you enabled SMS session creation via SMS message. For more information about the REST API, see Using the REST API to control SMS sessions.

Test by sending an SMS message
1. Verify that ALLOW_SESSION_CREATE_VIA_SMS is set to true in the configuration.
2. From a device such as a mobile phone, send an SMS message to the tenant phone number that you configured.
Sending the SMS message prompts SMS Gateway to create an SMS session. The gateway sends the message data to the Watson Assistant service and replies back with a fitting response according to the Watson Assistant dialog.
Test by using the REST API
1. In your browser, go to one of the following URLs, where host-address is the host name or IP of your deployment:
- Secured connection:
```
https://host-address:9443/publicURL/apis/explorer/
```
- Unsecured connection:
```
http://host-address:9080/publicURL/apis/explorer/
```
1. Click List operations and then Create a SMS session.
2. Under the Data type column, click the example to prepopulate the Value field.
3. Modify the smsUserPhoneNumber value to be the number that you want to send a message to, and modify the smsTenantPhoneNumber value to be the tenant phone number that you configured.
4. Click Try it out! to create a session.
When you create the session, SMS Gateway connects to the Watson Assistant service and sends the welcome response in an SMS message to the specified user phone number.

Tip: If you run into any problems, you can use the REST APIs for testing configuration to help troubleshoot.