webhook example

ashubham · Mar 22, 2017 · 25c1f06 · 25c1f06
1 parent ada5093
commit 25c1f06
Show file tree

Hide file tree

Showing 2 changed files with 90 additions and 71 deletions.
diff --git a/README.md b/README.md
@@ -39,13 +39,13 @@ let context = require('bot-context');
 
 function onMessageRecieved(message, userId) {
   let ctx = botContext.getOrCreate(userId);
-  ctx.match(message, function(err, match, contextCb) {
-    if(!err) contextCb(userId, match);
-  });
-
   if(!ctx.isSet()) {
       init(userId); // initialize the actions.
   }
+
+  ctx.match(message, function(err, match, contextCb) {
+    if(!err) contextCb(userId, match);
+  });
 }
 ```
 
@@ -98,119 +98,90 @@ function end(userId, pizzaType, address) {
 } 
 ```
 
-Now, if a user after putting his address changes his mind to another pizza type, by just typing the type of the pizza.
+Now, if a user after putting his address changes his mind to another pizza type, 
+by just typing the type of the pizza.
+
+## Webhooks
+
+Many people use WYSIWYG bot creators. Almost all of them allow integration with external
+tools via http `webhooks`.
+
+`bot-context` can easily be used with such bot tools. Please see the [examples](https://github.com/ashubham/bot-context/tree/master/examples).
+On how could you setup `bot-context` as a webservice.
 
 ## API
 
+`var contextMap = require('bot-context');`
+
+returns an instance of the ContextMap, the following methods are available on it.
+
 -   [ContextMap](#contextmap)
-    -   [constructor](#constructor)
-    -   [getOrCreate](#getorcreate)
+    -   [getOrCreate()](#getorcreate)
 -   [Context](#context)
-    -   [constructor](#constructor-1)
     -   [set](#set)
-    -   [ContextCb](#contextcb)
-    -   [matcherFn](#matcherfn)
     -   [isSet](#isset)
     -   [match](#match)
-    -   [contextMatchedCb](#contextmatchedcb)
 
-## ContextMap
-
-**Extends Map**
+## ContextMap **extends Map**
 
 A map to hold contexts for all users/keys
 
-### constructor
-
-Creates an instance of ContextMap.
-
-**Parameters**
-
--   `args` **any** 
-
-### getOrCreate
+### getOrCreate(uKey: string)
 
 Get Or Creates a context given the key.
 
 **Parameters**
 
--   `uKey` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
+-   `uKey` unique key to identify a user. **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
 
 Returns **[Context](#context)** 
 
 ## Context
 
-### constructor
-
-Creates an instance of Context.
-
-**Parameters**
-
--   `key` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
+A context uniqiue for each user. The following methods are available on the `context`.
 
-### set
+### <a name="set"></a>set(matchRegex|matcherFn, contextCallback)
 
 Set the current context.
 
 **Parameters**
 
--   `pattern` **([RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) | matcherFn)** 
--   `callback` **ContextCb** 
-
-### ContextCb
-
-Context callback set in the context stack.
-
-Type: [Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)
-
-**Parameters**
-
--   `pattern`  
--   `callback`  
+-   `matchRegex|matchFn` **([RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) | Function)** Used to match the input
+-   `contextCallback` Callback which is stored in the stack, it can hold references to closure vars.
 
-### matcherFn
+  #### matcherFn(inputText, callback)
 
-Matcher method called when matching contexts.
+  Matcher method called when matching contexts. It is called with the following params.
 
-Type: [Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)
-
-**Parameters**
+  **Parameters**
 
 -   `text` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** input text
--   `cb` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Callback resolving to truthy/falsy value.
--   `pattern`  
--   `callback`  
+-   `callback(boolean)` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Callback resolving to truthy/falsy value.
 
-### isSet
+  #### contextCallback
 
-Returns whethere there is any context set.
+  Context callback set in the context stack.
 
-Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** 
+###<a name="isset"></a> isSet(): boolean
 
-### match
+  Returns, is there any context set.
 
-Match an input text to the collection of currently set contexts.
-
-**Parameters**
+### <a name="match"></a>match(inputText: string, contextMatchedCallback)
 
--   `input` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** text
--   `callback` **contextMatchedCb** The callback to be called if matched.
--   `text`  
--   `cb`  
+  Match an input text to the collection of currently set contexts.
 
-Returns **any** 
+  **Parameters**
 
-### contextMatchedCb
+-   `inputText` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** text
+-   `contextMatchedCallback` The callback to be called if matched.
 
-Callback when a context is matched.
+#### contextMatchedCallback
 
-Type: [Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)
+Callback called when a context is matched, with the following values.
 
 **Parameters**
 
 -   `err` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) | null)** Error if any
 -   `match` **any** the match returned from the matchFn or regex
--   `callback` **ContextCb** the callback set to the context stack.
--   `text`  
--   `cb`  
+-   `contextCallback` **ContextCb** the callback which was previously set to the context stack.
 
diff --git a/examples/webhooks.js b/examples/webhooks.js
@@ -0,0 +1,48 @@
+// An example to show use of webhooks.
+
+var contextMap = require('bot-context');
+var express = require('express');
+var bodyParser = require('body-parser');
+var request = require('request');
+
+var app = express(); // Set up an express webservice. You can use restify, Koa etc.
+
+app.use(bodyParser.json());
+
+// Incoming webhook.
+app.post('/recieve', (req, res) => {
+    let ctx = contextMap.getOrCreate(req.body.userId); // Assuming userId is in the json payload.
+    if (!ctx.isSet()) {
+        init(userId); // initialize the actions.
+    }
+
+    ctx.match(message, function (err, match, contextCb) {
+        if (!err) contextCb(userId, match);
+    });
+});
+
+function init(userId) {
+    let ctx = contextMap.getOrCreate(userId);
+    ctx.set(
+        /.*/,  // The base matcher to match anything.
+        (match) => doSomethingAndRespond(userId));
+}
+
+function doSomethingAndRespond(userId) {
+    ctx.set(
+        // Set some more context here.
+    );
+    outgoingWebhook(userID, "bla bla");
+}
+
+function outgoingWebhook(userId, message) {
+    request.post({
+        url: 'https://<webhook-endpoint-here>',
+        form: {
+            userId: userId,
+            message: message
+        }
+    }, (err, resp, body) => {
+        // Handle webhook err/response.
+    });
+}