From Zero to Webex Teams Chatbot in 15 Minutes

Webex Teams currently powers thousands of bots with a variety of functionality – ranging from simple chat bots that provide specific information like the current weather, to more sophisticated bots that understand natural language and automate complex business tasks. Perhaps you've been wanting to deploy a handy chatbot of some kind and just haven't gotten a chance to start on it yet. Well, this is your big chance!

Back when Webex Teams (then called Spark) bot functionality was first made available, there were several simple starters. We always liked the sparkbotstarter which was created by Victor Algaze, using a framework called Flint, which was created by Nick Marus. This sample is based on the new, rebranded webex-node-bot-framework, and adds a few fun new tricks, like posting a message using Webex Buttons and Cards.

Getting Started

Even if you don't have any prior knowledge of the Webex APIs, this guide will have you deploy a functioning chatbot application pretty quickly. Then from there, the bot-starter application can serve as a template for creating your own customized bots and can be extended to your heart's content. You might need to be at least a little familiar with node.js and also have the following prerequisites:

1. Node & npm (minimum tested version is node 8.0.0 or higher) and git installed on your machine

2. A Webex Teams account: https://teams.webex.com/

Sign into Webex Teams

The first thing we'll need to do is create a new bot. You can simply use your regular Webex Teams credentials to log in to Webex for Developers. When you create the bot account, be sure to jot down the bot’s username & access token before leaving the creation page - we'll need those in a minute.

Set up the Local Web Server

The bot application has to be hosted on a server where it can communicate over HTTP. For now, we'll use nGrok, which is a tool that turns your machine into a web server by opening a local port to the Internet. We're doing this so we can start using our chatbot as quickly as possible without having to think about deployment or hosting. Once you’ve customized your chatbot, you’d likely want to deploy it on a proper cloud hosting service, such as Microsoft Azure or other similar platforms, instead of your machine. Since we are aiming to get started quickly though, nGrok uses the least number of steps to get there:

1. Download and setup nGrok here: https://ngrok.com/

2. After downloading and unzipping nGrok, from the same directory as the nGrok executable execute this command:

   $ ./ngrok http 7001 --region=eu

3. Once it's running, write down the web address that's tunneling to your localhost:7001 (e.g. http://XXXXXXX.ngrok.io)

Configure and Run the App

Now we just need to download the project, swap in a few values, and start the bot up!

1. Download the node.js Webex Bot Starter template project with this command in your terminal:

   git clone https://github.com/WebexSamples/webex-bot-starter && cd webex-bot-starter

2. Inside the project's root config-template.json file, use a code or text editor to swap out the following values:

   {
    "webhookUrl": "http://XXXXXXX.ngrok.io",
    "token": "BOT_TOKEN_CREATED_FROM_EARLIER",
    "port": 7001
   }

   Note that if/when you turn off nGrok, when you turn it back on the URL will change and you will need to update the config with the new address.

3. Save the changes, then rename the config-template.json file to config.json.

4. Finally, to install and start the application, run this command:

   $ npm start

5. If you're using a Mac, you might receive a prompt asking about “node” accepting incoming network connections. If so, click Allow to load the server:

Interact with the Bot in Webex Teams

Now that the nGrok server is loaded and the app is running, create a new group space (name the title whatever you want) in the Webex Teams client. Next, add your bot to the space (by the username you created earlier), just as you would add any other Webex user.

If everything was done correctly, your bot should have greeted you with some instructions when it was added to the space. You now have a running chatbot! To go further, open the index.js file in an editor and extend functionality as much as you need.

Helpful Resources

• This bot starter application is based from the webex-node-bot-framework:

  https://github.com/webex/webex-bot-node-framework

• Intro to the Webex for Developer platform:

  https://developer.webex.com/docs/platform-introduction

• Webex Bots explained:

  https://developer.webex.com/docs/bots

• Guide for creating Webex Buttons and Cards in messages:

  https://developer.webex.com/docs/api/guides/cards