Using SMS is a very convenient way to communicate with someone these days and most people prefer to use SMS instead of email. SMS also gives you a history of the conversation while, for example, the context of a phone call can be easily forgotten if you don’t take notes.
In the same way that you text someone these days, you could also apply the same idea to business communications. The convenience, flexibility and speed of SMS can dramatically improve customer service. On top of that, several business tasks could be easily automated. Just imagine that you can get the status of something you order without waiting in line or having to download a particular mobile app by just texting the business’ phone number.
Having the capability of serving your users using SMS with an Intelligent Bot performing the interactions is the exact scenario we are going to explore in this article.
The Big Picture
To give you an overview of what we are going to put together here, you can start with the following diagram that illustrates the messaging flow and the major components involved.
- You set up that Phone Number to send an HTTP request to your server every time a SMS message comes in.
- Your server receives the messages from Twilio and prepare them to the Intelligent Bot server.
- The Intelligent Bot server processes the request and sends an asynchronous HTTP response back to your server.
- Your server receives that information and sends an HTTP request through the Twilio SMS API.
- Twilio sends the SMS message to the user.
Setting up my Bot to Interact with SMS users
Once you already know what we are going to be doing, let’s have a look on what’s required before we get started and then dive into each one of these components.
Here are the ingredients:
- Twilio Account (You can get a free account here: https://www.twilio.com/try-twilio)
- Twilio Phone Number (Buy a Twilio Number here: https://www.twilio.com/console/phone-numbers/incoming)
- The Sample Node.js Server (more info below)
- Oracle Intelligent Bot instance (You can get started here: https://cloud.oracle.com/en_US/tryit)
The Twilio SMS Setup
To do that, you’ll need to set up a Twilio account. You can sign up here: https://www.twilio.com/try-twilio.
Once you have a Twilio account, log into the Twilio Console (https://www.twilio.com/console) and buy a Twilio Phone Number with SMS enabled.
With your new Phone Number, you have completed the first part of our configuration and you should be able to send SMS messages to your number. The following diagram shows you what have you done so far.
The next thing you will need is a way for Twilio to send HTTP requests to your sample Node.js server. If the Node.js server is running on your machine and it’s not directly exposed to the Internet then Twilio won’t be able to reach it. To enable that, I’d recommend using ngrok (https://ngrok.com/) with multiple simultaneous tunnels which allows you to expose a local server to the Internet, in this case one endpoint to be used by Twilio and the other by the Intelligent Bot server. If you already have a server that’s exposed to the Internet then feel free to use it as we move along.
Make sure that your ngrok setup points to where you are going to be running your Node.js server.
The URL generated by ngrok or the URL of your own server is what we are going to use to set up the Webhook in the Twilio Phone Number under the Messaging section for when “A Message Comes In”.
So, every time that someone sends a SMS message to the number you have set up, Twilio will make an HTTP request to the Webhook URL you have provided above.
With that, you have completed the second part of our configuration and now Twilio is able to communicate with your server as showed in the below diagram.
The Intelligent Bot SMS Channel Setup
To create a Webhook channel, go to your Bot Settings page, select Channels and click the ‘+ Channel’ to start configuring what you need.
Give it a name, description, select Webhook as the Channel Type, provide the Outgoing Webhook URI (this is where the Intelligent Bot server will make HTTP requests to your Node.js server) and make sure the Channel is set to Enabled.
The Sample Node.js Server
Download and extract the sample Node.js server code from here. Make sure you have Node.js (https://nodejs.org/en/) downloaded and installed on your machine before continuing on this step.
The next step in our configuration is to have a piece of software that’s going to interface with both the SMS side (Twilio in this case) and the Oracle Intelligent Bot server. For this particular thing we are going to use a Node.js based server running some sample code to take care of those required tasks but you could host this on Oracle Mobile Cloud Enterprise (OMCe), Oracle Application Container Cloud Service (ACCS) or on your own server.
The sample Node.js server will receive the SMS messages from Twilio, extract the relevant information, sign the message according to the Intelligent Bot server expectations and send the messages to the Intelligent Bot server.
Then, the sample Node.js server will also receive messages back from the Intelligent Bot server, verify its signature, set up the response message and finally send the messages back to Twilio where the SMS will be generated and sent to the user.
But, before you run the sample Node.js server, you will need to provide some required metadata information. You can set this up as environment variables or straight into the source code if you want to.
These are the environment variables you’ll need:
The next step in our configuration is to have a piece of software that’s going to interface with both the SMS side (Twilio in this case) and the Oracle Intelligent Bot server. For this particular thing we are going to use a Node.js based server running some sample code to take care of those required tasks but you could host this on Oracle Mobile Cloud Enterprise (OMCe), Oracle Application Container Cloud Service (ACCS) or on your own server.
The sample Node.js server will receive the SMS messages from Twilio, extract the relevant information, sign the message according to the Intelligent Bot server expectations and send the messages to the Intelligent Bot server.
Then, the sample Node.js server will also receive messages back from the Intelligent Bot server, verify its signature, set up the response message and finally send the messages back to Twilio where the SMS will be generated and sent to the user.
But, before you run the sample Node.js server, you will need to provide some required metadata information. You can set this up as environment variables or straight into the source code if you want to.
These are the environment variables you’ll need:
- TWILIO_ACCOUNT_SID – Your Twilio Account SID (You can get this from www.twilio.com/console)
- TWILIO_AUTH_TOKEN – Your Twilio Auth Token (You can get this from www.twilio.com/console)
- MY_TWILIO_NUMBER – This is the Twilio Phone Number you set up
- BOT_SECRET_KEY – This is the Intelligent Bot SMS Channel Secret Key (You have this from the previous step)
- BOT_WEBHOOK_URL – This is the Intelligent Bot SMS Webhook URL (You have this from the previous step)
The sample Node.js server will look for those variables during the startup and you can export/set them depending on your host platform of choice.
Personally, since I'm on macOS, I prefer to use a .env file with the following information:
export
TWILIO_ACCOUNT_SID=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
export
TWILIO_AUTH_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
export
BOT_SECRET_KEY= XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
export
BOT_WEBHOOK_URL=https://XXXXXXX.ngrok.io/connectors/v1/tenants/chatbot-tenant/listeners/webhook/channels/8C9F0AC4-FBBA-4BBE-8C4A-299D518396B8
export
MY_TWILIO_NUMBER=+1555-555-5555
so I can keep all the required information in one place for my development needs. Replace the instructions above based on your platform of choice and keep in mind that if you don’t set those values as environment variables then you’ll need to add that information in the twilio-sms/app.js file (approximately line 25) like showed below:
var metadata = {
waitForMoreResponsesMs: 500,
accountSid: ACXXXXXXXXXXXXXXXXXXXXXXX,
// Your Twilio Account SID
authToken: XXXXXXXXXXXXXXXXXXXXXXX, // Your
Twilio authToken
myTwilioNumber: ‘+1555-555-5555’, // Your
Twilio Phone Number
channelSecretKey:
XXXXXXXXXXXXXXXXXXXXXXX, // BOT Secret Key
channelUrl: XXXXXXXXXXXXXXXXXXXXXXX //
BOT Webhook URL
};
>
node twilio-sms/index.js
With that, you have put together the final part of our configuration that allows the Intelligent Bot server communicate with your server.
Testing the SMS Channel with Intelligent Bots
Conclusion
The fact that SMS is available everywhere, doesn’t require the user to download anything and it has a very low entry barrier makes it very appealing for a Bot channel.
With very little effort, you can set up everything needed for your Bot to be integrated with SMS API-based providers and have that channel available to your bot quickly.
Hopefully, this article provided a good idea on the major components, the necessary configuration on each level and the end to end functionality it provides to your bot project.
