hangoutsbot / hangoutsbot

Google Hangouts bot

Introduction

Hangupsbot is a chat bot designed for working with Google Hangouts.

Please see:

• Instructions for installing
• Issue tracker for bugs, issues and feature requests
• Wiki for everything else

Repository Links

• GitHub Organisation
• Translation Project
• Reference Hangups Library

Features

• Mentions : If somebody mentions you in a room, receive a private hangout from the bot with details on the mention, including context, room and person who mentioned you.
• Syncouts : A syncout is two Hangout group chats that have their messages forwarded to each other, allowing seamless interaction between the two rooms. Primarily used to beat the 150-member chat limit, but it can also be used for temporarily connecting teams together to interact.
• Cross-chat Syncouts : Half of your team is on Slack? No problem! You can connect them into the same room to communicate. Support for other chat clients coming soon.
• Hubot Integration: Hangupsbot allows you to connect to Hubot, instantly providing you access to hundreds of developed chat tools and plugins.
• Plugins and sinks : The bot has instructions for developing your own plugins and sinks, allowing the bot to interact with external services such as your company website, Google scripts and much more.
• Plugin mania : games, nickname support, subscribed keywords, customizable API - the list goes on!

Running The Bot

Note: First run? See the installation instructions

To execute: python3 hangupsbot.py

usage: hangupsbot [-h] [-d] [--log LOG] [--cookies COOKIES] [--memory MEMORY] [--config CONFIG] [--version]

optional arguments:
-h, --help         show this help message and exit
-d, --debug        log detailed debugging messages (default: False)
--log LOG          log file path (default:
                   ~/.local/share/hangupsbot/hangupsbot.log)
--cookies COOKIES  cookie storage path (default:
                   ~/.local/share/hangupsbot/cookies.json)
--memory MEMORY    memory storage path (default:
                   ~/.local/share/hangupsbot/memory.json)
--config CONFIG    config storage path (default:
                   ~/.local/share/hangupsbot/config.json)
--version          show program's version number and exit

Bot Configuration for Administrators

Configuration directives can be specified in config.json.

Please note that the config.json file supplied with the repository is not supposed to be edited/changed. It is the reference file used by the bot to create the actual configuration file located elsewhere in the system. To find out where the actual file is, please see the Additional Configuration section in the installation instructions.

Most configuration directives are specified globally

• Global directives are always specified in the "root" of config.json.
• To specify a per-conversation directive, the same configuration option should be defined as config.conversations[<conversation-id>].<configuration option>.
• Per-conversation directives override global settings, if both are set.
• Manually-configured per-conversation directives are DEPRECATED.

Plugins

The plugins key in config.json allows you to optionally specify a list of plugins that will be loaded by the bot on startup. If this option is left as null, then all available plugins will be loaded.

To specify the plugins to be loaded, first ensure that the correct .py files are inside your hangupsbot/plugin/ directory, then modify the plugins key in config.json to reflect which plugins/files you want to load e.g. plugins: ["mentions", "default", "chance", "syncrooms"]

Some plugins may require extra configuration. config.json is the the configuration provider for the bot and its plugins.

Some interesting plugins:

• mentions plugin
  • alert users when their names are mentioned in a chat
• subscribe plugin
  • alert users when keywords they are subscribed to are said in a chat
• syncout / syncrooms plugins
  • relay chat messages between different hangout group conversations (syncrooms)
  • configure via bot commands (syncrooms_config)
  • automated translation via Google Translate of relayed messages (syncrooms_autotranslate)

The wiki has a more comprehensive list of plugins...

Interacting with the Bot

There are two general types of interactions with the bot:

• /bot commands begin with /bot e.g. /bot dosomething
  • some bot commands are admin-only
• custom interactions (usage and accessibility varies by plugin)

The base bot supports some basic command even without any plugins loaded. Here is a partial list:

/bot help

• Bot lists all supported commands in a private message with the user

/bot ping

• Bot replies with a pong.

/bot version

