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
- Mentions : If somebody mentions you in a room, receive a private hangout from the bot with details onthe 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] (https://github.com/hangoutsbot/hangoutsbot/wiki/Authoring-Bot-Extensions), 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] (https://github.com/hangoutsbot/hangoutsbot/wiki/Plugin-List)!
Note: First run? See the [installation instructions] (https://github.com/hangoutsbot/hangoutsbot/blob/master/INSTALL.md)
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
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]
(https://github.com/hangoutsbot/hangoutsbot/blob/master/INSTALL.md#additional-configuration)
in the [installation]
(https://github.com/hangoutsbot/hangoutsbot/blob/master/INSTALL.md)
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.
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]
(https://github.com/hangoutsbot/hangoutsbot/wiki/Mentions-Plugin)
- alert users when their names are mentioned in a chat
- [subscribe plugin]
(https://github.com/hangoutsbot/hangoutsbot/wiki/Subscribe-Plugin)
- alert users when keywords they are subscribed to are said in a chat
- [syncout / syncrooms plugins]
(https://github.com/hangoutsbot/hangoutsbot/wiki/Syncouts-Plugin)
- 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] (https://github.com/hangoutsbot/hangoutsbot/wiki/Plugin-List)...
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)
Without any plugins, the bot only recognises the following /bot
commands:
/bot help
- Bot lists all supported commands in a private message with the user
- If the user does not have a 1-on-1 channel open, it will publicly tell the user to PM the bot and say hi
/bot locale <language code>
- Temporarily switches the bot language to a supported language from the [translation project] (https://github.com/hangoutsbot/hangoutsbot-locales)
- Resets to English (untranslated) on bot restart
/bot optout
- Toggles opt-in/opt-out of advanced bot features.
- Works by making existing 1-on-1 chat with the specific user invisible to the bot
- Bot will continue responding to the user in a group chat, but any feature/plugin which requires a 1-on-1 chat is effectively disabled when toggled ON
- Sending a private message to the bot when you are opted-out will automatically toggle opt-out OFF
/bot ping
- Bot replies with a
pong
.
/bot version
- Bot replies with the version number of the framework
Please see the wiki for the [list of plugins] (https://github.com/hangoutsbot/hangoutsbot/wiki/Plugin-List) to find out more about each plugin and their usage.
- 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 hangupsbotpip3 install -r requirements.txt --upgrade
- Restart the bot
- Run the bot with the
-d
parameter e.g.python3 hangupsbot.py -d
- this lowers the log level toINFO
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.
Program isn't running:
- Update
hangupsbot
andhangups
- 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.
Please see https://github.com/hangoutsbot/hangoutsbot/wiki/Authoring-Bot-Extensions
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