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

Sending a message with Postman

In the last part of our bot-building tutorial, we looked at the basics of how a bot works – and we also went through a detailed shopping list of all the tools and plug-ins you’ll need to create your own bot.

Today, we’re going to create an integration and send out our first test message. And once we’ve managed that, we’ll be ready to send a real message through our application in the next tutorial session.

Ready? Let’s get started:

Once you’ve launched Postman, close the welcome message and you should come to this screen:

Postman

We’re going to send information to Facebook’s Graph API by performing a POST.

(Remember our last lesson? We use a POST when we want to send information, and we use a GET when we want to ask for information.)

Here are the steps we need to take:

 

1. Setting up your POST

The first thing we need to do is change that ‘GET’ to a ‘POST’ by using the drop-down menu on the left (the grey box in the image that says ‘GET’).

Next, we’ll need to specify an URL to send it to. That’s the box right next to our drop-down menu.

Facebook’s documentation tells us that all requests need to be sent to https://graph.facebook.com/.

But there’s a little more to it than that – different functions are sent to different edges.

 

Edge? What’s that?

An edge is an extension to the Graph API URL. That might sound complicated, but you can think of it like a set of folders and subfolders – similar to the structure of an URL on a normal website.

There’s an edge for each type of data – such as groups, users, or events. And most of these edges have their own sub-edges.

So if I wanted to find all the members in a particular group, I’d perform a GET request to this URL:

https://graph.facebook.com/group/members

 

In our particular case, we want to send a message.

And to do that, we need to use a subsection of the Graph API called the Send API.

The Send API lives on an edge called /me/messages. So to send a message, we’ll need to make a POST to the following URL:

https://graph.facebook.com/me/messages

If you’re getting a little confused here, don’t worry. It’ll make more sense once you try it out in Postman.

So for now, you should have:

  • Launched Postman
  • Changed GET to POST in the drop-down menu
  • And entered the URL above into the field next to the drop-down menu.

Wait – why is the documentation different?

If you’ve been reading Facebook’s documentation, you might have noticed that they suggest a slightly different URL:

https://graph.facebook.com/v3.3/me/messages

That’s an URL that specifies which version of the Graph API you want to use (in the URL from the documentation, that’s version 3.3).

The Graph API is constantly evolving. And by the time you read this, we might be on a newer version (3.4 or higher).

So why is specifying the version important?

Every time Facebook changes the API, there’s a risk that something you rely on has changed.

So by adding something like “/v3.3/” into the URL, you can force your request through a particular version of the API that works for what you need.

If you leave that part out, you’re not specifying any version – and Workplace will automatically use the latest version of the API instead.

 

2. Finding a user

Before we can send a message, we need to know who we’re going to send it to.

And that means we need to find the user’s Universally Unique Identifier (UUID).

Luckily for us, that’s easy to do in Workplace:

You can see someone’s UUID by navigating to their Workplace profile and looking for the long number in the URL at the top of the page:

UUID

So on my profile, you can see that my UUID is 100028418687930.

And we’ll need that number for the next step:

 

3. Coding your message

Before we can send our message to a user, we need to create our first bit of code.

Don’t be scared! I’ll talk you through it.

We’re going to POST something called JSON to the Graph API.

JSON? What’s that?

JSON is short for ‘JavaScript Object Notation’. It’s a way for applications to store data, or to transfer it to another application.

It’s made up of pairs of names and values – all of which are contained in curly brackets. So if I wanted to store information about a pet, I might do it like this:

{

            Pet:      {

                        “type”: “dog”,

                        “colour”: “white”,

                        “nature”: “friendly”

          }

}

In this example, Type and Colour are names – and Dog and White are values.

So to send our message to a user, we need to POST our JSON to the Graph API.

Our UUID number is the value of “id” – and our actual message is the value of “text”:

{

     “recipient”: {

     “id”: “100028418687930 “

     },

     “message”: {

          “text”: “hello, world!”

      }

}

Let’s use the above JSON to send a message to ourselves in Workplace:

  • Back in Postman, look for the menu beneath the URL you entered earlier.
  • Click on ‘Body’.
  • Below that, click on ‘raw’.
  • To the right of that, use the drop-down menu to select ‘JSON (application/json)’.

And then just paste in the JSON code from above. It should look like this:

Postman Test Message

 

4. Creating an integration