• Bot replies with the version number of the framework

A full list of commands supported by the base framework is available at the Core Commands wiki page.

The wiki also has a list of plugins detailing available plugins with commands lists and usage.

Updating

• Navigate to the bot directory (eg. cd ~/hangupsbot)
• Change to the latest stable branch using git checkout master
• git pull to pull the latest version of hangupsbot
• pip3 install -r requirements.txt --upgrade
• Restart the bot

Debugging

• Run the bot with the -d parameter e.g. python3 hangupsbot.py -d - this lowers the log level to INFO for a more verbose and informative log file.
• tail the log file, which is probably located at /<user>/.local/share/hangupsbot/hangupsbot.log - the location varies by distro!
• Console output (STDOUT) is fairly limited whatever the log level, so rely on the output of the log file instead.

Tips for troubleshooting

Program isn't running:

• Update hangupsbot and hangups
• Run hangups to check if the original hangups library is working
  • If there are errors, delete the cookie at ``~/.local/share/hangupsbot/cookies.json` and try again
  • Log into your Google Account from the server's address.

Bot isn't responding to messages:

• Check that the chats are not going into the 'Invites' section of Hangouts.

Extending

Please see https://github.com/hangoutsbot/hangoutsbot/wiki/Authoring-Bot-Extensions

Credits / History

Hangoutsbot is derived from the mogunsamang bot, which itself is a fork of xmikos's hangupsbot

On 2015-06-20, this fork was detached and made standalone on GitHub

On 2015-07-03, the fork was made into a Github Organisation

hangoutsbot's Issues

Can't set nickname if field in config doesn't exist

/me trigger doesn't work correctly from mobile client?

desktop - web client
after entering: /me says something
I can see in the hangouts window: My_nick says something

mobile client:
after entering: /me says something
I can see: /me says something

is it code-related or server-side issue?

Messages and commands get processed too slowly when external hooks are enabled

namelock plugin causes an exception if memory is empty

possibly missing a try block when the key doesnt exist

lottery plugin broken with syncrooms

The lottery plugin uses conversation memory to remember its drawings - since syncroom are in multiple rooms, users in other rooms won't be able to draw from another lottery in a different room. May require a conjugate "key" when used in a syncroom. One of the issues involved from this is to make the lottery plugin syncroom aware.

Google Scripts sink not working

I can't seem to work out what exception is being thrown, so until I improve the debugging messages for sinks, I'm pretty much stuck with this one.
Last commit: 1a4a39d

namelock incorrectly displays ampersands (&) in setting topic message

The bot requires well-formed HTML to be sent into the parser. & needs to be converted to & prior to be being sent. Otherwise the following will occur:

/bot topic T&C Stuff
Oto replies with "Setting topic to 'T Stuff'"

/setnickname accepts virtually anything

Although this doesnt actually result in anything but hilariously formatted nicknames, the security risk greatly increases if an actual database is used will increase. The nickname should be filtered for a very limited character-set (such as [A-Z0-9-_]), with any non-matching characters replaced or removed.

[internal] better exception handling for plugins + custom handlers

try blocks ALL THE THINGS! (it makes plugin devs lives easier)

Documentation for plugin authoring

The plugin system allows more streamlined development of bot commands and triggers - it needs to be completed before the plugins branch can be considered done.

[upgrade] segments_to_html parser

presently there is only simple_parse_to_segments() (html to ChatMessageSegments) - project needs a reverse parser for testing and general usage by plugins when necessary re: #59

[feature] plugins should be able to decide for themselves which commands are admin-only

requires an optional function that can be called during plugin init

[feature] auto-translation of forwarded/sync hangouts

for some unknown reason, this scares me... preliminary roadmap:

• store "native" 2-letter iso language code in conversation memory
• modify sending handler to allow in-line translation of outgoing messages
• implement support for automatic translation between forwarded/synced hangouts

this list is subject to change

Support for running hangupsbot.py as a daemon

http://www.jejik.com/files/examples/daemon3x.py

This link above allows python scripts to be run as daemons. After a personal catastrophe with a start script and cron, having native support to be run as a daemon would be invaluable.

hangupsbot bypassing plugins and syncing all HO activity.

I wrote a new plugin based off of the syncrooms.py plugin (which is disabled) that only syncs words that match a certain pattern.

However, any HO activity, such as a user leaving a HO, gets reposted to all of the synced HOs. I've got multiple failsafes in place to make sure that unless a pattern is matched nothing is synced.

I've got several debugging statements in place walking through the code making sure the text matches the pattern before syncing, but my plugin is not being called as none of the debugging output is found.

Is this expected behavior and is there some way around this? It's unfortunately caused a lot of problems since moving to the new plugin system and I don't know why the non-matching output is being synced and my plugin being completely bypassed.

lottery plugin does not appear to recognise /me commands

tested with staging

After first start got this, and after restart bot do not respond to querry

# python3 hangupsbot.py -d
memory file will be used
creating memory file: /root/.local/share/hangupsbot/memory.json
Email: [email protected]
Password:

logger failed to initialise: config.hooks[].storage_path cannot be empty
hook failed to initialise
hook inited: ['hooks', 'hubotsend', 'post', 'sender']
1 hook(s) loaded
config.jsonrpc[0].certfile must be configured
config.jsonrpc[1].certfile must be configured
config.jsonrpc[2].certfile must be configured
thread starting: ['sinks', 'hubotreceive', 'post', 'receiver']
setting event loop
1 sink thread(s) started
setting static reference to bot
pem file possibly missing or broken (== '/root/server.pem')
Connected!

Autoreply doesn't parse spaces in triggers

The autoreply function doesn't seem to respond when the trigger phrases have spaces in them. The default examples "hi bot" and "hello bot" don't work out of the box. Setting a trigger phrase without a space works just fine.

Ability to make syncouts from hangouts

It would be awesome if syncouts can be made by hangouts.
Some thoughts:
/bot syncout <arraynumber> would add the current chat to a syncout of that array number.
Since syncouts are stored in an array, this would be easy to implement. The hard bit is working out which array to add the syncout to. Maybe calling /bot syncout with no parameters specified will output the current syncout settings and attached hangouts, if any?

When a person is in several chats of the same syncout, mentions do not work

duplicated command list in /bot help

Excerpt:

Admin commands:
allowbotadd, attachsyncout, config, config, detachsyncout, easteregg, forgetaboutitforchat, forgetaboutitforme, hangout, hangouts, hangouts, leave, leave, quit, quit, reload, reload, rememberthisforchat, rememberthisforme, removebotadd, rename, rename, topic, user, user, users, users, whatwasitforchat, whatwasitforme, whereami

restrictedadd will not force bot to leave upon creation of a group hangout with the bot

I assume this is because there is no hangups.MembershipChangeType.JOIN that is triggered upon creation of a new hangout.

[upgrade] optional context on all send message functionality

• modify bot framework and add karg context
• plugins need to supply context when sending messages

goal: allow suppression of messages via specialised sending handlers in a similar way to logger levels (DEBUG, INFO, WARNING, ERROR, etc)

After last pull have error

Client unexpectedly disconnected:
Failed to get initialize chat value: 'ds:7'

/bot setnickname does not check that the user is setting his own nickname

Affected plugin: mentions

User: /bot setnickname ABC
Bot: Setting nickname to "ABC"
User: /bot setnickname ABC
Bot: Error: Nickname already in use by somebody else!

Allow certain keywords set by user to trigger mentions

eg I want to be pinged everytime somebody says 'Nihal is awesome' in one of the groups that I'm in

Allow a single bot to handle multiple syncouts

Client unexpectedly disconnected: unsupported operand type(s) for //: 'str' and 'int'

I was using the previous version of hangupsbot with great success until I started getting the error message in the subject.

So, I upgraded to the latest version and I'm still getting the error. For the life of me I can't find where the hell it's coming from, but I'm assuming it's one of the included libraries (just a hunch). This is what the output from the new version looks like (as did the old one minus the new plugin messages, etc):

$ ./hangupsbot.py --debug --log /tmp/hangupsbot.log
HangupsBot: memory file will be used
main(): config.plugins is not defined, using ALL
plugin command: plugins.easteregg -> easteregg
plugin command: plugins.lookup -> lookup
plugin command: plugins.chance -> coinflip
plugin command: plugins.chance -> diceroll
plugin command: plugins.lottery -> perform_drawing
plugin command: plugins.lottery -> prepare
plugin introspection: plugins.mentions implements ['mention', 'pushbulletapi', 'dnd', 'setnickname']
plugin command: plugins.mentions -> dnd
plugin command: plugins.mentions -> mention
plugin command: plugins.mentions -> pushbulletapi
plugin command: plugins.mentions -> setnickname
plugin introspection: plugins.default implements ['users', 'user', 'hangouts', 'rename', 'leave', 'reload', 'quit', 'config', 'whoami', 'whereami', 'echo']
plugin command: plugins.default -> config
plugin command: plugins.default -> echo
plugin command: plugins.default -> hangouts
plugin command: plugins.default -> leave
plugin command: plugins.default -> quit
plugin command: plugins.default -> reload
plugin command: plugins.default -> rename
plugin command: plugins.default -> user
plugin command: plugins.default -> users
plugin command: plugins.default -> whereami
plugin command: plugins.default -> whoami
logger: chats stored in /tmp
_load_hooks(): ['hooks', 'chatlogger', 'writer', 'logger']
config.jsonrpc[0].certfile must be configured
config.jsonrpc[1].certfile must be configured
config.jsonrpc[2].certfile must be configured
Client unexpectedly disconnected:
unsupported operand type(s) for //: 'str' and 'int'
Waiting 5 seconds...
Trying to connect again (try 1 of 5)...
Client unexpectedly disconnected:
unsupported operand type(s) for //: 'str' and 'int'
Waiting 10 seconds...
Trying to connect again (try 2 of 5)...
Client unexpectedly disconnected:
unsupported operand type(s) for //: 'str' and 'int'
Waiting 15 seconds...
Trying to connect again (try 3 of 5)...
Client unexpectedly disconnected:
unsupported operand type(s) for //: 'str' and 'int'
Waiting 20 seconds...
Trying to connect again (try 4 of 5)...
Client unexpectedly disconnected:
unsupported operand type(s) for //: 'str' and 'int'
Waiting 25 seconds...
Trying to connect again (try 5 of 5)...
Maximum number of retries reached! Exiting...

Any idea what's happening? It was working great, then I restarted the bot and then this happened with both versions.

Thanks.

auto-expire DND (do not disturb) i.e. give it a snooze

example usage:

/bot dnd <duration>

where <duration> = <integer><m|h|d> and not exceed 3 days

List users in a chat by last message sent, and frequency of messages

Useful for finding inactive members in a chat

[feature] allow comments in config.json

https://commentjson.readthedocs.org/en/latest/ seems like a likely candidate library that doesn't seem to break backward compatibility with config.py

Syncroom config.json migration

Need to set up migration of the syncroom config from the two previous methods that are now deprecated.

Doumentation for plugins should move from README -> Wiki

As the list of plugins begin to grow, it would be wise to move the documentation of how plugins work and the relevant commands and configs for them off the README and into the Wiki.

[upgrade] framework needs an "allmessages" handler

presently the "message" handler is insufficient for some plugin requirements

example: the subscribe plugin needs to monitor bot messages as well, but the standard message handler will not actually pass messages sent by the bot itself

this needs to be rectified in a future framework upgrade

autoreply plugin is leaking words_in_name and get_conv_name into commands namespace

return any allowed commands from _initialise() or just return []

re: #45

Hyperlinks don't work in syncouts

When a message has been sent across a syncout, the resulting hyperlink does not open, instead leading to a 'talkgadget' URL that's just a blank screen.

autoreplies should be a plugin (that supports UTF-8)

The current configuration of autoreplies should be moved to the /plugins folder, to allow for more flexibility in developing that module. For example, current configuration doesn't work with utf-8 formatting

syncroom membership does not track if users are present in multiple syncrooms

Syncrooms consist of Room X and Room Y
User A is member of Room X and Room Y
User A leaves Room X
Bot reports that "User A has left the Syncout" - incorrect! user is still in Room Y

[internal] MessageHandler class (and all related references) should be renamed

MessageHandler implements handlers for renames and membership changes. It should be renamed to a more accurate name e.g. "GenericHandler". Note that other related references must be changed as well to reflect the new name e.g. "_message_handler" -> "_generic_handler".in hangupsbot.py, etc

The impact to developers should be minimal as this object should not be called externally anyway.

Bot listening to commands from other HOs

So don't know if it is normal or not, but seeing that the bot is in another HO is it normal for the bot to listen to them as well ? Or should it be limited to listen to only specific HOs?

Example: I sorta wanted to point out to whom am I written a response to in one hangout and because @david is a really common name, I received a private message from the bot that there are multiple Davids. OK. But should it work in other HOs

allow locking of name of hangouts and can be changed only by set admins

deprecate use of HangupsBot._conv_list.get()

this function appears susceptible to "forgetting" conversations when they are a lot of conversations - possibly similar to way a standard hangouts client appears to load only the top 30-50 most recent conversations only (requires scroll to refresh on mobile and desktop)

send_message_parsed(conversation_id, html) already supports sending a message using just the conversation_id string

affected functions:

• HangupsBot.send_html_to_conversation()
• syncrooms plugin: line 155
• handlers.py: line 112

send_html_to_conversation(id, html), send_html_to_user(id, html)

two unambiguous functions are required for future extension development:

• send_html_to_conversation(id, html)
• send_html_to_user(id, html)

optional new function: send_html_to(user_or_conversation_id, html) that utilises both functions

deprecated functions, maintained for legacy support:

• external_send_message()
• external_send_message_parsed()

Move nicknames to memory.json

To free up space in config.json, the nicknames should be moved to memory.json

[feature] add translation support

translation support for all strings would be nice - also something like aliases for bot's functions. all configured in json or any other file

mention plugin problem

2015-02-12 15:51:07,633 - requests.packages.urllib3.connectionpool - INFO - Starting new HTTP connection (1): 127.0.0.1
2015-02-12 15:51:07,850 - requests.packages.urllib3.connectionpool - DEBUG - "POST /receive/UgzNRcid-454545-BXrp4AaABAQ HTTP/1.1" 404 357
2015-02-12 15:51:07,853 - root - INFO - list_conversations() returned 4 conversation(s)
2015-02-12 15:51:07,854 - root - INFO - @mention 'WORD' in 'Some chat ' (UgzNRcid-454545-BXrp4AaABAQ)

When i try to test what's wrong ::
/bot mention WORD test
@mentions:
Nobody was successfully @mentioned ;-(

htmlparser needs an upgrade

it has problems recognising certain kinds of entityref and often leads the bot to strip them out of messages that utilise the parser

Documentation for the new language plugins

It'd be nice to have some documentation on how the new language plugins work for both syncrooms and same-room translations.

If port 8080 is busy what we need to choose?

When bot start(in config i have 8080) i can't receive any PM, if i try to edit it to different port like 8081 i got this ::
requests.exceptions.ConnectionError: HTTPConnectionPool(host='127.0.0.1', port=8081): Max retries exceeded with url: /receive/UgyMnN07kw8Yupcnavd4AaABAQ (Caused by <class 'ConnectionRefusedError'>: [Errno 111] Connection refused)
2015-02-12 14:13:15,076 - root - INFO - memory: UgxNZ6rK7YFz0wip7G54AaABAQ is 1on1 with 100879078835333107083
2015-02-12 14:13:16,676 - requests.packages.urllib3.connectionpool - INFO - Starting new HTTP connection (1): 127.0.0.1
2015-02-12 14:13:16,677 - root - ERROR - ('_execute_hooks()', <class 'hooks.hubotsend.post.sender'>, ConnectionError(MaxRetryError("HTTPConnectionPool(host='127.0.0.1', port=8081): Max retries exceeded with url: /receive/UgyMnN07kw8Yupcnavd4AaABAQ (Caused by <class 'ConnectionRefusedError'>: [Errno 111] Connection refused)",),))
Traceback (most recent call last):
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/packages/urllib3/connectionpool.py", line 493, in urlopen
body=body, headers=headers)
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/packages/urllib3/connectionpool.py", line 291, in _make_request
conn.request(method, url, **httplib_request_kw)
File "/usr/local/lib/python3.4/http/client.py", line 1090, in request
self._send_request(method, url, body, headers)
File "/usr/local/lib/python3.4/http/client.py", line 1128, in _send_request
self.endheaders(body)
File "/usr/local/lib/python3.4/http/client.py", line 1086, in endheaders
self._send_output(message_body)
File "/usr/local/lib/python3.4/http/client.py", line 924, in _send_output
self.send(msg)
File "/usr/local/lib/python3.4/http/client.py", line 859, in send
self.connect()
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/packages/urllib3/connection.py", line 106, in connect
conn = self._new_conn()
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/packages/urllib3/connection.py", line 90, in _new_conn
(self.host, self.port), self.timeout, *extra_args)
File "/usr/local/lib/python3.4/socket.py", line 509, in create_connection
raise err
File "/usr/local/lib/python3.4/socket.py", line 500, in create_connection
sock.connect(sa)
ConnectionRefusedError: [Errno 111] Connection refused

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/adapters.py", line 327, in send
timeout=timeout
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/packages/urllib3/connectionpool.py", line 543, in urlopen
raise MaxRetryError(self, url, e)
requests.packages.urllib3.exceptions.MaxRetryError: HTTPConnectionPool(host='127.0.0.1', port=8081): Max retries exceeded with url: /receive/UgyMnN07kw8Yupcnavd4AaABAQ (Caused by <class 'ConnectionRefusedError'>: [Errno 111] Connection refused)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "hangupsbot.py", line 506, in _execute_hook
method(parameters)
File "/home/hangupsbot/hangupsbot/hooks/hubotsend/post.py", line 37, in on_chat_message
r = requests.post(url, data = json.dumps(payload), headers = headers, verify=False)
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/api.py", line 88, in post
return request('post', url, data=data, *_kwargs)
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/api.py", line 44, in request
return session.request(method=method, url=url, *_kwargs)
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/sessions.py", line 456, in request
resp = self.send(prep, *_send_kwargs)
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/sessions.py", line 559, in send
r = adapter.send(request, *_kwargs)
File "/usr/local/lib/python3.4/site-packages/requests-2.3.0-py3.4.egg/requests/adapters.py", line 375, in send
raise ConnectionError(e, request=request)
requests.exceptions.ConnectionError: HTTPConnectionPool(host='127.0.0.1', port=8081): Max retries exceeded with url: /receive/UgyMnN07kw8Yupcnavd4AaABAQ (Caused by <class 'ConnectionRefusedError'>: [Errno 111] Connection refused)

Can someone suggest me how to fix this?

subscribe-omnibus-enhancements

1. do not notify users if they mention their own subscribed keyword
   • when subscribing, users should be informed of this so they don't self-test
2. do not send any notifications when in 1on1 conversations
3. lowercase/uppercase the subscribed word to ignore casing altogether instead
   of per-iteration .lower()
4. suggestion: alternate type of whole-word matching? python supports word boundaries:

x = "b"
y = "a b c"
x = "\\b" + x + "\\b"
re.search(x, y, re.IGNORECASE)