Sinks (2.4 and above)

Sinks allow the bot to receive external events in the form of JSON-based web requests.

In Bot Version 2.4 - 2.6, sinks are based on BaseBotRequestHandler(source).

In Bot Version 2.7 and above sinks are based on AsyncRequestHandler (source). Using this class is highly-recommended, as it is more responsive and flexible than BaseBotRequestHandler, which is still available in the code for backward-compatibility with older sinks.

The base class provides all the necessary functionality requires to create a simple sink. In fact, a new sink can easily be created just by sub-classing the sink with no changes.

This page contains general documentation for sink configuration and development.

There is also some sink-specific documentation - as of 2.7, all first-party sinks and plugins use AsyncRequestHandler as their base class to implement sinks:

• Google Script sink
• GitHub Webhook Sink
• GitLab Webhook Sink

Writing a New Sink

1. Create a new sub-folder in the hangupsbot/sinks/ folder
2. Create an __init__.py file inside the sub-folder with the following base pattern:

   from sinks import AsyncRequestHandler
   
   class AsyncMessagePoster(AsyncRequestHandler):
       # replace the classname with any valid name of your own choosing
       # add class method overrides here

For more information about overridable methods, please see the [2.4, 2.5, 2.6] BaseBotRequestHandler class reference or [2.7] AsyncRequestHandler class reference

Configuring Sinks

In config.json, you can add the new sink to the jsonrpc key:

"jsonrpc":
    {
      "certfile": "/root/server.pem",
      "module": "sinks.generic.AsyncMessagePoster",
      "name": "127.0.0.1",
      "port": 9002
    }

• The path to a valid .pem file for SSL/TLS must be provided in certfile. This is mandatory as the sink will refuse to start without SSL/TLS. A self-signed certificate will work.
• module should match your sink package and class name
• name should be the IP address of your server - 127.0.0.1 will suffice if you only intend to connect to the sink from the same server
• port should be unused

Testing & Debugging Sinks

As of 2.4 and above, all exceptions are logged into the bot log.

There is also a set of [simple sink tests] (https://github.com/hangoutsbot/hangoutsbot/tree/staging/hangupsbot/tests) that can be adapted to test your own custom sinks:

base-send.py

A simple script that can be executed directly from the Python3 interpreter and used to send messages and an optional picture to sinks based on either BaseBotRequestHandler such as sinks.generic.SimpleMessagePoster or [ver>=2.7] AsyncRequestHandler such as sinks.generic.AsyncMessagePoster

usage: base-send.py [-h] [-i IMAGEPATH] [-n IMAGEFILENAME] url content
positional arguments:
  url                   url to send the data
  content               content to send, quote if it contains spaces
optional arguments:
  -h, --help            show this help message and exit
  -i IMAGEPATH, --imagepath IMAGEPATH
                        image to send as base64-encoded string
  -n IMAGEFILENAME, --imagefilename IMAGEFILENAME
                        image filename

Examples:

python3 tests/base-send.py https://127.0.0.1:9999/<conv id> "Hello World!"

python3 tests/base-send.py \
  https://127.0.0.1:9999/<conv id> \ 
  "Hello World!" \
  --imagepath <image file path>

# replace <conv id> and <image file path> appropriately

Note: Custom sink developers may override the default functionality of BaseBotRequestHandler/AsyncRequestHandler, preventing the test script from working as intended

Reference Documentation

• AsyncRequestHandler class reference
• BaseBotRequestHandler class reference