Conversations Inbox | Integration with IBM Watson

Hi there!

Would you like an AI assistant to respond to messages from your customers automatically and have a coffee instead?

In this tutorial, you will learn to integrate the IBM Watson AI assistant with the WhatsApp channel of the Conversations Inbox using the Dashboard Assistant.

You will need

Your WABA phone number that has been approved by tyntec
A testing customer WhatsApp
An IBM Cloud account (A free Lite account is enough for 10 000 messages per month, with 5 minutes allowed for session inactivity.)
Your Conversations Inbox API key provided by tyntec (contact t yntec suppor t if you don't have it)
An Automatic Assistant for CMD set up by tyntec (contact tyntec support if you don't have it)
Postman
An ngrok account with the binary installed and authorized
A Node.js and your favourite text editor or IDE with JavaScript highlighting

Step One: Get your integration app ready

For your quick start with integrations, we’ve prepared a sample integration app. Let’s have a look at what the code does. Notice the code in the following files:

server.js does basic management, provides endpoints, and binds the logic together.
watsonHandler.js handles communication with Watson Assistant API and creates sessions with the Watson Assistant.
tyntecHandler.js forwards messages from the Watson Assistant to the given WhatsApp conversation via the CMD API.
config.js takes responsibility for app configuration.
cacheState.js caches a session for the Watson Assistant.

Let’s just quickly get your app running:

1. Clone the api-sample repository and go to the chat-integrations/watson directory.

2. Install dependencies (and the nodemon module if you don’t have it yet):

npm install
npm install nodemon

3. Run ngrok in a terminal to expose your local server on the internet:

path/to/ngrok ngrok http 3000

4. Copy the tunnel URL (The URL looks like http://843fc8776770.ngrok.io).

Note: This setup is suitable only for development. For production use, you have to deploy your app properly!

Step Two: Subscribe your webhook in the Inbox

Let the Inbox know where to deliver WhatsApp messages from customers. You’re going to subscribe your webhook via an API call in Postman.

From the chat-integrations directory, import the CMD.postman_collection.json into Postman.
Authorize Postman with your CMD API key and your WABA number. Right-click the collection and select Edit. Then go to Variables and set the apiKey variable to your CMD API key. Set also the wabaNumber variable to your WABA number.
Let’s set up the webhook! Open the Set Webhook request and change the URL in body to the /message endpoint on your server (for example https://843fc8776770.ngrok.io/message). This request will subscribe your URL to incoming message events.

Hit the Send button. You should receive a 2xx status in the response if everything was okay.

Cool! Now your Inbox knows where to deliver WhatsApp messages from your customers.

Step Three: Configure your IBM Watson Assistant

You need to set up your IBM Watson Assistant. Then, you train Watson with Intents and set responses to these intents using Dialog. The combination of Intents and Dialogs is called a Dialog Skill.

1. Login into your IBM cloud account and click on the Create Resource button.

2. Search for Watson Assistant and open the Watson Assistant page.

3. Set up your access to the Watson API. Start by selecting your region, set the Service Name, and click Create.

4. Copy the URL and API key, you will need them later, and click on Launch Watson Assistant to start creating it.

5. Now create your own Watson Assistant AI. Click on Create Assistant, fill the name in and add a description if you like.

6. With a newly created Assistant, you need to add Dialog Skills to set up the behavior of Watson Assistant.
Click on Add Dialog Skill, select Create Skill, and fill in a name of your test skill. If you want, you can add a suitable description. Click on the Create Dialog Skill button.

Afterwards, you’ll be redirected back to the Assistant Dashboard.

7. To understand your customer, Watson Assistant needs to know the intent of their message. Back in the Assistant Dashboard, click on the dialog skill you created to open the Intents page.

Here you set Intents. Watson Assistant uses Intents to understand the given message. Click on Create Intent to set up a new one.

8. Write the name of the Intent and press the Create Intent button.

9. Your first Intent is ready but it needs some examples to work properly. Fill in a few User examples, so your Assistant can understand.

Tip: You can always test the Assistant with the Try it button.

10. After creating the Intent and giving few User examples, you need to set up the behavior of Watson Assistant. Click on Dialog in the left menu.

Here you teach Watson how to respond to Intents. Click on Add Node to define a response.

Select your Intent in the If assistant recognizes field. Then you can write down Watson's responses. If you find it fitting, change the response variation: Random makes Watson use only one of the lines, sequential sends all lines as individual messages, and multiline sends a single large message with all the lines.

12. Now your Watson Assistant is set up, you just need its Assistant ID. Go back to the Assistant page, click on the three dots to open Settings and select Settings.

In Settings, click on API details and copy the Assistant ID.

Congrats! Your Watson Assistant is all set!

Step Four: Configure and run your app

Now you just need to finish configuring your app.

1. Copy the file .env-example to .env and set environment variables in .env:

ASSISTANT_ID -- ID of your Watson Assistant
WATSON_API_KEY -- API key for your Watson Assistant account
WATSON_URL -- URL of your Watson Assistant
WABA_NUMBER -- your WABA number in the international format without the leading +/00
CMD_API_KEY -- your API key from tyntec to authenticate calls to CMD API

2. Start the app in another terminal:

nodemon app.js

3. The last thing missing is to establish a session with IBM Cloud. In your browser, go to the /session address of your server (such as http://843fc8776770.ngrok.io/session). Your app will create a session and cache the session ID.

Step Five: Try it out!

Take your phone with your testing customer’s WhatsApp and try sending one of the User example messages from Step Three.

And voila! Watson should respond immediately:

Congratulations on your integration!

More?

For example, you may want to automate your integration further:

Refresh your session
The sample application doesn't refresh Session ID automatically. A session is usually dropped due to inactivity (the session limit is 5 minutes for Lite plans). Look at the official documentation to find how to change the settings.
If you want to stick with a Lite plan, you can extend the app to call for a new Session ID with a new conversation, or to watch session expiration by saving a timestamp of the last session retrieval.
Train your Assistant to answer more intents, add new dialog skills, or annotate semantic entities.