Contents

  1. Introduction
  2. Theory and tools
  3. Send a test message with Postman
  4. Send a message with code
  5. Connect a Workplace integration to our code
  6. Receive a message from Workplace
  7. Getting your bot online

Bot Theory and the Tools You’ll Need

In the first part of our bot-building tutorial series, we looked at some of the basic definitions (bots, chat bots, group chat bots, and integrations).

Today, we’ll start getting our toes wet. First, we’ll look at how a bot does what it does, and then we’ll look at some of the technical tools you’ll need before you can start making your first bot.

 

So how do bots work?

Before we get into the details, we need to understand the basic loop structure behind any Workplace chat bot. In simple terms, it goes a bit like this:

  1. The user talks to the bot in Workplace
  2. Workplace sends that message to our application
  3. The bot decides what to do
  4. Our application sends a message back to the user.

That’s the simplified version. Now here’s the technical version (with a handy diagram to help you visualise it):

1.  Workplace sends the user’s message to the bot

Once your user has entered a message in a chat with your bot, Workplace (the far left of the diagram) needs to be able to send that message through to your bot (the little robot icon). It does this through a webhook.

Webhook? What’s that?

A webhook is a piece of software that listens for incoming messages.

Your users might start a conversation with your bot at any time, so Workplace needs to be able to send your users’ messages to the bot at any time. It does this by forwarding the message from the user to the webhook (the listener).

2.  The bot decides what to do

Once the bot has your user’s message, it needs to take an action. If your bot is a basic one, it might just reply with some stock information. But in some cases, your bot will need to draw information from other sources first. It does this by reaching out to other APIs (the far-right side of the diagram).

API? What’s that?

API stands for Application Programming Interface. In simple terms, it’s a way for computers to talk to each other.

Facebook has a public API for Workplace – so by reading their documentation, I’ll be able to write my code in a way that lets it interact with Workplace.

You might be wondering where our bot sits in all of this. After all, as we explained last week, a bot is just a computer program – it’s a piece of code.

In many cases, the bot will be running on a cloud hosted service. In our example here, it’s running on Heroku (the purple square in the diagram).

Heroku? What’s that?

Heroku is a cloud services provider. That means that you can upload your code onto their platform, and they’ll manage all of the stuff you don’t want to worry about – things like servers, firewalls, patching, and updates.

There are lots of other cloud services providers you could use. I’ve chosen Heroku for this tutorial because it’s simple and reliable (it’s built on top of Amazon Web Services) and best of all, it’s free for development applications!

3.  The bot sends a message back to the user

Once our bot has reached out to any services it needs to get more information, it’s ready to send a reply back to the user. It does this through another API (Facebook’s Graph API).

Once the user has their reply, they might then send another message through the chat – and the whole loop can start all over again.

But how does the bot communicate?

Most communication over the internet happens with HTTP or HTTPS – and our bot will be no different.

HTTP? What’s that?

Hypertext Transfer Protocol (HTTP) is a fancy name for one of the ways computers talk over the internet.

The extra ‘S’ in HTTPS stands for ‘secure’. That means that the traffic has been encrypted before it’s sent down the wire. Facebook requires that we communicate over HTTPS.

To understand how HTTP and HTTPS work, we need to look at ‘HTTP verbs’.

In the human world, there are different stages to communication. We can ask for information, and we can send information.

In the world of HTTP, things aren’t much different:

If we’re asking for information, we perform a GET.

And if we’re sending information, we perform a POST.

There are plenty of other HTTP verbs beyond these two basic ones. But for the purposes of this tutorial (and, to be fair, for most professional work in Workplace bot development) we’ll only need to worry about these two: GET and POST.

So how does this work in practice?

When the user types a message in a chat with our bot, Workplace will POST the user’s message to us. Our application will GET information by reaching out to other services – and then our application will POST a message back to the user through Facebook’s Graph API.

Simple, right?

Well, things are about to get a little bit dense. But don’t worry: it’s only a shopping list.

 

What will I need to make a bot?

Before we can get started on building our first bot, we’re going to need a few tools. Quite a few tools, in fact.

You’ll need all of these tools to complete this tutorial. And with the exception of Workplace itself, they’re all free – so I recommend that you go ahead and download and install all of them now.

