{"id":13783607,"url":"https://github.com/matrix-hacks/matrix-puppet-hangouts","last_synced_at":"2026-01-16T19:23:15.251Z","repository":{"id":67550126,"uuid":"81785041","full_name":"matrix-hacks/matrix-puppet-hangouts","owner":"matrix-hacks","description":"Matrix bridge for Google Hangouts","archived":false,"fork":false,"pushed_at":"2020-03-30T20:33:58.000Z","size":43,"stargazers_count":49,"open_issues_count":9,"forks_count":19,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-17T20:47:28.630Z","etag":null,"topics":["google","hangouts","matrix","riot","vector"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-hacks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-02-13T04:31:58.000Z","updated_at":"2023-12-02T22:09:33.000Z","dependencies_parsed_at":"2023-05-18T17:00:33.435Z","dependency_job_id":null,"html_url":"https://github.com/matrix-hacks/matrix-puppet-hangouts","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-hacks%2Fmatrix-puppet-hangouts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-hacks%2Fmatrix-puppet-hangouts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-hacks%2Fmatrix-puppet-hangouts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-hacks%2Fmatrix-puppet-hangouts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-hacks","download_url":"https://codeload.github.com/matrix-hacks/matrix-puppet-hangouts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253621003,"owners_count":21937458,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google","hangouts","matrix","riot","vector"],"created_at":"2024-08-03T19:00:26.173Z","updated_at":"2026-01-16T19:23:15.220Z","avatar_url":"https://github.com/matrix-hacks.png","language":"Python","funding_links":[],"categories":["Bridges"],"sub_categories":["Google Hangouts"],"readme":"# matrix-puppet-hangouts [![#matrix-puppet-bridge:matrix.org](https://img.shields.io/matrix/matrix-puppet-bridge:matrix.org.svg?label=%23matrix-puppet-bridge%3Amatrix.org\u0026logo=matrix\u0026server_fqdn=matrix.org)](https://matrix.to/#/#matrix-puppet-bridge:matrix.org)\n\nThis is a Matrix bridge for Google Hangouts.\nIt logs in as (aka \"puppets\") both your matrix user and your hangouts user to\nestablish the bridge. For more information, see:\nhttps://github.com/matrix-hacks/matrix-puppet-bridge\n\nTo interact with the google hangouts servers, this bridge uses a python hangouts client library called hangups:\nhttps://github.com/tdryer/hangups\n\n## Requirements\n\n### For hangups, and our own python, python3 (Python 3.5+ for async) is required:\nsudo apt install python3 python3-dev\n(Or similar for your package manager)\n\nMake sure your python3 is version 3.5+ by running `python3 --version`\n\n### Install hangups system-wide:\n`sudo pip3 install hangups`\n\n## Installation\n\nClone this repo or download a release of the puppet\n\ncd into the directory\n\nrun `npm install`\n\n## Configure\n\nCopy `config.sample.json` to `config.json` and update it to match your setup.\n\nYou should really only have to edit the `homeserverUrl` and `domain` values. \nIf you are running the puppet on the same server as your homeserver, then you should probably\nset the `homeserverUrl` value to be `http://127.0.0.1:8008`.\n\n\n### Login to hangouts to save your authentication token.\n\nRun the following\n\n```\nmkdir -p ~/.cache/hangups\npython3 hangups_client.py --login-and-save-token\n```\n\nThis saves an authentication token into the default hangups token path (`~/.cache/hangups/` as of this writing).\n\n#### Troubleshooting Login\n\n##### Refresh token not found\n\nIf you get an error like this\n\n```\nTraceback (most recent call last):\n  File \"/home/keyvan/code/matrix-puppet-hangouts/env/lib/python3.6/site-packages/hangups/auth.py\", line 158, in get_auth\n    raise GoogleAuthError(\"Refresh token not found\")\nhangups.auth.GoogleAuthError: Refresh token not found\n```\n\nThen try logging in through a real browser first (lynx should work) to get past the SMS verification.\n\nIf you are still having this issue, make sure you turn off \"Login with my phone\" and \"2-step verification\". You may be able to turn these back on AFTER you've successfully logged in, but this is unconfirmed.\n\nYou can control these settings here: https://myaccount.google.com/security\n\n##### Authorization code cookie not found\n\nIf you get an error that says something along the lines of:\n\n`Login failed (Authorization code cookie not found)`\n\nYou may get your refresh token manually using hangups itself:\n\n```\nhangups --manual\n```\n(follow the instructions on screen in order to get the refresh token)\n\nWhile this will take you into a hangups TUI once everything is done, you can exit it with Control+E.\n\n\n### Register the app service\n\nNote: `your-bridge-server` is simply the IP address or hostname that your puppet will be running on, as it utilizes its own HTTP server for functionality. \nIf you are running Synapse and the puppet on the same system, feel free to use `localhost` or `127.0.0.1`.\n\nGenerate an `hangouts-registration.yaml` file with `node index.js -r -u \"http://your-bridge-server:8090\"`\n\nThis command above will ask you to sign in as a user. You should sign in as a user that is an administrator, otherwise you might experience problems.\n\nNote: The 'registration' setting in the config.json needs to set to the path of this file. By default, it already is.\n\nCopy this `hangouts-registration.yaml` file to your home server (or to the homeserver's configuration directory if the puppet and homeserver are the same system), \nthen edit it, setting its url to point to your bridge server. e.g. `url: 'http://your-bridge-server.example.org:8090'`. \n\nEdit your homeserver.yaml file and update the `app_service_config_files` with the path to the `hangouts-registration.yaml` file.\n\nLaunch the bridge with ```npm start```.\n\nRestart your HS.\n\nA handy way to control your puppet is through `systemd`. Here is a `systemd` service, that can be called `hangouts-puppet` and placed at `/etc/systemd/system`.\n```\n[Unit]\nDescription=Hangouts Matrix Puppet\n\n[Service]\nType=simple\nEnvironment=DEBUG=verbose:matrix-puppet:*\nUser=my-user-who-is-running-puppet-here\nGroup=my-group-who-is-running-puppet-here\nWorkingDirectory=/my/path/to/downloaded/puppet/here\nExecStart=/usr/bin/npm start\nRestart=always\nRestartSec=3\n\n[Install]\nWantedBy=multi-user.target\n```\nThis service will auto-restart when the puppet fails. If you want that to not be the case, remove the lines:\n```\nRestart=always\nRestartSec=3\n```\n\n## Discussion, Help and Support\n\nJoin us in the [![Matrix Puppet Bridge](https://user-images.githubusercontent.com/13843293/52007839-4b2f6580-24c7-11e9-9a6c-14d8fc0d0737.png)](https://matrix.to/#/#matrix-puppet-bridge:matrix.org) room\n\n## Using this puppet to bridge two group chats\nThis is a simple hack in order for this puppet to be usable to bridge two group chats, one on Matrix and one on Hangouts.\n\n1. Have a Google account that will be just for this puppet and create your hangups refresh token with this account.\n2. Run `register_new_matrix_user -c homeserver.yaml http://localhost:8008` on your Synapse homeserver. Make sure that this user is an administrator.\n3. Now run `node index.js -r -u \"http://your-bridge-server:8090\"`, but use the admin user you created before this in the registration.\n4. Follow other steps as detailed to get the puppet running.\n5. When the puppet starts successfully with `npm start`, invite the puppet's Google account to the group chat on Hangouts.\n6. By default, the sender's name is not shown, which makes it very difficult to bridge two group chats, because you wouldn't know who is who on the Matrix side in Hangouts.\nHowever, if you replace this block of code in `index.js`\n\n```js\nsendMessageAsPuppetToThirdPartyRoomWithId(id, text) {\n    return this.thirdPartyClient.send(id, text);\n}\nsendImageMessageAsPuppetToThirdPartyRoomWithId(id, data) {\n  return this.thirdPartyClient.sendImage(id, data);\n}\n```\nwith:\n```js\nsendMessageAsPuppetToThirdPartyRoomWithId(id, text, event) {\n    return this.thirdPartyClient.send(id, \"**\" + event.sender.split(\":\")[0].substring(1) + \"**\\n\" + text);\n}\nsendImageMessageAsPuppetToThirdPartyRoomWithId(id, data, event) {\n  this.sendMessageAsPuppetToThirdPartyRoomWithId(id, \"**\" + event.sender.split(':')[0].substring(1) + \"**\", event);\n  return this.thirdPartyClient.sendImage(id, data);\n}\n```\nyou should be able to see the sender's name from Matrix in the Hangouts chat. \n\nAll this does is the puppet adds a line before every message stating the sender in bold. \nWhile this only shows the localpart (username without homeserver), if you replace `event.sender.split(\":\")[0].substring(1)` with just `event.sender`, you will be able to see the username with the homeserver at the end, like `@username:homeserver.here`.\n\nAt the end, you should be able to just log in to Riot or your favorite client as that admin user that you created, and invite your real account to the \"bridged\" room. \n## TODO\n* Be able to start a brand new hangouts conversation fully from within a matrix client by choosing participants from your google contacts list. Currently, to start a new conversation this way, you'll have to start the conversation with an official hangouts client where your full contact list is available and once you send a message a bridged room will automatically be created for you. After this, you can carry on the rest of the conversation using your matrix client. Naturally, any incoming message will also automatically create a bridged room for you, so this limitation only applies when creating brand new rooms yourself. See this comment by tfreedman for a proposed solution to this problem - https://github.com/kfatehi/matrix-puppet-facebook/issues/2#issuecomment-274170696 and if you have any better ideas, please let us know!\n* Add a bot to each hangouts bridge room and use the bot's presence to indicate whether the bridge is running. This is an easy way to check on the status of the bridge.\n* Read receipt support.\n* Typing notification support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-hacks%2Fmatrix-puppet-hangouts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-hacks%2Fmatrix-puppet-hangouts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-hacks%2Fmatrix-puppet-hangouts/lists"}