Introduction

At Oracle Open World 2016, Larry Ellison demoed the upcoming Oracle Intelligent Bots Cloud Service (IBCS), if you haven’t seen the demo, you can watch the recording on youtube.

Chatbots employ a conversational interface that is both lean and smart, and if designed properly is even charming. Chat helps people find the things they want and need, as well as delivering great services and information directly into an interface they already know and love.Think about how much work it takes to compare and decide on which app to download. Then actually downloading it is never as easy as it sounds, and then the anxiety of where on your home screen to put it on, and then learning yet another new interface. Chatbots are the singularity that smart devices have been waiting for, the streamlined experience that will finally unshackle us from the burden that our apps put on our devices. For most of what we do on our mobile devices, the chatbot and chat interface are ideal.

Main Article

In this article, I’l go through a step-by-step guide on how to get started with chatbots and build your first Facebook chatbot. We will implement the bot using NodeJS and will deploy to Oracle Application Cloud Service ‘ACCS’, for more information on Oracle ACCS please click here. In a nutshell, below are the discussed topics:

• Create Facebook Page.
• Create Facebook App.
• Create Webhook and register with Facebook.
• Receive Facebook Messages
• Test using Facebook Messenger
• Deploy to ACCS

In order to proceed with this tutorial, you need to have a Facebook account and you should install Facebook Messenger on your mobile device.

Create Facebook Page

• Login to https://www.facebook.com with your Facebook credentials. From upper left corner, click the drop down menu and create a page.

Image may be NSFW.
Clik here to view.

• Choose any category, for example select ‘Company, Organization or Institution’, then specify a category and name and click ‘Get Started’. Make sure name is unique.

Image may be NSFW.
Clik here to view.

Image may be NSFW.
Clik here to view.

• Fill in the page description and URL. Use your imagination for values then press ‘Save Info’.

Image may be NSFW.
Clik here to view.

• Upload a page profile picture and then select ‘Next’.

Image may be NSFW.
Clik here to view.

• For step (3) and Step (4), you can easily press “Skip” leaving all default values. Now you can see your Facebook page, upload a cover page picture by clicking on the ‘Add Cover’ button.

Image may be NSFW.
Clik here to view.

• Click the ‘Add Button’ to add a ‘Send Message’ button.

Image may be NSFW.
Clik here to view.

Image may be NSFW.
Clik here to view.

• We need to get the ‘Page ID’ in order to configure our bot with it. From ‘More’ menu, select ‘Edit Page Info’. From the page details popup, under general tab, scroll to the bottom and click ‘See All Information’. The page details are shown, scroll to the bottom and note the ‘Facebook Page ID’ copy its value and keep it handy because we will use it later on.

Image may be NSFW.
Clik here to view.

Image may be NSFW.
Clik here to view.

Image may be NSFW.
Clik here to view.

Create Facebook App

Now you need to create a Facebook App and link it with your Facebook Page you created earlier, hence when users start chatting with your Facebook page, messages will be redirected to your Facebook app and consequently be delivered to your bot implementation.

• Login to https://developers.facebook.com with your Facebook credentials. Create a new Facebook App.

Image may be NSFW.
Clik here to view.

• Set the App display name, be creative, and from Category select ‘Messenger Bot’

Image may be NSFW.
Clik here to view.

• Scroll down to the ‘Token Generation’ section and from the Page drop down menu, select the page created earlier, notice that ‘Page access Token’ will get auto populated. Click on the ‘Page Access Token’ to copy it to the clipboard; keep it handy as we will use it later on.

if you navigate away from this page and then go back and selected the same page again, a new token will be generated, but the old token will still work, this is how Facebook designed their system.

Image may be NSFW.
Clik here to view.

• Scroll a bit down and you will see a section for ‘webhooks’; this is where you register your bot implementation webhook in order for Facebook to start sending you client & system messages.

This is where you will register your bot implementation web hook later on in order for Facebook to start sending you client & system messages. But we first need to build the web hook before we can register it!

Image may be NSFW.
Clik here to view.

Create Webhook

A Facebook webhook is an SSL enabled REST endpoint exposed publicly to the internet so Facebook can access it.For webhook implementation, we will use NodeJS; and in order to expose our webhook securely to Facebook, we will use the free tool ‘ngrok’ to create a secure tunnel (in the real world, your app will be deployed on a public API and a tunnel such as provided by ngrok is not necessary). Let us build now our simple webhook to complete the full Facebook bot lifecycle

• Create and initialize a new NodeJS app:

