Botium Connector for Facebook Webhooks

This is a Botium connector for testing your Facebook Messenger Platform Webhooks.

Did you read the Botium in a Nutshell articles ? Be warned, without prior knowledge of Botium you won't be able to properly use this library!

How it works ?

Botium emulates the Facebook Messenger Platform

• It sends inbound messages to your webhook
• It listens for outbound messages from your webhook

Redis is used to connect the webhook to Botium scripts: all messages received over the webhook are published to Redis, and Botium on the other end subscribes to those Redis channels before running a conversation.

You have to setup your webhook to send outbound messages to the endpoint started with botium-cli inbound-proxy instead of the real Facebook endpoint at https://graph.facebook.com. Depending on the technology you are using, there are several options to do this:

• If your technology allows to simply change the endpoint url, then this is the preferred way
• If you are using Node.js, there is a demo in samples/botkit-bot how to use Nock to intercept network traffic to the original Facebook endpoint
• You can try to configure a HTTP-Proxy for your technology

It can be used as any other Botium connector with all Botium Stack components:

• Botium CLI
• Botium Bindings
• Botium Box

Requirements

• Node.js and NPM
• a Facebook Messenger Platform Webhook
• a Redis instance (Cloud hosted free tier for example from redislabs will do as a starter)
• a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Facebook Webhook Connector

When using Botium CLI:

> npm install -g botium-cli
> npm install -g botium-connector-fbwebhook
> cd <your working dir>
> botium-cli init
> botium-cli run

When using Botium Bindings:

> npm install -g botium-bindings
> npm install -g botium-connector-fbwebhook
> botium-bindings init mocha
> npm install && npm run mocha

When using Botium Box:

Already integrated into Botium Box, no setup required

Connecting your Facebook Webhook to Botium

Open the file botium.json in your working directory and add the webhook url and Redis connection settings.

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "fbwebhook",
      "FBWEBHOOK_WEBHOOKURL": "...",
      "SIMPLEREST_INBOUND_REDISURL": "redis://127.0.0.1:6379"
    }
  }
}

Botium setup is ready, you can begin to write your BotiumScript files.

Important: The inbound-proxy command has to be started with Botium CLI. Otherwise, Botium scripts will fail to receive any input or output messages from your chatbot!

Facebook Referrals

For simulating referral parameters (see Facebook Docs), the UPDATE_CUSTOM logic hook can be used.

Simulating an m.me-link with a referral parameter:

#me
UPDATE_CUSTOM SET_FB_REFERRAL_MME|some referral parameter

Simulating another referral type by specifying JSON code:

#me
UPDATE_CUSTOM SET_FB_REFERRAL|{"ref": "<REF_DATA_IF_SPECIFIED_IN_THE_AD>", "ad_id": "<ID_OF_THE_AD>", "source": "ADS", "type": "OPEN_THREAD", "ads_context_data": {"ad_title": "<TITLE_OF_THE_AD>", "photo_url": "<URL_OF_THE_IMAGE_FROM_AD_THE_USER_IS_INTERESTED_IN>", "video_url": "<THUMBNAIL_URL_OF_THE_VIDEO_FROM_THE_AD>", "post_id": "<ID_OF_THE_POST>"}}

Running the Samples

Install botium-core as peerDependency

> npm install --no-save botium-core

Afterward in the folder samples/botkit-bot there is an example for a simple Facebook Webhook chatbot - it is one of the samples of Botkit. Start the webhook:

> cd samples/botkit-bot && npm install && npm run start:botium

Finally navigate into the samples/simple and run npm install, start the inbound proxy server and run the test itself with the following commands:

 > cd samples/simple
 > npm install
 > npm run inbound
 > npm test

Supported Capabilities

Set the capability CONTAINERMODE to fbwebhook to activate this connector.

FBWEBHOOK_WEBHOOKURL

The URL of your Facebook Messenger Platform webhook

FBWEBHOOK_TIMEOUT

Webhook timeout in milliseconds (default: 10000 = 10 seconds)

FBWEBHOOK_PAGEID

If your webhook expects a special Facebook Page ID to process messages, you can add one here (default: 123456)

The Facebook Page ID can also be set in the test case spec itself:

#begin
UPDATE_CUSTOM FBWEBHOOK_PAGEID|77777777

FBWEBHOOK_USERID

If your webhook expects a special Facebook User ID to process messages, you can add one here (default: 10 random digits)

The Facebook User ID can also be set in the test case spec itself:

#begin
UPDATE_CUSTOM FBWEBHOOK_USERID|66666666

FBWEBHOOK_APPSECRET

If your webhook is validating the X-Hub-Signature-header (it should!), then you have to give the Facebook App Secret to Botium to be able to generate this signature (default: empty)

Open Issues and Restrictions

• Currently only plain text, quick replies, buttons and cards are supported
• Currently only individual receivers supported