wordhop 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: af96cecf1ffde299d7e6fe0707f081b097007105
-  data.tar.gz: 1ec319673b789faa7faa5d97577d616df3fe1553
+  metadata.gz: 9fd062193fa74d0eac121d686cbc89172c85aada
+  data.tar.gz: c25c3973a3fc9a36a518025c0aacd1cd3334cbe1
 SHA512:
-  metadata.gz: 288aac394bba77997c9c7a505de576e92d7daa9501afeca3052f65c385ac26ee2c60162dbe1068a7d3cd56c4e3e1a85088cb5f49e3764203260ee5a3aaf8f0c0
-  data.tar.gz: 0a69a009d075748694aaad6d578d653c55b3753d069425f29a20e50e7f038752d4883104544479259fff59c8f2e005376cbe155ebf613b24b8202c97a9a4097c
+  metadata.gz: 052054010ab217213318d9508c40e5a0a07da4750a0d349e66e409df34c3088474d3689cfc5d0379e8238741cecac5610e24e1ab4923cee93f2d194865ff166e
+  data.tar.gz: 22bc9c48b7931d7ae0628764865c167089af541fe7fa2b24bc7dc5ae13a0d3d2635611b408f257eaf0e89a537c020ae0da5d842656fbd3551b08a071d48bbd28

data/README.md

@@ -1,7 +1,7 @@
 # [Wordhop](https://www.wordhop.io) - Monitor and Optimize Your Conversational Experience
 ## For Chatbots Built in Ruby
 
