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

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.

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>
(2) Select Users sidebar
(3) Click on + on bottom right of page.
(4) Name your Bot
(5) Set the role to Bot
(6) Click on Create User.

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 User

Copy the token by:
(1) Clicking on the user
(2) Clicking on the copy icon.

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