Botmaster | Messenger | Watson Conversation

Powered by

Botmaster framework with IBM Watson Conversation dependencies to deploy Facebook messenger bot. Botmaster is a lightweight highly extendable, highly configurable chatbot framework. It was meant to be used both in small scale and large scale projects. Its purpose is to integrate your chatbot into a variety of messaging channels.

Before you begin

• Create a Bluemix account
  • Sign up in Bluemix, or use an existing account. Your account must have available space for at least 1 app and 1 service.
• Make sure that you have the following prerequisites installed:
  • The Node.js runtime (including the npm package manager)
  • The Cloud Foundry and BlueMix command-line client

Getting Watson Conversation Credentials

In order for Watson Conversation to integrate with Botmaster, the following credentials are required

• Service Credentials
• Conversation Workspace ID

Service Credentials

---

1. Find your service within BlueMix and click to view the service details screen ![Find your service] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/services.png?raw=true)
2. From this screen click the "Service Credentials" tab
3. Copy the username and password information (we will use this later when connecting our conversation to Botmaster)

Conversation Workspace ID

---

1. Open the conversation instance you have created
2. In the service instance detail click "Launch Tool"
3. Once in the Conversation tooling locate your conversation workspace
4. Click the menu located top right and select "View Details"


5. Copy your workspace ID and make note (we will use this with service credentials to connect our Watson Conversation to Botmaster)

###Set up your Facebook page

In order to connect to Facebook messenger, you must first have a Facebook Developers account and page created.

[Click here to see how] (https://medium.com/@yrezgui/setup-your-first-messenger-chatbot-a28482a407d4#.k2f7xpobi)

Getting Started with Botmaster on BlueMix

If you wish to simply deploy a Botmaster instance without having to edit any of the pre existing code or do not wish to connect any additional API or additional functionality, use the steps below.

1. In order to setup botmatser and a webhook for messenger to link to your Watson conversation we first need to deploy a BlueMix application. So go ahead and hit the button.

2. Log into BlueMix
3. Give you application a unique name (this will be the URL for the base of your webhook e.g wwww.helloworld.mybluemix.net/webhook)
4. Select the space and organisation to deploy to. ![Name your application] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/bluemixname.png?raw=true)
5. Once complete you will be presented with this screen, now you can click edit code if you wish to add additional functionality. ![Success deployment] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/success.png?raw=true)
6. Once successfully deployed, go to your BlueMix app dashboard and view your app. ![Success deployment] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/appdetail.png?raw=true)
7. Select Runtime followed by Environment Variables ![Success deployment] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/envvar.png?raw=true)
8. Populate these fields with the required information
9. Hit save to restart your application

Connecting Facebook

6. Go to your Facebook Developer page for your application
7. Under Webhooks, create "New Subscription" for pages ![Facebook Webhook] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/facebookwebhook.png?raw=true)
8. In the callback URL field, paste in your app URL from BlueMix using your webhook by default this is set to /webhook (e.g myapp.bluemix.net/messenger/webhook) or in code line 23
9. Enter your verify token you created in Environent Variables or in code Line 18
10. Select the following fields messages, messaging_postbacks
11. Once your webhook is set up you need to subscribe to events within messenger
12. Go to Messenger in the Facebook Developer portal product tab
13. Go to Settings
14. Locate Webhooks
15. Subscribe your event to the page you created ![Subscribe Webhook] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/messengerevent.png?raw=true)

Getting started with Botmaster Locally

The best way to begin to utilise Botmaster is to run the app locally. This will allow you to customise the code if you so wish. If however you are happy with what is already included go ahead and skip to Getting Started with Botmaster on BlueMix.

Begin by changing to the directory of this repository you have just cloned or downloaded.

• This can be done via command line e.g cd Desktop/Botmaster-FBMessenger-Watson

To customise your Botmaster framework, such as adding additional actions or API services find documentation here [Botmaster Documentation] (https://Botmasterai.github.io/)

As described in the botmaster docs on webhooks You can use the command npm run tunnel. Make sure to edit the subdomain with something appropiate for your app.

Otherwise lets get going!

Connecting IBM Watson Conversation & Facebook Messenger

<<<<<<< Updated upstream You will notice within the repository files is a manifest-example.yml file. Copy this file and call it manifest.yml. This file is where we will enter our credentials to connect Botmaster to IBM Watson Conversation and Facebook Messenger. In order to achieve this change the following lines with your information.

You will notice within your Bluemix application, in the the runtime tab locate the Environment Variables section. This is where we will enter our credentials to connect Botmaster to IBM Watson Conversation and Facebook Messenger. In order to achieve this change the following lines with your information you have gathered previously.

Stashed changes ![Environment Variables] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/env.png?raw=true)

##Logging into BlueMix BlueMix is where we will host our application, therefore we will make use of the cloud foundry to help us manage and push the application.

1. Open terminal or command prompt
2. Set the API endpoint of your BlueMix space
   • cf api https://api.ng.bluemix.net - US South
   • cf api https://api.eu-gb.bluemix.net - UK
3. Login to BlueMix using:
   • cf login
   • Enter your email address of your BlueMix account
   • Hit enter
   • Enter your password of your BlueMix Account (it will appear your password is not typing)
   • Hit enter
4. Select your space following on screen prompt
5. To confirm and check which region, org and space is currently targeted type:
   • cf target

Once you have successfully logged in and targetted BlueMix you can now push your application to BlueMix.

##Pushing to BlueMix Once you have finished working on your application you can now push this to BlueMix to be hosted. Using the steps above login to BlueMix.

1. Open terminal or command prompt
2. Login to BlueMix
3. Change directory to your repository using cd yourrepository
4. Use the following command to push to BlueMix cf push
   • Note: Before you use cf push ensure you have edited the manifest.yml file. You will need to update lines 6 and 7 using the unique name of your application

#Exporting Your Conversation If you wish to export your conversation in the raw .json format to share with others or backup, this can be achieved by following:

1. Log into BlueMix
2. Locate your conversation service
3. Within your conversation service locate you conversation instance ![Conversation instance] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/instance.png?raw=true)
4. Using the menu in the top right of the conversation instance ![Menu icon] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/menuicon.png?raw=true)
5. Click "Download as JSON" ![Conversation instance] (https://github.com/ReeceMed/Botmaster-FBMessenger-WatsonConversation/blob/master/readmeimages/instance.png?raw=true)

#Using Fulfil Botmaster now has an official middleware that allows you to truly enrich your conversation by using custom XML tags within your chatbot. Commands that can be used with this repository that are already integrated are:

#Additional Links

Botmaster Documentation : [Botmaster Documentation] (https://Botmasterai.github.io/)

Facebook Messenger Webhook Reference : [Facebook Webhooks] (https://developers.facebook.com/docs/messenger-platform/webhook-reference#setup)

Watson Conversation Documentation : [Watson Conversation] (http://www.ibm.com/watson/developercloud/doc/conversation/index.html)

Santa Bot Example App : [Santa Bot] (fb.me/santachatbot)