Merge pull request #1537 from botpress/rl_messenger

feat(channel-messenger): add messenger support

docs/guide/docs/build/channels.md

@@ -3,17 +3,15 @@ id: channels
 title: Messaging Channels
 ---
 
-## Built-in Channels
+## Converse API
 
-### JSON Channel
+The Converse API is an easy way to integrate Botpress with any application or any other channels. This API will allow you to speak to your bot and get an answer synchronously.
 
-The JSON Channel is an easy way to integrate Botpress with any application or any other channels. This API will allow you to speak to your bot and get an answer synchronously.
-
-#### Usage (Public API)
+### Usage (Public API)
 
 `POST /api/v1/bots/{botId}/converse/{userId}` where **userId** is a unique string identifying a user that chats with your bot (**botId**).
 
-##### Request Body
+#### Request Body
 
 ```json
 {
@@ -22,11 +20,11 @@ The JSON Channel is an easy way to integrate Botpress with any application or an
 }
 ```
 
-#### Usage (Debug API)
+### Usage (Debug API)
 
 There's also a secured route (requires authentication to Botpress to consume this API). Using this route, you can include more data to your response by using the `include` query params separated by commas.
 
-##### Example
+#### Example
 
 ```
 POST /api/v1/bots/{botId}/converse/{userId}/secured?include=nlu,state,suggestions,decision
@@ -39,7 +37,7 @@ Possible options:
 - **suggestions**: The reply suggestions made by the modules
 - **decision**: The final decision made by the Decision Engine
 
-##### API Response
+#### API Response
 
 This is a sample of the response given by the `welcome-bot` when its the first time you chat with it.
 
@@ -74,13 +72,22 @@ This is a sample of the response given by the `welcome-bot` when its the first t
 }
 ```
 
-#### Caveats
+### Caveats
 
 Please note that for now this API can't:
 
 - Be used to receive proactive messages (messages initiated by the bot instead of the user)
 - Be disabled, throttled or restricted
 
-## Other Channels
+## Messenger
+
+Please refer to the [README](https://github.com/botpress/botpress/blob/master/modules/channel-messenger/README.md) for installation details.
+
+## Troubleshooting
+
+- When testing on localhost, we recommend using services like [pagekite](https://pagekite.net/), [ngrok](https://ngrok.com) or [tunnelme](https://localtunnel.github.io/www/) to expose your server.
+- Make sure the `EXTERNAL_URL` environment variable is set so that your assets are accessible from the outside.
+
+# Other Channels
 
 We are in the progress of adding many more channels to Botpress Server. If you would like to help us with that, [pull requests](https://github.com/botpress/botpress#contributing) are welcomed!

modules/builtin/src/content-types/carousel.js

@@ -41,9 +41,50 @@ function render(data) {
   ]
 }
 
+function renderMessenger(data) {
+  const renderElements = data => {
+    return data.items.map(card => ({
+      title: card.title,
+      image_url: card.image ? url.resolve(data.BOT_URL, card.image) : null,
+      subtitle: card.subtitle,
+      buttons: (card.actions || []).map(a => {
+        if (a.action === 'Say something') {
+          throw new Error('Channel-Messenger carousel does not support "Say something" action-buttons at the moment')
+        } else if (a.action === 'Open URL') {
+          return {
+            type: 'web_url',
+            url: a.url,
+            title: a.title
+          }
+        } else {
+          throw new Error(`Channel-Messenger carousel does not support "${a.action}" action-buttons at the moment`)
+        }
+      })
+    }))
+  }
+
+  return [
+    {
+      type: 'typing',
+      value: data.typing
+    },
+    {
+      attachment: {
+        type: 'template',
+        payload: {
+          template_type: 'generic',
+          elements: renderElements(data)
+        }
+      }
+    }
+  ]
+}
+
 function renderElement(data, channel) {
   if (channel === 'web' || channel === 'api' || channel === 'telegram') {
     return render(data)
+  } else if (channel === 'messenger') {
+    return renderMessenger(data)
   }
 
   return [] // TODO Handle channel not supported
@@ -67,7 +108,6 @@ module.exports = {
       ...base.typingIndicators
     }
   },
-
-  computePreviewText: formData => `Carousel: ${formData.length}`,
+  computePreviewText: formData => `Carousel: (${formData.items.length}) ${formData.items[0].title}`,
   renderElement: renderElement
 }

modules/builtin/src/content-types/image.js

@@ -22,9 +22,34 @@ function render(data) {
   ]
 }
 
