mautrix-googlechat

README

mautrix-googlechat (Go)

A Matrix–Google Chat puppeting bridge, built on mautrix-go bridgev2.

Status: pre-alpha, under active development.

This project is not affiliated with, endorsed by, or supported by Google. "Google Chat" is a trademark of Google LLC.

Features

Feature	Status
Text messages (send/receive)	Supported
Rich text formatting (bold, italic, links, etc.)	Supported
Threads	Supported
Replies	Supported
Message edits	Supported
Message deletes	Supported
Reactions	Supported
Read receipts	Supported
Typing notifications	Supported
Inbound media (Google Chat → Matrix: images, files)	Supported
Outbound media (Matrix → Google Chat)	Supported — verified against Google's live endpoint (2026-07-22), using the purple-googlechat request shape (which avoids the client bug behind upstream issue #114). Can be disabled via network.disable_outbound_media
Room renames / topic changes	Supported
Membership changes (joins/invites/leaves/kicks)	Supported
History backfill	Supported (opt-in, see Configuration)

The full mautrix-style feature matrix is in ROADMAP.md.

Requirements

• Go 1.25 or newer
• A Matrix homeserver that supports the Application Service API
• A PostgreSQL or SQLite (sqlite3-fk-wal) database
• A Google account with access to Google Chat (cookie-based login only — see docs/authentication.md)

The bridge is built with the pure-Go goolm crypto implementation (build tag goolm) instead of libolm; this is the only supported build configuration, and ./build.sh always passes -tags goolm.

Quick start

Build the bridge:

./build.sh

Generate an example config file (fails if the target path already exists):

./mautrix-googlechat -e -c config.yaml

Edit config.yaml: at minimum set homeserver.address/homeserver.domain, appservice.address, and database.uri. See Configuration below for bridge-specific options.

Generate the appservice registration (requires homeserver.domain to already be set in the config):

./mautrix-googlechat -g -c config.yaml -r registration.yaml

Add registration.yaml to your homeserver's application service registrations (e.g. Synapse's app_service_config_files) and restart the homeserver. See the mautrix docs on registering appservices for details.

Run the bridge:

./mautrix-googlechat -c config.yaml

Then open a DM with the bridge bot on your homeserver and send login (inside that DM, no prefix needed — use !gc login, or your configured command_prefix, elsewhere) to start the cookie login flow. See docs/authentication.md for how to extract the required cookies.

Docker

A Dockerfile and docker-run.sh are provided; no pre-built image is published yet. Build it locally:

docker build -t mautrix-googlechat .

First run writes an example config to /data/config.yaml if none exists yet, then exits so you can edit it:

docker run --rm -v $(pwd)/data:/data mautrix-googlechat
# edit ./data/config.yaml

Generate the registration by running the binary directly inside the container (docker-run.sh itself doesn't do this step):

docker run --rm -v $(pwd)/data:/data --entrypoint /usr/bin/mautrix-googlechat \
    mautrix-googlechat -c /data/config.yaml -g -r /data/registration.yaml

Then start the bridge normally:

docker run -v $(pwd)/data:/data mautrix-googlechat

Configuration

The full config is generated by -e above (network-specific options are nested under the top-level network: key; the rest is the standard mautrix-go bridgev2 config). Notable options:

• network.displayname_template — display name template for Google Chat ghost users.
• network.initial_chat_sync — how many most-recently-active chats to create portals for after login.
• network.disable_outbound_media — disable sending Matrix media to Google Chat (see the outbound-media caveat in the feature table above).
• backfill.enabled — must be true to enable history backfill at all (a framework-level option shared across all mautrix-go bridges).
• backfill.max_initial_messages / backfill.threads.max_initial_messages — must be greater than zero for backfill to actually populate messages in new rooms/threads; zero or negative disables backfill in new rooms even if backfill.enabled is true.
• bridge.permissions — must grant at least user-level access to your Matrix account before the login command will work.

Authentication

Google Chat has no interactive OAuth login for third-party clients; this bridge authenticates by cookie, extracted manually from a logged-in browser session. See docs/authentication.md for the full, step-by-step cookie-extraction and login guide, including an important security warning about what these cookies grant access to.

Migrating from the Python bridge

If you're moving from the original Python mautrix/googlechat bridge, this bridge can migrate its database directly — portals, ghosts, messages (including multi-part/attachments), reactions, users, saved logins, and double-puppeting — via --migrate-from-python. See docs/migration.md for prerequisites (read these first — in particular, stop the Python bridge and back up both databases before running anything), the exact command, and the full list of known, documented caveats.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — see LICENSE.