tqumhieh~ $mkdir chatbot
tqumhieh~ $cd chatbot
tqumhieh~/chatbot $npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help json` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg> --save` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
name: (chatbot) 
version: (1.0.0) 
description: Facebook chatbot
entry point: (index.js) app.js
test command: 
git repository: 
keywords: 
author: Tamer Qumhieh
license: (ISC) 
About to write to /Users/tqumhieh/chatbot/package.json:

{
  "name": "chatbot",
  "version": "1.0.0",
  "description": "Facebook chatbot",
  "main": "app.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Tamer Qumhieh",
  "license": "ISC"
}


Is this ok? (yes) 
tqumhieh~/chatbot $touch app.js
tqumhieh~/chatbot $

• We will be using nodejs ‘express‘ and ‘body-parser‘, so we need to add them to project dependencies:

npm install --save express body-parser

The first step in the Facebook webhook, is to register/subscribe your webhook with your Facebook App.To ensure this process, Your Facebook App and your webhook needs to exchange a couple of tokens. verify_token: this is an arbitrary text you define at Facebook App and within your webhook implementation; when youregister the Facebook App with your webhook, the token will be sent to your webhook, you need to compare the token received with the token defined in your code and if they both match reply back with the ‘hub.challenge’ value. hub.challenge: this is a Facebook auto-generated token that is sent to your webhook as a query param.

• Within the ‘app.js‘ file, copy the below code:

var express = require('express');
var bodyParser = require('body-parser');

var app = express();
app.set('port', 8081);
app.use(bodyParser.json());

var VERIFY_TOKEN = 'ateam';


app.get('/webhook', function (req, res) {
    if (req.query['hub.mode'] === 'subscribe' &&
        req.query['hub.verify_token'] == VERIFY_TOKEN) {
        console.log("Validating webhook");
        res.status(200).send(req.query['hub.challenge']);
    } else {
        console.error("Failed validation. Make sure the validation tokens match.");
        res.sendStatus(403);
    }
});

app.listen(app.get('port'), function () {
    console.log('Node app is running on port', app.get('port'));
});

• Run your nodejs app.

node app.js

• now your webhook is almost ready for registration, you need to expose it through an SSL tunnel to Facebook, the easiest is to use the free tool ‘ngrok’. Download ngrok from https://ngrok.com/download , unzip and form a command prompt navigate to the directory and Start ngrok.

  ngrok http 8081

  Note that the port 8081 is the same port defined in your webhook.

• Make sure the ‘session status’ is ‘online’. Now you have 2 URLS that are publicly accessible form the internet, one is SSL enabled and the other is not. Select and copy the ‘https‘ URL.

Note that you will have different URL combinations.

Image may be NSFW.
Clik here to view.

• Now back to Facebook developer portal https://developers.facebook.com , under the webhook section, click ‘setup Webhooks’.

Image may be NSFW.
Clik here to view.

• Set the callback URL to the ‘https’ URL you copied form ‘ngrok’ terminal and don’t forget to append (/webhook) to it which is the REST end point defined in your code. Set the verify token to (ateam) which is also defined in the webhook implementation code.

if you wish to set a different value here, make sure to set the same value for (VERIFY_TOKEN) variable in the webhook implementation code.

• Select (messages, messages_postback), this will instruct Facebook to forward all (text messages, buttons postbacks) to your webhooks, if you wish to receive more details like delivery/read reports, mark those down.
• Click ‘Verify and Save’; make sure no errors are thrown. You can check your IDE console, if nothing goes wrong, you should see ‘Validating webhook’ printed in the console window.

Image may be NSFW.
Clik here to view.

• Within the same webhooks section, make sure to select your Facebook page and click subscribe, that is how the Facebook Page is linked to the App through the Webhook.

Image may be NSFW.
Clik here to view.

• At this stage, you managed to successfully register your webhook with Facebook.

Note that if you closed your ‘ngrok’ terminal and started it again, you will get different URLS. Hence need to edit the webhook URL within your Facebook App. Surprisingly you need to go to a different window in order to do so. To Edit the webhook URL value, select ‘Webhook’ from the left navigation menu. If you can’t find a ‘webhook’ entry in the menu, then from the Left navigation menu, click ‘Add Product’ , and then look for ‘webhook’ and click the ‘Get Started’ button. Click the ‘Edit’ button in order to change the webhook URL and verification token.

Receive Facebook Messages

At this stage, your environment is successfully configured and setup to receive Facebook messages, now you need to add logic to your webhook implementation to intercept client messages. In order to intercept Facebook messages, you need to add a ‘POST’ endpoint to the same webhook URL defined before, however, this is very low level, we can always use a readymade framework that facilitates this process, a framework like ‘botly’ , check ‘botly’ github repo to learn more how to use it. To install nodeJS ‘botly’ framework.

