hangups¶
hangups is the first third-party instant messaging client for Google Hangouts. It includes both a Python library and a reference client with a text-based user interface.
Unlike its predecessor Google Talk, Hangouts uses a proprietary, non-interoperable protocol. hangups is implemented by reverse-engineering this protocol, which allows it to support features like group messaging that aren’t available in clients that connect via XMPP.
hangups is still in an early stage of development. The reference client is usable for basic chatting, but the API is undocumented and subject to change. Bug reports and pull requests are welcome!
Quick Links¶
Documentation Contents¶
Installation¶
hangups requires Python 3.3 or 3.4, and is known to work on Linux and Mac OS X.
Python Package Index (PyPI)¶
hangups is listed in PyPI, and may be installed using pip.
Simply run pip to install the hangups package:
pip3 install hangups
Arch Linux¶
An unofficial hangups package is available for Arch Linux in the Arch User Repository.
Install from Source¶
The hangups code is also available from GitHub.
Either download and extract a hangups release archive, or clone the hangups repository on GitHub:
git clone https://github.com/tdryer/hangups.git
Switch to the hangups directory and install the package:
cd hangups
python3 setup.py install
User Guide¶
This section is intended for end-users who want to use the textual user interface included with hangups.
Running¶
Once installed, run this command to start hangups:
hangups
For help with command line arguments, run:
hangups -h
Logging in¶
The first time you start hangups, you will be prompted to log into your Google account with your email and password. If your account requires 2-step verification, you will also be prompted for a PIN. After a successful login, hangups will be able to log in automatically after starting.
hangups will only send your credentials to Google, and only session cookies will be stored locally. By default, session cookies are stored in a file in an OS-specific cache directory. The default cookie file location can be viewed using hangups -h. To specify a different cookie file, use the cookies option:
hangups --cookies /path/to/mycookies.json
If hangups is unable to access your account, try logging in through a browser first, and try again.
Usage¶
After connecting, hangups will display the conversations tab, which lists the names of all the available conversations. Use the up and down arrow keys to select a conversation, and press enter to open it in a new tab.
hangups uses a tabbed interface. The first tab is always the conversations tab. Once multiple tabs are open, use ctrl+u and ctrl+d and move up and down the list of tabs. Use ctrl+w to close a tab.
In a conversation tab, type a message and press enter to send it, or use the up and arrows to scroll the list of previous messages.
When new messages arrive, hangups will open a conversation tab in the background, and display the number of unread messages in the tab title. On Linux (with an appropriate desktop notification service running) and Mac OS X, hangups will also display a desktop notification. To mark messages as read, press any key (such as enter) while in a conversation tab.
When the network connection is interrupted, hangups will show a “Disconnected” message in each conversation. When the connection is restored a “Connected” message is shown, and hangups will attempt to sync any messages that were missed during the disconnection. If hangups is disconnected for too long, it will eventually exit.
To exit hangups, press ctrl+e.
Configuration¶
hangups may be configured through both command line arguments and a configuration file. See the output of hangups -h for details.
Keybindings are specified using urwid’s format, for example: ctrl e or shift ctrl e. Some key combinations may be unavailable due to terminal limitations or conflicts.
Troubleshooting¶
hangups can log information that may be useful for troubleshooting a problem. Run hangups -h to view the default log file path.
To specify a custom log file path, run:
hangups --log /path/to/mylog
To log detailed debugging messages, run:
hangups -d