Merge pull request RasaHQ#5474 from RasaHQ/muelerma-hangouts-channel

Hangouts Channel integration

Author: degiz

changelog/5006.feature.rst

@@ -0,0 +1 @@
+Channel ``hangouts`` for Rasa integration with Google Hangouts Chat is now supported out-of-the-box.

docs/user-guide/connectors/hangouts.rst

@@ -0,0 +1,75 @@
+:desc: Build a Rasa Chat Bot on Google Hangouts Chat
+
+.. _google-hangouts-chat:
+
+Google Hangouts Chat
+====================
+
+.. edit-link::
+
+Hangouts Chat Setup
+-------------------
+
+This channel works similar to the standard Rasa REST channel. For each request from the channel, your bot will 
+send one response. The response will be displayed to the user either as text or a so-called card (for
+more information, see the Cards section).
+
+In order to connect your Rasa bot to Google Hangouts Chat, you first need to create a project in 
+Google Developer Console that includes the Hangouts API. There you can specify your bot's endpoint
+and also obtain your project id, which determines the scope for the OAuth2 authorization in case you 
+want to use OAuth2. The Hangouts Chat API sends a Bearer token with every request, but it is up to 
+the bot to actually verify the token, hence the channel also works without this.  
+For more information see the official Google resources https://developers.google.com/hangouts/chat.
+
+The possibility to implement asynchronous communication between Hangouts Chat and bot exists, but due
+to the usually synchronous nature of Rasa bots, this functionality is not included in this channel. 
+
+Running On Hangouts Chat
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to connect to Hangouts Chat using the run script, e.g. using:
+
+.. code-block:: bash
+
+  rasa run
+
+you don't need to supply a ``credentials.yml``.
+
+If you want to use OAuth2, simply put the project id obtained from the Google Developer Console into it.
+
+.. code-block:: yaml
+
+  hangouts:
+    project_id: "12345678901"
+
+The endpoint for receiving Hangouts Chat messages is
+``http://localhost:5005/webhooks/hangouts/webhook``, replacing
+the host and port with the appropriate values. Hangouts Chat only forwards
+messages to endpoints via ``https``, so take appropriate measures to add
+it to your setup.
+
+
+Cards and Interactive Cards
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two ways in which Hangouts Chat will display bot messages, either as text or card. For each recevied
+request, your bot will send all messages in one response. If one of those messages is a card (e.g. an image), 
+all other messages are converted to card format as well.
+
+Interactive cards trigger the ``CARD_CLICKED`` event for user interactions, e.g. when a button is clicked. When 
+creating an interactive card, e.g. via ``dispatcher.utter_button_message()`` in your ``actions.py``, you can 
+specify a payload for each button that is going to be returned with the ``CARD_CLICKED`` event and extracted 
+by the ``HangoutsInput`` channel (for example 
+``buttons=[{"text":"Yes!", "payload":"/affirm"}, {"text":"Nope.", "payload":"/deny"}])``.
+Updating cards is not yet supported.
+
+For more detailed information on cards, visit the
+`Hangouts docs <https://developers.google.com/hangouts/chat/reference>`_.
+
+
+Other Hangouts Chat Events
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Except for ``MESSAGE`` and ``CARD_CLICKED``, Hangouts Chat knows two other event types, ``ADDED_TO_SPACE`` and 
+``REMOVED_FROM_SPACE``, which are triggered when your bot is added or removed from a direct message or chat room
+space. The default intent names for these events can be modified in the ``HangoutsInput`` constructor method. 

docs/user-guide/messaging-and-voice-channels.rst

@@ -37,6 +37,7 @@ Learn how to make your assistant available on:
    connectors/cisco-webex-teams
    connectors/rocketchat
    connectors/mattermost
+   connectors/hangouts
    connectors/custom-connectors
 
 

poetry.lock

@@ -122,6 +122,7 @@ tensorflow-probability = "~0.7"
 setuptools = ">=41.0.0"
 kafka-python = "^1.4"
 ujson = "^1.35"
+oauth2client = "4.1.3"
 
 [tool.poetry.dev-dependencies]
 pytest-cov = "^2.8.1"

pyproject.toml

@@ -25,6 +25,7 @@
 from rasa.core.channels.telegram import TelegramInput  # nopep8
 from rasa.core.channels.twilio import TwilioInput  # nopep8
 from rasa.core.channels.webexteams import WebexTeamsInput  # nopep8
+from rasa.core.channels.hangouts import HangoutsInput  # nopep8
 
 input_channel_classes = [
     CmdlineInput,
@@ -40,6 +41,7 @@
     RestInput,
     SocketIOInput,
     WebexTeamsInput,
+    HangoutsInput,
 ]  # type: List[InputChannel]
 
 # Mapping from a input channel name to its class to allow name based lookup.