npm install --save botly

• Change your webhook implementation code to use botly as below, make sure to update the value of the ACCESS_TOKEN and set it to the access token value copied before.

var VERIFY_TOKEN = 'ateam';
var ACCESS_TOKEN = 'YOUR ACCES TOKEN';


var express = require('express');
var bodyParser = require('body-parser');
var Botly = require('botly');
var botly = new Botly({
    accessToken: ACCESS_TOKEN,
    verifyToken: VERIFY_TOKEN,
    webHookPath: '/',
    notificationType:  Botly.CONST.REGULAR
});

botly.on('message', function (userId, message, data) {
    console.log(data);
});

botly.on("postback", function (userId, message, postback) {
    console.log(postback);
});


var app = express();
app.use(bodyParser.json());
app.use("/webhook", botly.router());
app.listen(8081);

• Run your updated code.

Test Using Facebook Messenger

You need to install Facebook Messenger on your mobile device. Start Facebook Messenger and within the Home screen, search for the Facebook page you created before, if you followed this guide naming, then this name is (A-Team). Notice the Page Description/ Picture/Cover photo that showed up are the same you specified in previous steps.

Image may be NSFW.
Clik here to view.

Image may be NSFW.
Clik here to view.

Image may be NSFW.
Clik here to view.

• Send any text message, for example (hello from Facebook messenger) and notice the same message printed in your IDE console window.

Image may be NSFW.
Clik here to view.

Image may be NSFW.
Clik here to view.

• To reply back with a text message, you can modify your botly.on(‘message’,…) block code as below:

botly.on('message', function (userId, message, data) {
    console.log(data);
    botly.sendText({id: userId , text : 'Hello back from BOT!!!'} , function(error , data)
    {
        if(error)
        {
            console.log(error);
        }
        else
        {
            console.log('message sent...');
        }
    });
});

• Now back to Facebook Messenger, if you send the message again, you should see a reply back.

Image may be NSFW.
Clik here to view.

• The power of Facebook Messenger is that it doesn’t only supports Text messages, but it also supports different kind of templates and message formats. To learn more about these templates visit Facebook Messenger Platform Guide / Templates.The easiest way to generate these templates from your BOT is to use ‘botly’ framework helper methods (sendButton, sendText, sendAttachment…) to learn the signature of these methods check the botly framework documentation on github. One last hint, if you generated and used buttons template; when user click on a button, the payload defined for that button is sent to your BOT and specifically to the below method.

botly.on("postback", function (userId, message, postback) {
    console.log(postback);
});

• It is worth checking Facebook Messenger ‘Greeting Text’ and ‘Getting Started Button’ in order to enhance UX.

Deploy to ACCS

• In order to deploy to ACCS, create a new (manifest.json) file at root level

Image may be NSFW.
Clik here to view.

• Use the code below as the content of the newly create (manifest.json) file. Note the value of the “command” attribute, you need to replace ‘app.js’ with the name of your nodejs main file.

{
  "runtime":{"majorVersion" : "6.3"},
  "command":"node app.js",
  "release" : {},
  "notes":""
}

• Within your main nodejs file, modify the ‘express’ app configuration as below (line 4). This will instruct your code to use a random port generated by ACCS if ACCS decides to do so for a reason or another.

var app = express();
app.use(bodyParser.json());
app.use("/webhook", botly.router());
app.listen( process.env.PORT || 8081);

• Package the content of your application as a zip file, you should zip the content of the root folder and not the folder itself. Navigate to ACCS console and make sure it is configured correctly with StorageCS. Within ‘ACCS’ console, select ‘Applications’ for the upper navigation menu. Then click ‘Create Application’. From the ‘Create Application dialog’, select ‘Node’.

Image may be NSFW.
Clik here to view.

• In the ‘Create Application’ dialog, set a ‘Name’, and upload the zip archive you created before. Set the ‘Memory’ to 5 GB. Click ‘Create’.

Image may be NSFW.
Clik here to view.

• After your application is deployed to ACCS, copy the application URL.

Image may be NSFW.
Clik here to view.

• Now you need to edit Facebook webhook and use the ACCS BOT URL instead of the URL generated by ngrok.

Summary

In this tutorial you learned the steps to create a basic Facebook chatbot and how to deploy it to Oracle ACCS. You can enrich the bot by introducing natural language processing ‘NLP’ frameworks to analyze and understand users intent when sending free text messages.

All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission