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:
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