🙉 Version 3.0 in progress

Author: karishay

README.md

@@ -21,7 +21,7 @@ First you'll want to clone this project locally. This project is structured with
 
 At each step, feel free to ask questions in the _#help_ channel, or ask your neighbor if they can help! :raised_hands:
 
-To get started, checkout the first branch
+To get started, check out the first branch
 
 ```bash
 git checkout chapter-1
@@ -30,7 +30,7 @@ git checkout chapter-1
 If you'd like to follow along without any of the code, all of the documentation for each chapter is located in the `docs` folder in the `master` branch.
 
 * **[Chapter 1: Setting Things Up](docs/Chapter-1.md)** :point_left:  
-* [Chapter 2: App.py and OAuth](docs/Chapter-2.md)  
+* [Chapter 2: OMG OAuth](docs/Chapter-2.md)  
 * [Chapter 3: Handle Hello with Class](docs/Chapter-3.md)  
 * [Chapter 4: Message Buttons Magic](docs/Chapter-4.md)
 * [Chapter 5: ABCs of NLP](docs/Chapter-5.md)
@@ -41,15 +41,16 @@ If you'd like to follow along without any of the code, all of the documentation
 
 ##### Slack Documentation
 
-* [Getting started with Slack apps](https://api.slack.com/slack-apps)  
-* [Slack Events API documentation](https://api.slack.com/events)  
-* [Slack Web API documentation](https://api.slack.com/web)
+* [Getting started with Slack apps](https://api.slack.com/slack-apps?utm_source=events&utm_campaign=build-bot-workshop&utm_medium=workshop)  
+* [Slack Events API documentation](https://api.slack.com/events?utm_source=events&utm_campaign=build-bot-workshop&utm_medium=workshop)  
+* [Slack Web API documentation](https://api.slack.com/web?utm_source=events&utm_campaign=build-bot-workshop&utm_medium=workshop)
 
 ##### Documentation for Tools
 
 * [virtualenv](https://virtualenv.pypa.io/en/latest/userguide/)
 * [flask](http://flask.pocoo.org/)
 * [python-slackclient](http://python-slackclient.readthedocs.io/en/latest/)
+* [Slack Events Adapter](https://github.com/slackapi/python-slack-events-api)
 * [ngrok](https://ngrok.com/docs)
 * [postman](https://www.getpostman.com/docs/)
 
@@ -59,9 +60,9 @@ Wondering what to do if you can't get this dang tutorial to work for you?
 The Slack Developer community is an awesome place to get help when you're confused
 or stuck. We have an excellent 'search first' culture and Slack is committed to
 improving our tutorials and documentation based on your feedback. If you've
-checked the [Slack API documentation](https://api.slack.com/), reached the end
+checked the [Slack API documentation](https://api.slack.com/?utm_source=events&utm_campaign=build-bot-workshop&utm_medium=workshop), reached the end
 of your google patience and found [StackOverflow](http://stackoverflow.com/questions/tagged/slack-api)
-to be unhelpful, try asking for help in the [Slack Developer Hangout](http://dev4slack.xoxco.com/)
+to be unhelpful, try asking for help in the [Bot Developer Hangout](http://dev4slack.xoxco.com/)
 Slack team.
 
 ### Feedback
@@ -70,3 +71,5 @@ I'd love to improve this project, so if you've got some ideas :bulb:, feedback
 :raising_hand: or praise :love_letter: please file an issue, submit a PR or
 reach out to me through [Github](https://github.com/karishay) or on
 [Twitter](https://twitter.com/karishannon)!
+
+If you want to keep up with Slack platform updates chat with us on [Twitter](https://twitter.com/slackapi).

docs/Chapter-1.md

@@ -1,6 +1,6 @@
 # Chapter 1: Setting Things Up
 
-Before we get to the core of bot building, we need to get set up. First, we'll add everything you need for creating a local web server where our bot will live and an https ngrok tunnel so that our bot can connect to Slack. After we've set up our development environment, we'll set up a new Slack App and bot user and then we'll connect Slack to our local environment.
+Before we get to the core of bot building, we need to get set up. First, we'll add everything you need for creating a local web server where our bot will live and an https ngrok tunnel so that our bot can connect to Slack. After we've set up our development environment, we'll set up a new Slack App and bot user and then we'll connect Slack to our local environment. Once our environment is set up, we'll get our Flask application server running.
 
 ## Setting up Your Development Environment
 
@@ -23,11 +23,7 @@ tool to manage a virtual environment
 - **[Ngrok](https://ngrok.com/)**, an easy to use tunneling tool that supports HTTPS,
 which we'll use to connect our app to Slack over _teh interwebz._
 
-Once you've installed Python, pip, virtualenv and ngrok you can install all additional
-dependent libraries using pip and the `requirements.txt` file included in this
-project, including [Flask](http://flask.pocoo.org/), a web development micro
-framework for Python and [python-slackclient](http://python-slackclient.readthedocs.io/en/latest/), a
-Slack client for Python. :snake:
+After you’ve installed Python, pip, ngrok and virtualenv you’ll need to generate and activate a new virtualenv. Once your virtualenv is turned on you can install all the additional dependent libraries using pip and the `requirements.txt` file in this project, including [Flask](http://flask.pocoo.org/), a web development microframework for Python, [python-slackclient](http://python-slackclient.readthedocs.io/en/latest/), a Slack client for Python and the [Slack Events Adapter for Python](https://github.com/slackapi/python-slack-events-api). :snake:
 
 First, you'll want to create a virtual environment to keep the dependencies for this project isolated from any other project you may be working on. You'll need to open a terminal or command prompt to enter these and the following commands.
 
@@ -55,10 +51,10 @@ pip install -r requirements.txt
 
 Now that we've got our local environment set up we'll need to create a new Slack App. :tada:
 
-### Creating a New Slack App on [api.slack.com](https://api.slack.com/apps)
+### Creating a New Slack App on [api.slack.com](https://api.slack.com/apps?utm_source=events&utm_campaign=build-bot-workshop&utm_medium=workshop)
 
-In your browser, on [api.slack.com/apps](https://api.slack.com/apps) you'll find
-a green button labeled [Create New App](https://api.slack.com/apps/new) on the
+In your browser, on [api.slack.com/apps](https://api.slack.com/apps?utm_source=events&utm_campaign=build-bot-workshop&utm_medium=workshop) you'll find
+a green button labeled [Create New App](https://api.slack.com/apps/new?utm_source=events&utm_campaign=build-bot-workshop&utm_medium=workshop) on the
 top right of the page.
 
 ![create_new_slack_app](https://cloud.githubusercontent.com/assets/4828352/20548492/b4270b52-b0d8-11e6-94cb-ea307342ebb9.png)
@@ -79,16 +75,18 @@ Once you've got your fancy new automaton, we have it subscribe to events in Slac
 
 ### Subscribe to Events
 
-By using Slack's [Events API](https://api.slack.com/events-api) we can ask Slack to send us a JSON payload of information when something particular happens inside of Slack. If we want our bot respond when a user says hello, we can have our bot subscribe to `message.channels` and when a user posts a message, Slack will send the information about the message event to the URL we specify. If the message matches our criteria we can choose to respond to it with an additional step. Unneeded events are discarded.
+By using Slack's [Events API](https://api.slack.com/events-api?utm_source=events&utm_campaign=build-bot-workshop&utm_medium=workshop) we can ask Slack to send us a JSON payload of information when something particular happens inside of Slack. If we want our bot respond when a user says hello to our bot in a DM, we can have our bot subscribe to `message.im` and when a user posts a message, Slack will send the information about the message event to the URL we specify. If the message matches our criteria we can choose to respond to it with an additional step. Unneeded events are discarded.
 
 On the left navigation bar of your app's settings page you'll find **Event Subscriptions**.
-To start off right, go ahead and subscribe your bot to `message.channels` events under the **Bot Events** section of the page.
+To start off right, go ahead and subscribe your bot to `message.im` events under the **Bot Events** section of the page.
+
+![add_bot_events](https://cloud.githubusercontent.com/assets/4828352/23191396/364af9fc-f852-11e6-9206-5aeb4ca2018a.png)
 
-![add_bot_events](https://cloud.githubusercontent.com/assets/4828352/20548810/8ea539b4-b0db-11e6-859d-e75f98a29ddc.png)
 
 After you've subscribed to all the events your app will need, make sure to **Save Changes**.
 
-![save_changes](https://cloud.githubusercontent.com/assets/4828352/20575405/fca754dc-b16d-11e6-880d-5eb8dd5d5196.png)
+![save_changes](https://cloud.githubusercontent.com/assets/4828352/23178485/716f367a-f81f-11e6-8967-a35893a2cd41.png)
+
 
 ### App Credentials
 
@@ -120,9 +118,28 @@ set VERIFICATION_TOKEN='xxxXXXxxXXxxX'
 
 Our app will grab these secrets from our environment.
 
+## Let's Make an [app.py](app.py)
+
+In this project directory, you'll find a file called [app.py](app.py). Slack will be delivering events to your application securely, so your application server will need to be able to receive incoming HTTPS traffic. In  [app.py](app.py) we'll use the [Slack Events Adapter](https://github.com/slackapi/python-slack-events-api) to create a Flask server to handle all incoming events from Slack. But first, you'll need a web page where people can install your bot onto their teams!
+
+When you open [app.py](app.py) you'll see that we've created an instance of _SlackEventAdapter_ called `events_adapter` and added a couple of routes to it's Flask server.
+
+To verify that our server is associated with our app, Slack will make a request to the `/slack` endpoint created by the Flask server in our [Slack Events Adapter](https://github.com/slackapi/python-slack-events-api) by sending a `challenge` parameter that it will expect us to return back. The events adapter will handle this verification for us.
+
+First, we'll need to add an `/install` route that renders an HTML template where users will eventually be able to install your app. The second route called `/thanks` will return an HTML page to let our users know that our app has been sucessfully installed on their Slack team.
+
+Let's fire up our app and test that our Flask server is working properly. With your virtual environment turned on and your secrets exported to the environment, go ahead and start your app:
+
+```bash
+python app.py
+```
+![start_appy](https://cloud.githubusercontent.com/assets/4828352/20549064/cad48f8c-b0dd-11e6-8a85-25bff2815d2e.png)
+
+Check our your shiny app is running locally in a browser by navigating to   [localhost:5000/install](http://localhost:5000/install). :boom:
+
 ## You Did It! :sparkles:
 
-You're all set up! Time to checkout the next chapter.
+You're all set up! Time to check out the next chapter and move on to OAuth.
 
 ```bash
 git checkout chapter-2