Navigate / search

How to start with chatbots

Not a long time ago I decided to explore the new possibilities of designing chatbots with our tools. Here is my experience with developing first simple bots, maybe it can help you if you plan to go the same path.

When you want to develop cognitive chatbot, you have to learn two products:

  • IBM Watson Conversation: a service from a big Watson family that take the sentence user typed in the bot understands the meaning and give back to bot extracted entities. The bot can use the entities to chose the appropriate response and send it back to the user. Usually, this involved communicating with another system, calling remote APIs, obtaining data and formatting them for user output.
  • IBM Watson Workspace: a conversation tool, that takes care of the whole front end. Watson Conversation itself does not have any end-user interface; it works behind the scene. You need some UI, where people will have a conversation with your bot, so why not to use Watson Workspace? Moreover, there is built-in integration between Workspace and Conversation that will ease you with steps with the technologies.


Learn about IBM Watson Conversation

The best way is to start building a simple bot with a step-by-step tutorial. I have found that IBM offers a few good entry tutorials and if you follow them you will even receive a badge! Here is the list of tutorials I went through:

Build Chatbots with Watson Conversation

Introduction and explanation of the building blocks (intents, entities, dialogues). You will create your first bot. Optionally, you can explore possibilities of accessing Conversation API from a simple node.js application.
After this course, you can create your own very simple chatbot, with a few intents and entities, that you can call from a custom application added to Watson Workspace.


If you want to go deeper and learn about chatbots methodology, implementation and project management, you can try following three courses. If you are eager to use bots in Watson Workspace, you can skip them and return to them later.

Watson Conversation Service Foundations

Watson Conversation Service Methodology

Watson Conversation Service Hands-On



There is also a course on CognitiveClass website:
Build Your Own Chatbot


If your preferred method learning new things is to read books, try this one from IBM Redbooks series:
Building Cognitive Applications with IBM Watson Services: Volume 2 Conversation (PDF and ePUB available)


Learn about Watson Workspace

The good way how to start is the TechTalk about developing for Watson Workspace. It gives you overview how Watson Work (a platform behind Workspace UI) handles messages, adds annotations to them and how custom applications added to Space can hook into message processing workflow.

Now you have a basic technical knowledge, and you probably want to get your hands dirty and develop a simple application yourself.
You will use Watson Work Services API for that. The official documentation is here and covers both principles of building and deploying an application as well as API reference.

But I guess you do not want to start coding from scratch, deal with session opening, authentication, sending and receiving HTTP calls etc. You want to implement a simple business logic: for a start, you will do something like “Hello world”, then you want to integrate the app with Conversation dialogue you already created. That’s why SDKs exists — those toolkits will do the hard and not exciting work for you and let you focus on application logic itself. SDKs are language specific. I use an unofficial JavaScript SDK developed by IBMer Van Staub. It is an excellent piece of work, and his toolkits helped me building Workspace App almost instantly.

It is expected that you have some basic knowledge of JavaScript development, npm packages and Node.js server. Here are components of Van’s SDK:

IBM Watson Workspace Javascript SDK
It covers authentication with Watson Work Services and message operations (getting message, sending message, working with action fulfilment etc.) You do not need to work with this library directly, is’s functions are called from other libraries.

IBM Watson Workspace Bot Framework
This is a framework for building Watson Workspace Bots. Its primary goal is to hook into Workspace message workflow (via webhooks) and handling actions when a specific event occurs (for example when a new message is posted into Space when a new user is added as a member to Space or when a message is analysed). This library uses functions from WW-SDK library mentioned earlier. You will use functions from the library in your bot application.

IBM Watson Workspace Starter Bot
This is not a library but an example of straightforward, but functional WW application. It shows you how to call functions fr mentioned WW-BOT library to build your application.
This is the place where you should start with creating your first WW application. Just copy the code, fill in credentials and run it. When it works, play with it, do simple modifications, check how it behaves.
Van also recorded a short video where he explains, step by step, how to use this Starter Bot sample application. Watch it on YouTube.


Integrate Conversation into Workspace

Now you know how to build the simple application, add it to your Space, handle specific webhooks and launch actions according to them.
When you want to integrate WW app with dialogue in Watson Conversation, you have two options:

  • Do it manually: Listen on hook message-created, then send the message content to Conversation, receive back entities and use them as parameters for real action (for example receiving data from a backend service). You can use Watson Conversation Service SDK:
  • Or you can use built-in integration between WW and Conversation: It does the initial part for you: when a new message is sent to Space, Workspace automatically sends it to Conversation and returns analysed entities as a message-focus annotation. You can handle this event with WW Bot Framework and react according to entities. You will need basic JavaScript development knowledge to do this.

When you develop WW applications, you need to know what happens under the cover. As an end.user you only see sentences that appear on the screen, but behind the curtain the are invisible messages going there and back, between systems. Yes, there is a system in this messages, they are described and explained, but when you start with the development, you could be a little lost.

When I was in this phase and experimented with handling different types of events, I analysed the payload of the messages, did a lot of detailed console.log dumps, etc.
To help you in this situation Van created a helper bot application, which will visually show you the structure of the message in the Space, display how WW analyse each message and which entities you can use in your application. You can find it here:

IBM Watson Workspace Cognitive Explorer Bot

Van also created a ready-to-use WW application that handles todos discussed in a Space. Use it both for fully working demonstration and for learning by reading the code.
IBM Watson Workspace Todo Bot

Good luck on your chatbots exploring path!