Here’s what you’ll need:

  • A premium instance of Workplace (you’ll need to be an admin)
  • An account with Heroku (the cloud services provider we mentioned before)
  • The Heroku CLI (the Command Line Interface for Heroku)
  • NodeJS (a JavaScript runtime – I’d recommend that you get the LTS version). This will also install something called Node Package Manager (NPM)
  • GIT (a source control system)
  • ngrok (to let you test out URLs)
  • And Postman (an API manager)
  • Visual Studio Code. (you’ll write your code with this)

We’re going to be writing our application in JavaScript, which is a programming language that’s rather ‘messy’.

Programming language? What’s that?

A programming language is a system of instructions used to tell a program (such as a bot) what to do.

There are lots of different languages, such as JavaScript, Python, C#, and C++. They each have their own little quirks that you’ll come to love or hate.

For a beginner, I’d recommend either JavaScript or Python – and personally, I lean towards JavaScript.

So to help you out with the messiness of JavaScript, I’d also recommend the following plug-ins for Visual Studio Code. They’re optional, but they will make it easier for you to read your JavaScript:

That’s a long list of tools. And if it all seems a bit intimidating now, don’t worry: I’ll be with you through every step of this tutorial as you start to put them all to use.

And if you really do get stuck, don’t hesitate to contact me via Workplace or email.

 

A few notes about JavaScript

Bots can be programmed in lots of different languages. For this tutorial, we’re going to use JavaScript on top of NodeJS – because that’s what Facebook’s own example applications are written in.

NodeJS? What’s that?

NodeJS is the platform that your JavaScript bot will run on.

Just like your web browser runs on an operating system (like Windows or macOS, or Android or iOS if you’re on a mobile), your bot needs something to run on. And in the JavaScript world, that something is NodeJS.

NodeJS is based on the same engine as Google Chrome – so if you learn how to program a bot with NodeJS, you’re well on your way to knowing how to make websites, too.

So, back to JavaScript:

JavaScript is a superb choice for a programming language, but it does have a few quirks that might confuse a beginner.

Imagine that you’ve written a set of instructions for your bot that includes two commands:

Command 1 – Say ‘Hello’, then wait 5 seconds and say ‘Nice to meet you’.

Command 2 – Say ‘Goodbye’.

Most people would expect those commands to give the following output:

Hello

Nice to meet you

Goodbye

But in practice, what you’ll really see is this:

Hello

Goodbye

Nice to meet you

That’s because NodeJS executes every command as soon as it sees it. In other words, JavaScript is asynchronous.

Asynchronous? What’s that?

Most programming languages run the first command, and then they wait for it to finish before they run the second command. This means that they’re synchronous.

JavaScript is a little unusual in that it runs every command at the earliest opportunity. This means that JavaScript is asynchronous.

It works this way for speed and efficiency – but it unfortunately makes your code a little harder to read. Luckily, there are new commands being built in to JavaScript to emulate synchronicity. If you’re interested, you can Google ‘ES6 async wait’ and ‘JavaScript Promises’ to learn more.

So JavaScript is asynchronous, which means it executes every command as soon it sees it. Whereas other programming languages would wait for the first command to finish before starting on the second command.

There won’t be a lot of asynchronous code in this tutorial. But it will become important when we start using APIs.

Imagine that your user makes a request to your bot, and your bot then contacts your HR system to get more information. If you’re not aware of the problems of asynchronous code, you might find that your bot sends a reply back to the user before the HR system has been able to give your bot all the information it needs.

You could try to avoid the problems of asynchronous code by learning a different programming language, such as Python, C# or C++.

That might make things a little easier in the beginning – but you will find that you’ll have fewer tutorials to turn to with these languages when you start to get stuck.

 

So what’s next?

By now, you should have a better understanding of how a bot operates – and you should have all of your development tools downloaded and installed and ready to go.

In my next blog post, you’ll send your first Workplace bot message using a tool called Postman.

Enjoyed this case study? Share!

Coolr thinking

Check out our latest news, blogs, cases studies and rants below.

Read more

Coolr story

We're doing things a little different at Coolr. We're part agency, part tech start-up, part consultancy - and we have big plans.

Learn more