Update README (#14)

* Add descriptive README

* Add README for echobot

* Add markdown formatting

* Update README.md

* Update Bot registration URL

* Add steps to integrate with MS BotFramework

* Add build badge in README

* punctuate READMEs

Co-authored-by: Sahil Lakhwani <[email protected]>

README.md

@@ -1,2 +1,47 @@
-# msbotbuilder-go
-Microsoft Bot Framework SDK for Go Lang
+# Bot Framework SDK for GoLang
+
+[![Build Status](https://travis-ci.org/infracloudio/msbotbuilder-go.svg?branch=develop)](https://travis-ci.org/infracloudio/msbotbuilder-go)
+
+This repository is the Go version of the Microsoft Bot Framework SDK. It facilitates developers to build bot applications using the Go language.
+
+## Installing
+
+```sh
+$ go get -u github.com/infracloudio/msbotbuilder-go/...
+```
+
+## Get started with example
+
+The [samples](samples/echobot) contains a sample bot created using this library which echoes any message received.
+
+Before running this, two environment variables are needed viz. the Bot Framework application ID and the password. This can be received after [registration of a new bot](https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/create-a-bot-for-teams#register-your-web-service-with-the-bot-framework).
+
+```sh
+$ export APP_ID=MICROSOFT_APP_ID
+$ export APP_PASSWORD=MICROSOFT_APP_PASSWORD
+```
+
+Then, from the root of this repository,
+
+```sh
+$ cd samples/echobot
+$ go run main.go
+```
+
+This starts a webserver on port `3978` by default.
+
+This is the endpoint which the connector service for the registered bot should point to. For a descriptive understanding of the example refer the [sample](samples/).
+
+## Contributing
+
+We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+
+## Credits
+
+This project is highly inspired from the official Microsoft Bot Framework SDK - https://github.com/microsoft/botbuilder-python.
+
+We have borrowed most of the design principles from the official Python SDKs.

samples/echobot/README.md

@@ -0,0 +1,76 @@
+# Bot Framework echo bot sample.
+
+This Microsoft Teams bot uses the [msbotbuilder-go](https://github.com/infracloudio/msbotbuilder-go) library. It shows how to create a simple bot that accepts input from the user and echoes it back.
+
+## Run the example
+
+#### Step 1: Register MS BOT
+
+Follow the official [documentation](https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/create-a-bot-for-teams#register-your-web-service-with-the-bot-framework) to create and register your BOT.
+
+Copy `APP_ID` and `APP_PASSWORD` generated for your BOT.
+
+Do not set any messaging endpoint for now.
+
+#### Step 2: Run echo local server
+
+Set two variables for the session as `APP_ID` and `APP_PASSWORD` to the values of your BotFramework `APP_ID` and `APP_PASSWORD`. Then run the `main.go` file.
+
+```bash
+export APP_PASSWORD=MICROSOFT_APP_PASSWORD
+export APP_ID=MICROSOFT_APP_ID
+
+go run main.go
+```
+
+This will start a server which will listen on port `3978`
+
+#### Step 3: Expose local server with ngrok
+
+Now, in separate terminal, run [ngrok](https://ngrok.com/download) command to expose your local server to outside world.
+
+```sh
+$ ngrok http 3978
+```
+
+Copy `https` endpoint, go to [Bot Framework](https://dev.botframework.com/bots) dashboard and set messaging endpoint under Settings.
+
+#### Step 4: Test the BOT
+
+You can either test BOT on BotFramework portal or you can create app manifest and install the App on Teams as mentioned [here](https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/create-a-bot-for-teams#create-your-app-manifest-and-package).
+
+
+## Understanding the example
+
+The program starts by creating a handler struct of type `activity.HandlerFuncs`.
+
+This struct contains definition for the `OnMessageFunc` field which is a treated as a callback by the library on the respective event.
+
+```bash
+var  customHandler = activity.HandlerFuncs{
+	OnMessageFunc: func(turn *activity.TurnContext) (schema.Activity, error) {
+		activity := turn.Activity
+		activity.Text = "Echo: " + activity.Text
+		return turn.TextMessage(activity), nil
+	},
+}
+```
+
+
+The `init` function picks up the `APP_ID` and `APP_PASSWORD` from the environment session and creates an `adapter` using this.
+
+
+A webserver is started with a handler which passes the received payload to `adapter.ParseRequest`. This methods authenticates the payload, parses the request and returns an Activity value.
+
+```
+activity, err := adapter.ParseRequest(ctx, req)
+```
+
+
+The Activity is then passed to `adapter.ProcessActivity` with the handler created to process the activity as per the handler functions and send the response to the connector service.
+
+```
+err = adapter.ProcessActivity(ctx, activity, customHandler)
+```
+
+In case of no error, this web server responds with a 200 status.