- Theory and tools
- Send a test message with Postman
- Send a message with code
- Connect a Workplace integration to our code
- Receive a message from Workplace
- 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:
- The user talks to the bot in Workplace
- Workplace sends that message to our application
- The bot decides what to do
- 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.
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)
- 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)
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.
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.
NodeJS? What’s that?
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.
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:
Nice to meet you
But in practice, what you’ll really see is this:
Nice to meet you
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.
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.