Merge branch 'master' into unit

Author: colestrode

.gitignore

@@ -10,5 +10,5 @@ examples/db_team_bot/
 */.DS_Store
 .env
 .idea
-.vscode/settings.json
+.vscode
 coverage

.npmignore

@@ -0,0 +1 @@
+docs/provisioning/IMG

.vscode/launch.json

@@ -206,7 +206,7 @@ Adds [ConsoleBot](lib/ConsoleBot.js) for creating bots that work on the command
 
 Adds a new [Middleware Readme](readme-middlewares.md) for documenting the existing middleware modules
 
-Adds an example for using quick replies in the [Facebook Example Bot](facebook_bot.js)
+Adds an example for using quick replies in the [Facebook Example Bot](examples/facebook_bot.js)
 
 Adds additional fields to Facebook messages to specify if they are `facebook_postback`s or normal messages.
 
@@ -290,7 +290,7 @@ Make the oauth identity available to the user of the OAuth endpoint via `req.ide
 
 Fix issue where single team apps had a hard time receiving slash command events without funky workaround. (closes [Issue #108](https://github.com/howdyai/botkit/issues/108))
 
-Add [team_slashcommand.js](/examples/team_slashcommand.js) and [team_outgoingwebhook.js](/examples/team_outgoingwebhook.js) to the examples folder.
+Add [team_slashcommand.js](/examples/slack/team_slashcommand.js) and [team_outgoingwebhook.js](/examples/slack/team_outgoingwebhook.js) to the examples folder.
 
 
 

changelog.md

@@ -3,24 +3,24 @@
 
 These examples are included in the Botkit [Github repo](https://github.com/howdyai/botkit).
 
-[slack_bot.js](https://github.com/howdyai/botkit/blob/master/slack_bot.js) An example bot that can be connected to your team. Useful as a basis for creating your first bot!
+[slack_bot.js](https://github.com/howdyai/botkit/blob/master/examples/slack_bot.js) An example bot that can be connected to your team. Useful as a basis for creating your first bot!
 
-[spark_bot.js](https://github.com/howdyai/botkit/blob/master/spark_bot.js) An example bot that can be connected to Cisco Spark. Useful as a basis for creating your first bot!
+[spark_bot.js](https://github.com/howdyai/botkit/blob/master/examples/spark_bot.js) An example bot that can be connected to Cisco Spark. Useful as a basis for creating your first bot!
 
-[facebook_bot.js](https://github.com/howdyai/botkit/blob/master/facebook_bot.js) An example bot that can be connected to your Facebook page. Useful as a basis for creating your first bot!
+[facebook_bot.js](https://github.com/howdyai/botkit/blob/master/examples/facebook_bot.js) An example bot that can be connected to your Facebook page. Useful as a basis for creating your first bot!
 
-[twilio_ipm_bot.js](https://github.com/howdyai/botkit/blob/master/twilio_ipm_bot.js) An example bot that can be connected to your Twilio IP Messaging client. Useful as a basis for creating your first bot!
+[twilio_ipm_bot.js](https://github.com/howdyai/botkit/blob/master/examples/twilio_ipm_bot.js) An example bot that can be connected to your Twilio IP Messaging client. Useful as a basis for creating your first bot!
 
-[botframework_bot.js](https://github.com/howdyai/botkit/blob/master/botframework_bot.js) An example bot that can be connected to the Microsoft Bot Framework network. Useful as a basis for creating your first bot!
+[botframework_bot.js](https://github.com/howdyai/botkit/blob/master/examples/botframework_bot.js) An example bot that can be connected to the Microsoft Bot Framework network. Useful as a basis for creating your first bot!
 
-[examples/demo_bot.js](https://github.com/howdyai/botkit/blob/master/examples/demo_bot.js) another example bot that uses different ways to send and receive messages.
+[examples/demo_bot.js](https://github.com/howdyai/botkit/blob/master/examples/slack/demo_bot.js) another example bot that uses different ways to send and receive messages.
 
-[examples/team_outgoingwebhook.js](https://github.com/howdyai/botkit/blob/master/examples/team_outgoingwebhook.js) an example of a Botkit app that receives and responds to outgoing webhooks from a single team.
+[examples/team_outgoingwebhook.js](https://github.com/howdyai/botkit/blob/master/examples/slack/team_outgoingwebhook.js) an example of a Botkit app that receives and responds to outgoing webhooks from a single team.
 
-[examples/team_slashcommand.js](https://github.com/howdyai/botkit/blob/master/examples/team_slashcommand.js) an example of a Botkit app that receives slash commands from a single team.
+[examples/team_slashcommand.js](https://github.com/howdyai/botkit/blob/master/examples/slack/team_slashcommand.js) an example of a Botkit app that receives slash commands from a single team.
 
-[examples/slackbutton_bot.js](https://github.com/howdyai/botkit/blob/master/examples/slackbutton_bot.js) an example of using the Slack Button to offer a bot integration.
+[examples/slackbutton_bot.js](https://github.com/howdyai/botkit/blob/master/examples/slack/slackbutton_bot.js) an example of using the Slack Button to offer a bot integration.
 
-[examples/slackbutton_incomingwebhooks.js](https://github.com/howdyai/botkit/blob/master/examples/slackbutton_incomingwebhooks.js) an example of using the Slack Button to offer an incoming webhook integration. This example also includes a simple form which allows you to broadcast a message to any team who adds the integration.
+[examples/slackbutton_incomingwebhooks.js](https://github.com/howdyai/botkit/blob/master/examples/slack/slackbutton_incomingwebhooks.js) an example of using the Slack Button to offer an incoming webhook integration. This example also includes a simple form which allows you to broadcast a message to any team who adds the integration.
 
-[example/sentiment_analysis.js](https://github.com/howdyai/botkit/blob/master/examples/sentiment_analysis.js) a simple example of a chatbot using sentiment analysis. Keeps a running score of each user based on positive and negative keywords. Messages and thresholds can be configured.
+[example/sentiment_analysis.js](https://github.com/howdyai/botkit/blob/master/examples/slack/sentiment_analysis.js) a simple example of a chatbot using sentiment analysis. Keeps a running score of each user based on positive and negative keywords. Messages and thresholds can be configured.

docs/examples.md

@@ -0,0 +1,42 @@
+# Configure Botkit and Cisco Spark
+
+Setting up a bot for Cisco Spark is one of the easiest experiences for bot developers! Follow these steps carefully to configure your bot.
+
+### 1. Install Botkit
+
+The easiest path to creating a new bot for Cisco Spark is through Botkit Studio. [Sign up for an account here](https://studio.botkit.ai/signup/). This method will provide a guided path to hosting, along with other useful tools for creating and managing your bot.
+
+For advanced users looking to run their own code, you will need to [install Botkit](../readme-ciscospark.md#getting-started) and run it before your bot can be configured with Cisco Spark. 
+
+### 2. Create a new bot in the Cisco Developer portal
+
+Follow the instructions to create a new bot in the [Cisco Spark Developer Portal](https://developer.ciscospark.com/add-bot.html). 
+
+![Add a bot](IMG/cisco_add.png)
+
+Take note of the bot username, you'll need it later.
+
+**Note about your icon**: Cisco requires you host an avatar for your bot before you can create it in their portal. This bot needs to be a 512x512px image icon hosted anywhere on the web. This can be changed later.
+
+You can copy and paste this URL for a Botkit icon you can use right away: `https://raw.githubusercontent.com/howdyai/botkit-starter-ciscospark/master/public/default_icon.png`
+
+### 3. Copy your access token
+
+Cisco will provide you an `access token` that is specific to your bot. Write this down, you won't be able to see this later (but you will be able revoke it and create a new one).
+
+### 4. Run your bot with variables set
+
+ [Follow these instructions](../readme-ciscospark.md#getting-started) to run your bot locally, or by using a third-party service such as [Glitch](https://glitch.com) or [Heroku](https://heroku.com).
+ 
+ You will need the following environment variables when running your bot:
+ 
+ * `access_token` = Your token from Cisco Spark (**required**)
+ * `secret` = User-defined string to validate payloads  (**required**)
+ * `public_address`=  URL of your bot server (**required**)
+ * `studio_token`= [Botkit Studio](https://studio.botkit.ai)  API token (optional)
+
+You should now be able to search your Cisco Spark team for the bot username you defined, and add it to your team!
+
+### Additional resources
+
+Read more about making bots for this platform in the [Cisco Developer Portal](https://developer.ciscospark.com/bots.html).

docs/provisioning/IMG/Slack-eventsenable.png

@@ -0,0 +1,55 @@
+# Configure Botkit and Facebook Messenger
+
+Facebook is a constantly evolving platform, nominally you can find everything you [need to create a bot](https://developers.facebook.com/docs/messenger-platform/guides/quick-start) on their platform page, but that information is subject to change. 
+
+The easiest path to creating a new bot for Facebook Messenger is through Botkit Studio. [Sign up for an account here](https://studio.botkit.ai/signup/). This method will provide a guided path to hosting, along with other useful tools for creating and managing your bot.
+
+For advanced users looking to run their own code, you will need to [install Botkit](https://github.com/howdyai/botkit-starter-facebook) and run it before your bot can be configured with Messenger.
+
+### 1. [Install Botkit](https://github.com/howdyai/botkit/blob/master/readme.md#start-with-botkit-studio)
+
+Once installed, you will need to do steps 2-4, and steps 5 in parallel. It helps to have your development enviroment and the Facebook for Developers page open at the same time. 
+
+### 2. Create a Facebook App for Web
+
+Visit [Facebook for Developers page](https://developers.facebook.com/tools-and-support/) and create a new app.
+
+![Create your APP ID](IMG/fb_new.png)
+
+* Select a Messenger application
+
+![Create your app](IMG/fb_mess.png)
+
+### 3. Get a Page Access Token for your app
+Scroll down to `Token Generation`
+
+![page access token](IMG/fb_tokengen.png)
+
+If you have not yet created your page yet, you can go ahead and do this now, or associate this new bot with an existing page.
+
+Copy this `Page Access Token`, you'll need it when running your bot.
+
+### 4. Setup webhooks 
+Click  `Setup Webhooks` to link this application to your Botkit instance.
+
+![page access token](IMG/fb_webhooks.png)
+
+The callback url will be `https://YOURURL/facebook/receive`. This URL must be publically available, and SSL-secured. More information on this can be found in the next step.
+
+You will also need to define a `Verify Token` for your page subscription. This is a user-defined string that you will keep secret and pass in with your environment variables.
+
+### 5. Run your application
+
+Run your application with your environment variables set:
+
+* `page_token` - Your Page Access Token (**required**)
+* `verify_token` - Your Verify Token (**required**)
+* `studio_token` - Your [Botkit Studio](https://studio.botkit.ai/signup) Token (optional)
+
+If your application has been configured correctly, you will be able to talk to your bot through the page you specified in Step 3. Congratulations!
+
+### Additional resources
+*  [Botkit Facebook readme](https://github.com/howdyai/botkit/blob/master/docs/readme-facebook.md)
+*  [Botkit Facebook Starter Kit](https://github.com/howdyai/botkit-starter-facebook) 
+*  [Messenger Platform Documentation](https://developers.facebook.com/products/messenger/)
+*  [Sign up for Botkit Studio](https://studio.botkit.ai/)

docs/provisioning/IMG/botkit_icon.png

@@ -0,0 +1,32 @@
+## Provisioning Botkit
+As Botkit adds more platforms, it becomes increasingly difficult to keep track of all the methods for provisioning your bot on the various platforms we support. 
+
+To help Botkit developers, we are pulling out detailed provisioning documents for each platform and keeping them in this directory. Our hope is that this will make our docs more flexible to platform changes, and clearly show the fastest way to stand up your bot!
+
+## Platforms
+
+#### [Slack (Events API)](slack-events-api.md)
+
+#### [Facebook Messenger](facebook_messenger.md)
+
+#### [Cisco Spark](cisco-spark.md)
+
+## Documentation
+
+* [Get Started](../../readme.md)
+* [Botkit Studio API](../readme-studio.md)
+* [Function index](../readme.md#developing-with-botkit)
+* [Extending Botkit with Plugins and Middleware](../middleware.md)
+  * [List of current plugins](../readme-middlewares.md)
+* [Storing Information](../storage.md)
+* [Logging](../logging.md)
+* Platforms
+  * [Slack](../readme-slack.md)
+  * [Cisco Spark](../readme-ciscospark.md)
+  * [Facebook Messenger](../readme-facebook.md)
+  * [Twilio IPM](https://../readme-twilioipm.md)
+  * [Microsoft Bot Framework](../readme-botframework.md)
+* Contributing to Botkit
+  * [Contributing to Botkit Core](../../CONTRIBUTING.md)
+  * [Building Middleware/plugins](../howto/build_middleware.md)
+  * [Building platform connectors](../howto/build_connector.md)

docs/provisioning/IMG/cisco_add.png

@@ -0,0 +1,83 @@
+# Configure Botkit and the Slack Events API
+
+Building a bot with Botkit and the Slack Events API gives you access to all of the best tools and options available to create a feature-rich bot for Slack.
+
+In order to get everything set up, you will need to configure a new Slack App inside the [Slack Developer Portal](http://api.slack.com/apps), and at the same time, configure a [Botkit-powered bot](http://botkit.ai). It only takes a few moments, but there are a bunch of steps, so follow these instructions carefully. 
+
+This feature is still in very active development at Slack, and these steps are subject to change.
+
+## 1. Create a new Slack App
+
+Go to [http://api.slack.com/apps](http://api.slack.com/apps) and create a new application record.
+
+![Create your app](IMG/slack-new.png)	
+
+You will receive a `clientId` and a `clientSecret`. You need these values - copy them into a temporary text file for use in the following steps.
+
+![Create your app](IMG/slack_client_secret.png)	
+
+## 2. Turn on your Botkit app
+
+Botkit Studio provides the easiest path to creating a new bot for Slack. This method will provide a guided path to hosting, along with other useful tools for creating and managing your bot. If you're already using [Botkit Studio](https://studio.botkit.ai/), this is happening in the background! 
+
+For advanced users looking to run their own code, you will need to [install Botkit](https://github.com/howdyai/botkit-starter-slack) and run it before your bot can be configured with Slack.
+
+Once you've collected your `clientId` and `clientSecret` tokens from Slack, you can start your Botkit app. You will need to have a bot service online and reachable over the web to complete the following steps and finish setting up your bot.
+
+## 3. Configure OAuth
+
+Botkit and Slack use the OAuth authentication system to grant bots access to connect to, read from, and send messages to Slack teams.
+
+![Setup Oauth](IMG/slack_oauth.png)
+
+Click on the "OAuth & Permissions" tab in your Slack's app setting, and under Redirect URLs, add: `https://my-bot-url/oauth`, and save your progress.
+
+## 4. Add a Bot User
+
+Click on the "Bot Users" tab and specify a name for your bot. This is the name that will be used by default when your application creates a new bot on a user's team. 
+
+![Setup Oauth](IMG/slack-botuser.png)
+
+In addition to a name, enable the option for "Always Show My Bot Online." This will ensure your Bot appears online to your team.
+
+## 5. Set up Interactive Messages
+
+"Interactive messages" is Slack's fancy way of saying "buttons." In order to enable buttons, under Request URL, add `https://YOURURL/slack/receive`, then click save.
+
+![Setup Interactive images](IMG/slack-im.png)
+
+## 6. Set up Event Subscriptions
+
+To start receiving messages, you will need to enable Event Subscriptions. Finally, scroll to the top of the page and switch "Enable Events" to "on". 
+
+Next you will need to add your Request URL, like this: `https://YOURURL/slack/receive`. When you finish typing, Slack will verify that this endpoint is properly configured. You must be running your Botkit application at the URL specified for this to work.
+
+![Verify your endpoints](IMG/Slack-eventsenable.png)
+
+Once verified, click "Add Bot User Event", and using the dropdown that appears, select all of the `message.*` events: 
+
+* `message.channels`
+* `message.groups`
+* `message.ims`
+*  `message.mpim`
+
+This configuration tells Slack to send your bot all messages that are sent in any channel or group in which your bot is present. Add other events as needed. 
+
+![Add some subscriptions](IMG/slack_botevents.png)
+
+Your bot is now ready to receive messages!
+
+*Problems?* : If you do not see `Bot User` here, it is likely that you forgot to add a Bot User back in Step 4. Go and fix that now, and come back to Step 6 to continue.
+
+*Note*: If you intend on submitting to the App Directory, be sure to have a good reason to request more widely ranging events as your app can be rejected for excessively wide permissions.
+
+## 7. Add your bot to your Slack team
+
+Now that your bot is configured, and your appliacation is up and running, you can login and add your bot. Visit `https://MYURL/`, and you will be automatically directed to Slack's login page. Login and choose a team. You'll get one more confirmation before being redirected back to your app.
+
+Meanwhile, your bot should appear inside your Slack team. You should receive a friendly welcome message to indicates your bot is now online and working! 
+
+## Additional resources 
+* [Botkit Slack readme](../readme-slack.md) 
+* [Slack's official documention for Events API](https://api.slack.com/events-api)
+* [Sign up for Botkit Studio](https://studio.botkit.ai/signup) 

docs/provisioning/IMG/fb_app_perm.png

@@ -34,7 +34,7 @@ Table of Contents
 4) Run the example bot using the App ID & Password you were assigned. If you are _not_ running your bot at a public, SSL-enabled internet address, use the --lt option and update your bots endpoint in the developer portal to use the URL assigned to your bot.
 
 ```
-app_id=<MY_APP_ID> app_password=<MY_APP_PASSWORD> node botframework_bot.js [--lt [--ltsubdomain CUSTOM_SUBDOMAIN]]
+app_id=<MY_APP_ID> app_password=<MY_APP_PASSWORD> node examples/botframework_bot.js [--lt [--ltsubdomain CUSTOM_SUBDOMAIN]]
 ```    
 
 5) Your bot should be online! Within Skype, find the bot in your contacts list, and send it a message.

docs/provisioning/IMG/fb_mess.png

@@ -35,7 +35,7 @@ ngrok http 3000
 4) Run your bot application using the access token you received, the base url of your bot application, and a secret which is used to validate the origin of incoming webhooks:
 
 ```
-access_token=<MY ACCESS TOKEN> public_address=<https://my_bot_url> secret=<my_secret_phrase> node spark_bot.js
+access_token=<MY ACCESS TOKEN> public_address=<https://my_bot_url> secret=<my_secret_phrase> node examples/spark_bot.js
 ```
 
 5) Your bot should now come online and respond to requests! Find it in Cisco Spark by searching for it's name.