+function renderMessenger(data) {
+  return [
+    {
+      type: 'typing',
+      value: data.typing
+    },
+    {
+      attachment: {
+        type: 'template',
+        payload: {
+          template_type: 'generic',
+          elements: [
+            {
+              title: data.title,
+              image_url: url.resolve(data.BOT_URL, data.image)
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+
 function renderElement(data, channel) {
   if (channel === 'web' || channel === 'api') {
     return render(data)
+  } else if (channel === 'messenger') {
+    return renderMessenger(data)
   }
 
   return [] // TODO Handle channel not supported

modules/builtin/src/content-types/single_choice.js

@@ -24,9 +24,28 @@ function render(data) {
   ]
 }
 
+function renderMessenger(data) {
+  return [
+    {
+      type: 'typing',
+      value: data.typing
+    },
+    {
+      text: data.text,
+      quick_replies: data.choices.map(c => ({
+        content_type: 'text',
+        title: c.title,
+        payload: c.value.toUpperCase()
+      }))
+    }
+  ]
+}
+
 function renderElement(data, channel) {
   if (channel === 'web' || channel === 'api' || channel === 'telegram') {
     return render(data)
+  } else if (channel === 'messenger') {
+    return renderMessenger(data)
   }
 
   return [] // TODO Handle channel not supported

modules/builtin/src/content-types/text.js

@@ -20,9 +20,23 @@ function render(data) {
   ]
 }
 
+function renderMessenger(data) {
+  return [
+    {
+      type: 'typing',
+      value: data.typing
+    },
+    {
+      text: data.text
+    }
+  ]
+}
+
 function renderElement(data, channel) {
   if (channel === 'web' || channel === 'api' || channel === 'telegram') {
     return render(data)
+  } else if (channel === 'messenger') {
+    return renderMessenger(data)
   }
 
   return [] // TODO

modules/channel-messenger/.gitignore

@@ -0,0 +1,7 @@
+/bin
+/node_modules
+/dist
+/assets/web/
+/assets/config.schema.json
+botpress.d.ts
+global.d.ts

modules/channel-messenger/README.md

@@ -0,0 +1,86 @@
+# Channel-Messenger
+
+## Requirements
+
+Messenger requires you to have a Facebook App and a Facebook Page to setup your bot.
+
+### Create your Facebook App
+
+Go to your [Facebook Apps](https://developers.facebook.com/apps/) and create a new App.
+
+![Create App](assets/messenger-app.png)
+
+### Enable Messenger on your App
+
+Go to Products > Messenger > Setup
+
+![Setup Messenger](assets/messenger-setup.png)
+
+### Create a Facebook Page
+
+1. In Products > Messenger > Settings > Create a new page.
+1. Then select the newly created page in the `Page` dropdown menu.
+1. Copy your Page Access Token, you'll need it to setup your webhook.
+
+![Create Facebook Page](assets/messenger-page.png)
+
+### Setup your webhook
+
+Messenger will use a webhook that you'll need register in order to communicate with your bot.
+
+1. In Products > Messenger > Settings > Webhooks > Setup Webhooks
+
+1. In Callback URL, enter your secured public url and make sure to point to the `/webhook` endpoint.
+1. Paste your Page Access Token in the Verify Token field.
+1. Make sure `messages` and `messaging_postbacks` are checked in Subscription Fields.
+
+> **⭐ Note**: When you setup your webhook, Messenger requires a **secured public** address. To test on localhost, we recommend using services like [pagekite](https://pagekite.net/), [ngrok](https://ngrok.com) or [tunnelme](https://localtunnel.github.io/www/) to expose your server.
+
+![Setup Webhook](assets/messenger-webhook.png)
+
+### Add your token to your module config file
+
+Head over to `data/bots/<your_bot>/config/channel-messenger.json` and edit your info or create the file if it doesn't exists.
+
+```json
+{
+  "$schema": "../../../assets/modules/channel-messenger/config.schema.json",
+  "verifyToken": "<your_token>",
+  "greeting": "This is a greeting message!!! Hello Human!",
+  "getStarted": "You got started!",
+  "persistentMenu": [
+    {
+      "locale": "default",
+      "call_to_actions": [
+        {
+          "title": "Bot's Menu",
+          "type": "nested",
+          "call_to_actions": [
+            {
+              "type": "web_url",
+              "title": "Latest News",
+              "url": "https://news.google.com",
+              "webview_height_ratio": "full"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Configuration
+
+The config file for channel-messenger can be found at `data/bots/<your_bot>/config/channel-messenger.json`.
+
+| Property       | Description                                                                                                                                                                                                                                                               |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| verifyToken    | The Facebook Page Access Token                                                                                                                                                                                                                                            |
+| greeting       | The optional greeting message people will see on the welcome screen. Greeting will not appear if left blank.                                                                                                                                                              |
+| getStarted     | The optional message of the welcome screen "Get Started" button. Get Started wont appear if this is left blank.                                                                                                                                                           |
+| persistentMenu | The optional raw persistent menu object. The menu won't appear if this is left blank. Please refer to Facebook's [Persistent Menu Documentation](https://developers.facebook.com/docs/messenger-platform/send-messages/persistent-menu/) to know more about menu options. |
+
+## More details
+
+If you need more details on how to setup a bot on Messenger, please refer to Facebook's [documentation](https://developers.facebook.com/docs/messenger-platform/getting-started/app-setup) to setup your Facebook App and register your webhook.

modules/channel-messenger/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "channel-messenger",
+  "version": "1.0.0",
+  "description": "Messenger Channel for Botpress",
+  "private": true,
+  "author": "Botpress, Inc.",
+  "license": "AGPL-3.0-only",
+  "main": "dist/backend/index.js",
+  "devDependencies": {
+    "module-builder": "file:../../build/module-builder"
+  },
+  "scripts": {
+    "build": "./node_modules/.bin/module-builder build",
+    "watch": "./node_modules/.bin/module-builder watch",
+    "package": "./node_modules/.bin/module-builder package"
+  }
+}

modules/channel-messenger/src/backend/index.ts

@@ -0,0 +1,22 @@
+import 'bluebird-global'
+import * as sdk from 'botpress/sdk'
+
+import { MessengerService } from './messenger'
+
+const onServerStarted = async (bp: typeof sdk) => {
+  const messengerService = new MessengerService(bp)
+  messengerService.initialize()
+}
+
+const onServerReady = (bp: typeof sdk) => {}
+
+const entryPoint: sdk.ModuleEntryPoint = {
+  onServerReady,
+  onServerStarted,
+  definition: {
+    name: 'channel-messenger',
+    fullName: 'Messenger Channel'
+  }
+}
+
+export default entryPoint