-With Wordhop you can sync up your Ruby-based Chatbot to Slack, so you can retain your users without ever leaving Slack.  Wordhop monitors your Chatbot for friction in your conversational experience and alerts you on Slack in real-time. Simply add Wordhop to Slack and then drop in a couple of lines of code into your Chatbot.  Wordhop integrates in minutes, not days, and begins working immediately.  From Slack, you can pause and take over your bot, then hand the conversation back to your bot.  Actionable analytics also show you and your Slack team where you can optimize your conversational experience and measure results. 
+Wordhop monitors your Chatbot for friction in your conversational experience and alerts you on Slack in real-time. Simply add Wordhop to Slack and then drop in a couple of lines of code into your Chatbot.  Wordhop integrates in minutes, and begins working immediately.  From Slack, you can see full transcripts of all your bot's conversations, pause and take over your bot, then hand the conversation back to your bot.  Actionable analytics also show you and your Slack team where you can optimize your conversational experience and measure results. 
 
 ### What you can do with Wordhop:
 * [See Key Features](https://developer.wordhop.io)
@@ -10,7 +10,12 @@ With Wordhop you can sync up your Ruby-based Chatbot to Slack, so you can retain
 ### What you need to get started:
 * [A Slack Account](http://www.slack.com)
 * [Wordhop for Slack](https://slack.com/oauth/authorize?scope=users:read,users:read.email,commands,chat:write:bot,channels:read,channels:write,bot&client_id=23850726983.39760486257)
-* [A Chatbot built in Ruby](https://github.com/hyperoslo/facebook-messenger)
+* [A Chatbot built in Ruby](./examples/)
+
+##### Operational Dependencies:
+1.  You'll need an API key from Wordhop and for each Chatbot a Bot Token.  You can get both of those (free) when you add Wordhop to Slack and through a conversation with Wordhop. 
+2.  If you're building a Messenger Chatbot, you'll need to setup a Facebook App, Facebook Page, get the Page Access Token from Facebook and link the Facebook App to the Facebook Page for Wordhop to work.
+
 
 ### Installation
 
@@ -21,6 +26,15 @@ $ gem install wordhop
 
 ### Usage
 
+Set your environmental variables for `WORDHOP_API_KEY`, `WORDHOP_CLIENT_KEY`, `ACCESS_TOKEN`.
+
+```bash
+$ export WORDHOP_API_KEY=xxxxxxxxxxxxxxxxxxxx
+$ export WORDHOP_CLIENT_KEY=xxxxxxxxxxxxxxxxxxxx
+$ export ACCESS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+Add the Wordhop class to your code and set the required parameter values.
 ```ruby
 require 'wordhop'
 
@@ -33,14 +47,67 @@ Wordhop.platform = "messenger"
 # Page Access Token (only required for Messenger bots)
 Wordhop.token = ENV['ACCESS_TOKEN']
 ```
+##### Incoming Message Schema:
+Throughout this documentation, you will see references to `incomingMessage`. Depending on whether you have a Messenger or Slack bot, the schema will be different. The value of `incomingMessage` should be equal to the message you receive directly from either the Messenger webhook response, or from the Slack RTM event response.
+
+```python
+# Example of a Slack Incoming Message
+{
+    "type": "message",
+    "channel": "D024BE91L",
+    "user": "U2147483697",
+    "text": "Hello world",
+    "ts": "1355517523.000005"
+}
+
+# Example of a Messenger Incoming Message
+{
+  "sender":{
+    "id":"USER_ID"
+  },
+  "recipient":{
+    "id":"PAGE_ID"
+  },
+  "timestamp":1458692752478,
+  "message":{
+    "mid":"mid.1457764197618:41d102a3e1ae206a38",
+    "seq":73,
+    "text":"hello, world!",
+    "quick_reply": {
+      "payload": "DEVELOPER_DEFINED_PAYLOAD"
+    }
+  }
+}  
+```
+
+##### Outgoing Message Schema:
+Throughout this documentation, you will see references to `outgoingMessage`. Depending on whether you have a Messenger or Slack bot, the schema, as defined by each platform, will be different. Every time you track an outgoing message, the schema requirements match the respective platform.
+
+```python
+# Example of Slack Outgoing Message
+{
+    "channel": "C024BE91L",
+    "text": "Hello world"
+}
+
+# Exmaple of Messenger Outgoing Message
+{
+  "recipient":{
+    "id":"USER_ID"
+  },
+  "message":{
+    "text":"hello, world!"
+  }
+}
+```
 
 ##### Tracking received messages:
 
-When Messenger calls your receiving webhook, you'll need to log the data with Wordhop. 
+When your bot receives an incoming message, you'll need to log the data with Wordhop by calling to `wordhop.hopIn`. 
 __Note__: Wordhop can pause your bot so that it doesn't auto response while a human has taken over. The server response from your `hopIn` request will pass the `paused` state. Use that to stop your bot from responding to an incoming message. Here is an example:
 
 ```ruby
-hopInResponse = Wordhop.hopIn(message.messaging)
+hopInResponse = Wordhop.hopIn(incomingMessage)
 if hopInResponse['paused'] != true
 # proceed to process incoming message
  ...
@@ -48,55 +115,53 @@ if hopInResponse['paused'] != true
 
 ##### Tracking sent messages:
 
-Each time your bot sends a message, make sure to log that with Wordhop in the request's callback. Here is an example:
+Each time your bot sends a message, make sure to log that with Wordhop by calling to `wordhop.hopOut`. Here is an example of a function that we're calling `sendIt` that tracks an outgoing message and at the same time, has the bot say the message:
 ```ruby
-def sendIt(message, data)
-    payload = {
-        recipient: message.sender,
-        message: data
-    }
-    message.reply(data)
-    Wordhop.hopOut(payload)
-end
+def sendIt(channel, text)
+    # schema matches Messenger
+    outgoingMessage = {recipient: {id: channel},message: {text: text}}
+    Wordhop.hopOut(outgoingMessage)
+    bot.send_text_message(channel, text) # <= example of bot sending reply
+    ...
 ```
 
-##### Human Take Over:
-
-To enable the ability to have a human take over your bot, add the following code:
-
-```ruby
-# Handle forwarding the messages sent by a human through your bot
-Wordhop.on :'chat response' do |data|
-    Bot.deliver(data, access_token: ENV['ACCESS_TOKEN'])  # <= example of bot sending message
-end
-```
 ##### Log Unknown Intents:
 
-Find the spot in your code your bot processes incoming messages it does not understand. You may have some outgoing fallback message there (i.e. "Oops I didn't get that!"). Within that block of code, call to `wordhop.logUnkownIntent` to capture these conversational ‘dead-ends’. Here's an example:
+Find the spot in your code your bot processes incoming messages it does not understand. Within that block of code, call to `wordhop.logUnkownIntent` to capture these conversational ‘dead-ends’. Here's an example:
 
 ```ruby
 # let the user know that the bot does not understand
-sendIt(message, text: 'Huh?')
+sendIt(recipient_id, 'Huh?')
 # capture conversational dead-ends.
-Wordhop.logUnknownIntent(message.messaging)
+Wordhop.logUnknownIntent(incomingMessage) 
 ```
 ##### Dial 0 to Speak With a Live Human Being:
 
-Wordhop can trigger alerts to suggest when a human should take over for your Chatbot. To enable this, create an intent such as when a customer explicitly requests live assistance, and then include the following line of code where your bot listens for this intent:
+Wordhop can trigger alerts to suggest when a human should take over for your Chatbot. To enable this, create an intent such as when a customer explicitly requests live assistance, and then include the following lines of code where your bot listens for this intent:
 
 ```ruby
 # match an intent to talk to a real human
 if text == 'help'
     # let the user know that they are being routed to a human
-    sendIt(message, text: 'Hang tight. Let me see what I can do.')
+    sendIt(recipient_id, 'Hang tight. Let me see what I can do.')
     # send a Wordhop alert to your slack channel
     # that the user could use assistance
-    Wordhop.assistanceRequested(message.messaging)
-    ...
+    Wordhop.assistanceRequested(incomingMessage);
+```
+
+##### Human Take Over:
+
+To enable the ability to have a human take over your bot, add the following code:
+
+```ruby
+# Handle forwarding the messages sent by a human through your bot
+Wordhop.on :'chat response' do |data|
+    Bot.deliver(data, access_token: ENV['ACCESS_TOKEN'])  # <= example of bot sending message
+end
 ```
 
 Go back to Slack and wait for alerts. That's it! 
-[Be sure to check out our example.](examples/messenger/README.md)
+[Be sure to check out our examples.](./examples/)
 
 
 ### Looking for something we don't yet support?  

data/lib/wordhop.rb

@@ -39,7 +39,7 @@ module Wordhop
         end
         
         def token
-            @token ||= ENV['ACCESS_TOKEN']
+            @token ||= ENV['ACCESS_TOKEN'] ||= ''
         end
         
         def platform

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wordhop
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Michael Nathanson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-08 00:00:00.000000000 Z
+date: 2016-12-12 00:00:00.000000000 Z
 dependencies: []
 description: "Chatbots allow you scale your customer communications through messaging,
   \n  \tautomating tasks and enabling transactions, but they can't empathize like