AndyBot Botpress

The AndyBot server handles communication and coordination between Facebook and Andybot's APIs. It's function is to

1. Recieve webhooks from the Andrew Facebook app and record chatbot activity in a Postgres SQL Server
2. Send, message send requests to the Facebook Send API
3. Present content from activities.json configuration file
4. Make appropriate AndyBot API calls depending on user scans and responses

Background Reading

• Botpress documentation: https://botpress.io/docs/
• FB Messenger Platform Docs: https://developers.facebook.com/docs/messenger-platform

Prerequisites:

• Make sure git is installed
• Make sure you can connect to the database from the current machine
• Ensure that you have NodeJS 8.6.0 or above installed
• Ensure that your current machine is reachable over HTTPS from the internet

Environment Configuration and Important Environment Variables

These are a list of some of the important environment variables.

FB_APP_ID 
FB_APP_SECRET
FB_PAGE_ACCESS_TOKEN
FB_VERIFY_TOKEN

BOTPRESS_PASSWORD

PG_HOST
PG_PORT
PG_USER
PG_PASSWORD
PG_BOTPRESS_DB

We use the dotenv module to automatically load the environment variables in the .env file in the root directory. Please make sure you have pasted the correct environment configuration from the environments directory into that file before trying to run the app. These .env files must be kept secure.

Important Configuration Settings

In addition to the environment variables, there are other important configuration parameters in src/config.js. These include

1. hostname: 'bots.pagekite.me', This is the URL to which your FB app's webhooks will be configured to point to. Please note that you must not include the protoocol (i.e. http / https) in the hostname. Messenger will always ONLY use HTTPS so make sure your machine can he reached over HTTPS at this hostname.

2. staticUrl: 'https://static.andybot.org/static/' This is the URL for all CDN'd assets like images used by the bot throughout the experience

3. apiEndpoint: 'http://localhost:3001' This is the URL endpoint for the AndyBot API the bot should connect to. Please read more about andybot-express to set this up.

Developer Setup

1. git clone git@github.com:CMP-Studio/andybot-botpress.git

2. npm install -g yarn

3. cd andybot-botpress; yarn install;

4. You should have access to .env files for andybot-botpress. Make sure you paste the contents of andybot-dev.env into a file called .env in the root folder

5. cd andybot-botpress; yarn install;

6. node app.js

7. In a new terminal window, make sure you set up your secure web tunnel using pagekite.

8. Go to localhost:3000 and log in with the username studio and BOTPRESS_PASSWORD appropriately

9. Go to the Messenger tab.

10. Under "Connection" click "Disconnect / Reconnect" button. Once your configuration is saved successfully you should see a green indicator.

11. Make sure andybot-express API is accessible from your bot machine.

Botpress Basics

Botpress at it's core is an express application. When an incoming webhook is delivered, Botprss triggers a sequence of middleware the executes and responds to this request.

You can add custom handlers using bp.hear which will trigger your custom handlers.

Directory Structure and Important Files

What is Happening at Startup

When app.js runs, it starts a botpress server. This is a little different from the typicial, default botpress setup since

1. Unlike a simple botpress server, in our case messenger.config.yml and content.yml are dynamically generated at runtime from their cooresponding template file inside the src folder. This allows us to reuse code, easily reconfigure evironment specific parameters without having to maintain multiple environment specific .yml files. This happens within src/setup.js using the json2yaml package.

   • Please keep in mind that there are 2 types of templating syntaxes within x.template.yml files that provide for different use cases
   • <%=startupTimeVariableName%> - this syntax is used to substitute strings within the emitted .yml file. This templating will only happen once when you start up the app
   • {sendTimeVariable} - this syntax is used to substitute variables when sending a UMM message block. This templating happens every time a UMM block is sent in the code, for example when you call event.reply("#some_message_block") in your bot code.

2. We do not use botpress start to run our bot. Instead, the bot is started manually through the code in app.js, which will take care of building our YML templates and setting up Botpress.

Communication with Facebook

FB will send webhook requests when user's message the bot or sent messages have been delivered or read. The bot will also recieve webhooks when users click postbacks, quickreplies or scan entry codes.

Communication with API

When we find the user has taken certain actions, the botpress server will call to notify the andybot-express API and update the user's state.

Addding developers / testers

1. Go to developers.facebook.com
2. Browse to your app, go to the roles tab
3. Add user by name or FBID to the testers or developers group
4. Go to the business manager and choose the page you are looking for
5. Add the name or FBID of the person to the "Editors" group under the page
6. Make sure the person accepts their developer invite by going to developers.facebook.com

How to tell if you're able to test the bot? If you see a blue button that says Get Started on the bot's page, then you have been enabled as a tester. If you see a button that says Message you are not yet a tester.