To make our request secure (and to stop random people from using the API to message people in our organisation), we’ll need the equivalent of a username and password. In the world of Workplace, this equivalent is called an Access Token.

And to do that, we’ll need to create an integration.

We previously talked about the difference between ‘bot’ and ‘integration’ – and how these two terms are sometimes used interchangeably in Workplace.

(Remember: a bot is actually a subcategory of a Workplace integration.)

To secure our request, we’ll need to:

  • Create an integration
  • Configure it to be a bot
  • And get that integration’s Access Token (the equivalent of a username and password).

So to do that, let’s first head over to Workplace and open the admin page.

From there, you can open the Integration tab, and click the button that says ‘Create Custom Integration’.

For this tutorial, we can give our integration the name ‘Coolr-Bot-Tutorial’.

Creating an Integration

Next, you’ll want to have a look at the ‘Integration Permissions’ section.

Different bots will require different permissions, depending on what they do. But our simple chat bot will only need one: ‘message any member’.

It’s important to get into the habit of specifying permissions. You should only ever give your bots the permissions they need to do their specific job – and nothing else. This way, your bot will be much more secure against hackers.

 

5. Creating an Access Token

I said we would need the equivalent of a username and password to make our bot more secure. And for our Workplace integration, that security comes from an Access Token.

Technically, it’s called a bearer token – which is a long string of encrypted letters and numbers.

So how do we get one of those?

On the Integrations page, click on the ‘Create Access Token’ button.

Access Token

You should see the following warning screen pop up:

Token Warning

We want to select ‘In-house development’ and then click ‘Create Token’.

Facebook recently changed their model around how partners create integrations. So you should never need to select the other option (‘External developer’). That’s because companies like mine should be delivering their integrations through another channel.

That said, if any of your suppliers ever asks you to choose ‘In-house development’, that’s a big red flag!

Once you’ve clicked ‘Create Token’, you should see a screen like this:

Create Access Token

Copy your token, and then read the warning and click ‘I understand’.

Now this is important:

You’ll need to keep your token extremely safe. Once you click past this screen, you won’t be able to recover your token. You can create a new one, but that would cause the original one to stop working.

This token is basically a username and password – and you should treat it with the same level of care and caution. If a hacker were to get this token, they’d be able to message anyone in your company! 

Once you’re happy that you’ve copied the token and stored it somewhere safe, click ‘Done’, and then scroll to the bottom of the page and hit ‘Save’.

You should also navigate away from the admin panel at this stage – otherwise your bot’s message won’t be able to reach you when you test it. The easiest way to do this is to click on the Workplace logo in the top-left corner of the screen (click it twice if you’re using the new Workplace Look & Feel) to go back to your feed.

 

6. Testing your message

Head back over to Postman and look underneath the box where you entered the URL.

Select the ‘Authorization’ tab, and use the drop-down menu below ‘TYPE’ to switch it to ‘Bearer Token’.

In the box to the right marked ‘Token’, you can paste in the token that you’ve just created in Workplace.

Postman final settings

This is it! The moment of truth.

Click the blue ‘Send’ button, and then look at your Workplace window to see your bot’s first message!

Workplace Results Home Simpson - WooHoo

Well done! Take a moment to give yourself a pat on the back and realise how far you’ve come.

Through this tutorial series, you’ve managed to:

  • Set up your development environment
  • Create your first integration
  • And successfully send a test message to yourself.

So what’s next?

At this point I’d recommend you do two things before moving on:

First, click the ‘code’ button and have a look at the various different languages that Postman can requests for. Select NodeJs and then Request.

Creating code with Postman

I know it looks complicated but this is the kind of code we’ll be creating in the next few installments of the tutorial. Having setup Postman, we now have a nice graphical way of creating our final code.

Generated Code

Second, I’d love for you to have a look at the templates section of the Facebook documentation. Note that this links to the Facebook documentation, not Workplace. The reason I’ve done this is that the Send API is mostly identical on both platforms but the Facebook documentation is much more detailed and easy to understand.

This is your homework: give the documentation a read and see if you can send a more complicated message using a different JSON template. For example: you can get some really cool and engaging effects using the media template. The only bit that should change is what’s inside message: {}

In our next lesson, we’re going to take our “hello, world!” message and learn how to deliver it with NodeJS – and that’s when you can really start to call yourself a bot developer.

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