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 ChatShipper 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 ChatShipper Admin rights to be able to create the bot in ChatShipper.

Initilizing 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 ChatShipper.

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:

ChatShipper 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:

ChatShipper 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. ChatShipper'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 ChatShipper 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

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 ChatShipper...hop on to the next chapter...