Creating a bot

Before you start

Our SDK is written in Node.js and we will use this SDK to create our bot. If you want to create a bot with another language you can do so by talking to the Web1on1 REST-full backend directly, but that is out of the scope of this example.

We are assuming you have knowledge of Node.js, npm, Javascript and working in a Unix-like shell. We are also assuming you have node installed on your machine.

You will also need Web1on1 Admin rights to be able to create the bot in Web1on1.

Initializing the node project

Our bot will say hello when you start it manually. First, let's set up a project for our Node.js bot. Open a terminal and follow these steps:

# Create the project folder and the src folder in one go
mkdir -p helloworld/src
# Step into the folder
cd helloworld
# Initialize node
npm init
# Just press enter on all questions, but fill in src/index.js at
# the question about the 'entry point'. We will be useing the
# ChipChat SDK and debug so we need to install it.
npm i -s chipchat debug

you should have a package.json in your project folder after this.

The bot's code

Now that we initialized our node project we can edit the src/index.js file in your favorite editor to start working on our bot. Add the following code in src/index.js:

// file: src/index.js
const log = require('debug')('bot');
const Bot = require('chipchat');
const bot = new Bot({
    token: process.env.TOKEN,
    ignoreOnActivity: true
bot.on('message.**', (message) => {
    log(`incoming message: type: ${message.type}, text: ${message.text}`);

this creates the smallest bot ever that only shows all incoming events in the log. it is always good to add the ignoreOnActivity option that will stop the bot the moment a user or bot becomes active in the conversation.

debug is explained later in this chapter.

As you can see we are using process.env.TOKEN. This token belongs to the bot user and will identify and authorize the bot to Web1on1.

Creating the bot in the UI

But we don't have a bot user yet, so let's create one in your organization by following the steps in the image below:

Web1on1 Bot User

Adding a bot user to your organization:
(1) Select Settings > <Your Organization> > Bots sidebar
(2) Select the My Bots tab
(3) Click on + on bottom right of page.
(4) Name your Bot
(5) Give your bot a nice icon
(6) Leave empty
(7) Select the capabilities of your bot.
(7) Select the audience of your bot.
(9) Optional: select the commands your bot knows about.
(10) Optional: choose the webhook your bot uses.
(11) Add a good description of the functionality of the bot. This will be visibe in the bot store.
(12) Optional: Add any meta variables your bot uses.
(13) Click on Create Bot.

Capabilities of your bot

You bot can have 4 different capabilities. it depends on the functionality of your bot which one(s) you should select.

  • User assist ("bot"): A bot that guides and assists users or enriches conversations, and can be addressed by users.
  • Consumer facing ("agent"): A bot that accepts contact conversations and talks to consumers.
  • Administrative rights ("admin"): A bot with special administrative privileges, like creating users or updating organization resources.
  • Platform integration ("contact"): An application that creates and represents external contacts, such as a bridge or portal to consumers.

You should always choose the lowest possible capability that still does what you want.

Audience of your bot

You bot can have 3 different audiences. Audience means visibility in the bot store. Who can see and therefore enable and use the bot.

  • Owner: Only the owner of the bot will see the bot in the store.
  • Sub-orgs: Share this bot with all sub organisations under you organisation. This can be sub filtered by tag.
  • Global: Share this bot with all organisations, Also the ones above your organisation.

Commands of your bot

Here you can configure the available command your bot knows about. This will be used in the Agent interface. When an agent used the > to select a bot it will see the commands avaliable for this bot.

Meta variables of your bot

Most bots are configurable. As the owner of the bot you can add meta variables to configure the bot's default behaviour. All meta variable keys will be available to the sub organisation that has added/enabled your bot. They will not see the value of each meta key. This is to protect sensitive data. It is up to the creator of the bot to provide good documentation of the meta vaiables to user of the bot.

After the bot is created in the UI

After the user is created you can click on it again to access it's properties so you can copy it's TOKEN like his:

Web1on1 Bot Tokens

Copy the tokens by:
(1) Clicking on My Bots
(2) Clicking on the just created bot
(3) Clicking on the Api Token tab
(3) Clicking on the Generate Tokens button that you will see. if you see tokens already, you will see a Refresh button
(4) Clicking on the copy icon of the Api Token.

Now, open a new terminal, goto your project folder and do this:

# Export the TOKEN environment variable just for this session
export TOKEN=<paste your token here>
# Start the node application (our little bot)
DEBUG=* node src/index.js

DEBUG=* will activate debug log messages on all node packages so we see what is happening under the hood. Our twilio partners have written a nice blog post about it. If all went well, you should see something like

ChipChat Webhook running on localhost:3000/

Congratulations, you have your first running bot.

Accessing the bot

As you might have noticed, the bot is running on your local machine port 3000. Web1on1's webhook that we will setup in the next chapter cannot access your local machine from the internet for obvious security reasons.

But do not despair, you can fix this by using a nice little tool called ngrok. It makes an external url that is accessible by Web1on1 route to your local machine's port 3000.

To do this, open a new terminal and start ngrok like this:

ngrok http 3000

if ngrok is not found just do npm i -g ngrok, and try again

your should get something like this:


all traffic from (port 80) will be passed on to your localhost port 3000

Set up a webhook

Alright, we now have a publicly accessible url where our bot is running on. It is time to hook up this url to our webhook in Web1on1.

All bots listen to Web1on1 events via a webhook. With a webhook you can tell Web1on1 to send one or more events from Web1on1 to your bot (the url your bot is connected listening on). Follow the steps in the Webhooks Guide to create a webhook for your bot.

Testing the bot

What do we have so far:

  • We have a running bot that listens to all events and logs them.
  • We have a webhook that pushes the default message and conversation events.

It's now time to test the bot. We can test the bot by starting a conversation with it.

Talking to the bot

There will be two log messages in the terminal where you started the bot with something like this:

# The first message shows you joined the conversation with the bot
bot incoming message: type: command, text: /join +0ms
# The second message shows you send the message 'hi there'
bot incoming message: type: chat, text: hi there +0ms

Make the bot say something

The second parameter of the incoming messages is the conversation context that you can use to make the bot talk. Let's make the bot say hi back. Change bot.on function the code to receive the second argument and talk back like this:

bot.on('', (message, context) => {
    if (message.text === 'hi there') {
        context.say('Hello to you too!');

We change the event to, so we will only listen the chat messages. We also added the context param that we use to say hi back if the message sent was hi there

Now, when we type hi there in the conversation, we should get the bot returning hello to you too!: