Skip to content
A prototype Matrix<->Hangouts appservice written in Python 3.6 using asyncio.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
ansible v0.2.0 using the new appservice_framework Jan 6, 2018
matrix_appservice_hangouts only get auth users Mar 1, 2018
.gitignore Add Lots and lots of things. Aug 31, 2017
README.rst Add example of hangoutsas startup commands Jan 19, 2018
Vagrantfile WIP on send message. Dec 31, 2016
hangouts-as.yaml Refactor AS into a class. Jan 2, 2017
requirements.txt v0.2.0 using the new appservice_framework Jan 6, 2018 v0.2.0 using the new appservice_framework Jan 6, 2018
tox.ini Make this an actual package Sep 3, 2017



This is a matrix appservice with the objective of being a fully featured puppeting multi-user hangouts bridge.

This bridge is implemented in Python 3.6+ using asyncio and the hangups library. This library contains an asyncio implementation of parts of the matrix client-server API and the application service API.

Why Python 3.6

I wanted to implement this using asyncio and using the async def and await syntax. Python 3.6 is because I am lazy and love f-strings.


The appservice can be run with the hangoutsas command. The default options for this command connect to the localhost testing homeserver.

$ hangoutsas --help
  Usage: hangoutsas [OPTIONS]

    -m, --mxid TEXT
    -t, --token TEXT
    --matrix_server TEXT
    --server_domain TEXT
    --database-uri TEXT
    --access_token TEXT
    --debug / --no-debug
    --help                Show this message and exit.

You need to provide the matrix user id and hangouts authentication tokens for any users (technically only on first run, as they are then stored in the database). This may change in the future, but it is very hard to obtain hangouts tokens and there are security concerns over allowing people to login with the bridge. (Also I haven't implemented support for an admin chat channel yet!)


hangoutsas --matrix_server=http://localhost:8008 --access_token=xeehahR5eibXesEicohPh3Yisoi2osh5 --database-uri=sqlite:////opt/matrix-appservice-hangouts/hangouts.sqlite --mxid --token 1/7bVBdycv6hS2Su1F0jej2FTs9TJrNaCMkyX2_ARSnE4

where mxid is your matrix login which must receive messages from hangouts, --token is access_token of needed hangouts user (hangouts username is not needed, only access token). mxid and token pair can be set multiple times for add several hangouts bridges to different matrix users.

The best way to get your personal hangouts login token is to follow these instructions. When logged in, you can find the refresh token in ~/.cache/hangups/refresh_token.txt and use it to log in with the bridge.


NOTE: Currently the appservice_framework package requires a branch of the
matrix-python-sdk so it's probably better if you clone both this repo and the appservice-framework repo and install using requirements.txt in both.


Testing and Development

This repo also contains configuration for a vagrant VM running a matrix homeserver, this can be used to develop or test the appservice. It can be run with:

$ vagrant up --provision

You can then connect your matrix client to the address http://localhost:8008 with the username @admin:localhost and password admin.


  • Handle hangouts events: - Join room - Part room - Typing - Online / Offline (bidirectional)
  • Add some way of joining hangouts rooms before getting a message in the room. This might be made easier once communities are easily filterable on the matrix side.




matrix_appservice_hangouts was written by Stuart Mumford.

You can’t perform that action at this time.