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

Receiving data from Workplace

In the last part of our bot-building tutorial, we set up and subscribed to a webhook – a listener that keeps its ears open for any messages our users send through our Workplace bot.

Today, we’re going to work with the data we receive from Workplace, and then test a reply message that we’ll send back to the user.

 

1. Creating a POST route

In our last tutorial, we talked about what happens when a user sends a message to our bot.

That message gets forwarded to our application’s webhook as an HTTPS POST.

Our application currently has a GET route. But it doesn’t have a POST route – and we’ll need one before we can continue. So let’s fix that now:

To begin with, we’re just going to:

  • Receive the data
  • Print the data to our debug console
  • And then reply to Workplace with a 200 response.

(Remember 200 responses from our last session? These are the ones that say that everything went well.)

So, first you’ll need to add the following route to your application:

app.post('/webhook', (req, res) => {
    console.log(req)
    res.sendStatus(200)
})

You can now (re)start your application and send a message to your bot from inside Workplace:

Sending a message to the bot

And if you head back to your debug console in VS Code, you should see that you’ve received some data:

Debug Console

Amazing! We can see in our debug console that we received some data.

Click on the little arrow next to the IncomingMessage object, and you’ll see lots of information.

This is the ‘req’ object that we echoed out using console.log(req) a few moments ago.

(‘req’ is just short for ‘request’ – but you can call it anything you like!)

As you can see in the image, this isn’t very easy to work with. So let’s do a few things to help improve that.

First, add a breakpoint next to the console.log(req) line. In the example below, that’s on line 41.

(Remember breakpoints? By adding a breakpoint to a certain line of code, it tells our application to stop when it gets to that line.)

Next, we’re going to head back into Workplace and say something new to our bot (you won’t need to restart your application).

But before we do that, we can do something to make our lives a little easier:

In the top-right hand corner of the debug console, there’s a button with a red X and a few horizontal lines (it’s highlighted with a red circle in the image below). This will clear your debug console, so you won’t get confused between the new data and the previous data.

Clear down your debug console and then head into Workplace and send a new message (‘something else’) to our bot:

Sending a message to the bot

Debug Console

Because we added that breakpoint, we can now see and interact with our ‘req’ object in the variables panel on the left-hand side.

Click on the arrow to expand the ‘req’ object, and look for a sub-object called ‘body’. Bodyparser has injected this object for us by parsing all the information Workplace sent over.

We’re now going to keep expanding sub-objects until we find our message. Here are the levels you’ll need to click through to get down to it:

req > body > entry > 0 > messaging > 0 > message

You should now see the text with the message we just sent to our bot: ‘something else’.

Right-click on the purple ‘text’, and then click on ‘Copy as Expression’. You can now use that to reference your message in your code.

Head back to the line of code that contains ‘console.log(req)’ – that’s the line where we added a breakpoint – delete ‘req’ and paste in the expression you just copied.

That line of code should now look like this:

console.log(req.body.entry[0].messaging[0].message.text)

Restart your application and remove your breakpoint (click the little red dot again so that it disappears), and then send another message through the bot in Workplace.

Debug Console

And there you go – you just received a message and echoed it out to the console!

 

2. Sending a reply to the user

Because we’ve already done all the donkey work, it’s actually really easy to reply.

We already have our sendMessage() function built. But that function needs two pieces of information:

  1. The UUID of the person we’re messaging
  2. The actual message we want to send.

(Remember UUID? That’s the Universally Unique Identifier – the ID code of a particular user in Workplace.)

Luckily, Workplace has already given us the UUID of the person who messaged our bot. So how do we find it?

Create a breakpoint at the ‘req’ line of code, and then send another message through your bot in Workplace.

Let’s see if you can find the UUID by expanding the sub-objects.

Couldn’t find it? Don’t worry, here’s the spoiler:

The UUID is contained in req.body.entry[0].messaging[0].sender.id

Now that we have the UUID of the user, we can send them a reply. Change your route to match the following:

app.post('/webhook', (req, res) => {
    let uuid = req.body.entry[0].messaging[0].sender.id
    let message = req.body.entry[0].messaging[0].message.text
    console.log('Received a message from', uuid, 'now replying')
    sendMessage(uuid, message)
    res.sendStatus(200)
})

You can now restart your app, remove any breakpoints – and then send a message through the bot in Workplace:

Sending a message to the bot. The bot echos that message back

The message is printed to the debug console

Do you know what this means? You just had a conversation with your very own bot!

It might not have been the most inspiring or creative conversation, but this is a huge step – and you now have all of the building blocks you’ll need to start building something awesome in the future.

At this point, you should know how to:

  • Receive messages from Workplace
  • Dig into those messages and pull out key information (like UUIDs and the text being sent)
  • Use Axios to make webservice calls to other systems
  • And send a response back to the user.

That covers every element of our original Bot Theory diagram from way back in Part 2 of this series. And that means you’ve come a long way!

Now would be a great time to check our code in – so let’s do that:

Checking code into GIT

 

A few quick notes on Ngrok

We’re almost ready for the final part of our tutorial series. But before we move on, I want to show you a little bit more of Ngrok – because we really haven’t done it justice yet.

As well as giving you a way of exposing your machine to the internet, Ngrok is also a powerful development tool. Let’s open it up and have a quick look.

Load the following URL in your browser:

http://127.0.0.1:4040

And you should see something like this:

Ngrok summary screen

This is Ngrok’s web interface.

On the left, you’ll see all the requests that have been sent to your Ngrok URL. If you’ve been following this tutorial, you’ll probably see lots of them here – all the requests we made while setting up our bot.

So why do we care about this?

When we’re in the process of creating code and debugging our application, things won’t always work perfectly (and that’s an understatement!).

When Workplace sees that an application isn’t replying or is generating errors, it’ll throttle requests to that application – and that can mean that Workplace stops sending your user messages to your webhook.

As you can imagine, this can make debugging truly frustrating.

But with Ngrok, we’re able to capture the first POST from Workplace and then replay (and even manipulate it) without having to go back into Workplace again.

This is hugely useful for testing and tweaking our code – without having to rely on Workplace while we do it.

 

So what’s next?

We’re getting seriously close to the end now! In the next and final part of our tutorial series, we’re going to take our baby bot and get it ready for the big wide world – by moving it from our local machine and migrating it onto the cloud.

Enjoyed this case study? Share!

Coolr thinking

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

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