- Python 97.5%
- Shell 1.8%
- Dockerfile 0.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .beans | ||
| .superpowers/sdd/2025-08-04-bridge-refactor | ||
| chatto_bridge | ||
| discord | ||
| docs | ||
| LICENSES | ||
| nostr | ||
| scripts | ||
| slack | ||
| tests | ||
| .beans.yml | ||
| .env.example | ||
| .gitignore | ||
| Dockerfile | ||
| LICENSE | ||
| LICENSING.md | ||
| pyproject.toml | ||
| README.md | ||
| REUSE.toml | ||
chatto-bridge
Unofficial Discord ↔ Chatto bridge bot. Built on discord.py (cog system) and chattolib.
This is a fork of TheCodemancerLtd/chatto-bridge, adapted to work against recent Chatto versions (currently tested with
v0.5.0). See Fork changes for details.
Features
- Bidirectional message forwarding between linked Chatto rooms and
Discord channels, with per-user attribution (Chatto users appear in
Discord via channel webhooks carrying their display name and avatar;
Discord users appear in Chatto as
**name**: text). - Replies work across both platforms. A reply in Discord becomes a
real Chatto reply (
in_reply_to), and a reply in Chatto is rendered in Discord as a> **author**: snippetquote above the forwarded text (webhooks cannot create native Discord replies). Replying to a message that was never bridged degrades gracefully instead of breaking. - Edits sync both ways. Edits on either side are mirrored onto the bridged counterpart message via a persistent message-link table — no duplicate posts.
- Discord → Chatto attachments. Images and files sent in Discord are
downloaded and re-uploaded as real, encrypted Chatto assets
(
attachment_asset_ids), so they survive in Chatto history. Attachments above a size cap (~20 MiB) are skipped and noted in the message body. - Chatto avatars shown in Discord. Forwarded Chatto messages carry
the author's avatar (resolved via
batch_get_users) alongside their display name. - Interactive room linking via
/bridge linkslash commands (see below).
The bridge is intended to run co-located with the Chatto server so it can
speak directly to Chatto's NATS event bus for the Chatto → Discord direction.
The Discord → Chatto direction goes through Chatto's public ConnectRPC API
using a bot user account (chattolib's ChattoClient) — publishing raw
protobuf into NATS is not supported by Chatto and would bypass RBAC,
mentions, link previews, and asset binding.
Note: since Chatto v0.5 encrypts message bodies per-user, the Chatto →
Discord direction does not read message text from NATS. The NATS event only
signals that a message was posted; the bridge then fetches the decrypted
message through the ConnectRPC API as the bot account
(ChattoClient.get_message).
Install (Docker, recommended)
docker build -t chatto-bridge .
No Chatto version pinning is required — the bridge tracks the current Chatto release and the protobuf bindings are generated accordingly at build time.
Minimal docker-compose.yml snippet (place the bridge in the same compose
project as Chatto so service-name DNS resolves):
services:
chatto-bridge:
build: ./chatto-bridge
depends_on:
- chatto
restart: unless-stopped
env_file: ./chatto-bridge/.env
volumes:
- bridge-data:/app
volumes:
bridge-data:
The bridge-data volume persists chatto-bridge.db (the room ↔ channel
mappings created with /bridge link, the /bridge forward_bots setting,
and the message-link table powering edit/reply propagation) across rebuilds.
Install (from source)
Requires protoc (Protocol Buffers compiler) and jq on PATH.
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# Generate protobuf bindings for NATS event decoding:
bash scripts/generate_pb.sh
scripts/generate_pb.sh fetches the full proto tree from
chattocorp/chatto, pulls the
buf/validate dependency on demand, and runs protoc with the
well-known-types include path.
Configure
Copy .env.example to .env and fill in credentials:
cp .env.example .env
Required env vars:
| Var | What |
|---|---|
DISCORD_BOT_TOKEN |
Bot token from the Discord developer portal |
DISCORD_GUILD_ID |
The guild (server) this bridge attaches to |
CHATTO_BASE_URL |
e.g. https://chat.chatto.run; in Docker Compose use the internal service URL, e.g. http://chatto:4000 |
CHATTO_LOGIN |
Login for the Chatto bot account |
CHATTO_PASSWORD |
Password for the Chatto bot account |
NATS_URL |
e.g. nats://localhost:4222; in Docker Compose use nats://nats:4222 (Chatto's CHATTO_NATS_CLIENT_URL rewritten with the service name) |
NATS_AUTH_TOKEN |
optional; matches the --auth=${NATS_TOKEN} flag on Chatto's NATS container |
BRIDGE_MAP |
optional JSON {"<chatto_room_id>": <discord_channel_id>, ...}; if unset, manage links via /bridge link instead |
Tip: leave BRIDGE_MAP unset and use the Discord slash commands — the env
var always overrides the persisted database, which makes interactive
linking appear broken while it is set.
Run
chatto-bridge
# or
python -m chatto_bridge.discord
Runtime bridge map changes (/bridge link) are persisted to
chatto-bridge.db in the working directory and survive restart.
The BRIDGE_MAP env var always takes precedence over the persisted file.
The /bridge link command accepts a Chatto room ID or room URL and links
it after verifying the room exists on the server (a case-insensitive ID
match is tried as a fallback); input that matches no room opens an
interactive room picker using the input as a name/ID search filter:
/bridge link— browse and select a Chatto room/bridge link <room id or url>— link directly (verified against the room list; unknown IDs fall back to the picker)/bridge link <text>— filter rooms by name or ID
Other commands:
/bridge unlink— remove the link for the current channel/bridge list— show all active bridge links/bridge forward_bots [true|false]— toggle mirroring of other apps and webhooks from Discord into Chatto (off by default)
Commands are registered guild-scoped for DISCORD_GUILD_ID and require the
"Manage Server" permission to invoke. If they do not appear after inviting
the bot, hard-refresh your Discord client and verify the invite includes the
applications.commands scope.
How bridging works
- Chatto → Discord: the bridge tails Chatto's NATS event stream, and
for each
message_postedevent fetches the decrypted message via the ConnectRPC API, then posts it to the linked Discord channel through a per-channel webhook carrying the author's name and avatar. - Discord → Chatto: inbound Discord messages are posted to the linked
Chatto room via
ChattoClient.post_message, with attachments uploaded first (upload_attachment) and passed asattachment_asset_ids. - Reply propagation: both sides maintain a persistent message-link
table mapping each bridged message to its counterpart ID. Discord
replies resolve to real Chatto replies through this table; Chatto
replies are rendered as block quotes in Discord (webhooks cannot set
message_reference). - Edit propagation: the same link table lets edits on either side update the counterpart message in place.
Chatto NATS subjects consumed
The bridge subscribes to Chatto's plain NATS republish subject
live.evt.room.> (mirror of the JetStream EVT stream), so no durable
JetStream consumer state has to be maintained. Payloads are the
chatto.core.evt.v1.Event protobuf envelope Chatto uses internally.
Fork changes
Relative to upstream, this fork fixes compatibility with recent Chatto
versions (currently tested against v0.5.0) and Python 3.12, and adds the
features listed under Features:
- Proto namespace: Chatto restructured protos from
chatto.core.v1tochatto.core.evt.v1.scripts/generate_pb.shfetches the full recursive proto tree (surviving directory reshuffles) and pulls thebuf/validate+ well-known-type dependencies. - No version pinning: unlike upstream, no
CHATTO_REFbuild argument is needed — protobuf bindings are generated from the current Chatto release, so the bridge follows Chatto without manual version bumps. - Python 3.12:
importlib.metadata.entry_points()no longer returns a dict; the plugin loader uses.select(group=...). - Import shadowing: the
discord/source tree is remapped tochatto_bridge.discordat install time, so intra-package imports use the installed name, andChattoBridgeBotis imported at runtime, not just underTYPE_CHECKING. - Namespace collision: chattolib ships its own generated
chattopackage; the bridge merges its_pb/chattotree into the existing package's__path__sochatto.core.evt.v1resolves at runtime. - Encrypted message bodies: Chatto v0.5 reserves the
bodyfield onmessage_posted(text travels per-user-encrypted in a separatemessage_bodyevent), so the Chatto → Discord direction now fetches the decrypted message through the ConnectRPC API viaChattoClient.get_messageinstead of reading the NATS payload. Author display names resolve throughbatch_get_users; echoes of the bridge's own posts are suppressed. - Replies: Discord replies become real Chatto replies via
post_message(in_reply_to=...), with the reply-ping mention Discord pins into reply content stripped. Chatto replies are rendered as> **author**: snippetquotes in Discord. - Edits: a persistent message-link table maps bridged messages to
their counterparts on both platforms;
on_message_editand Chattomessage_editedevents update the counterpart in place. Rows the bridge did not author are excluded from webhook edits, since webhooks can only edit their own messages. - Discord → Chatto attachments: attachments are downloaded (size-capped),
staged in temp files, uploaded via
ChattoClient.upload_attachment, and posted withattachment_asset_ids. Skipped or failed uploads are noted in the message body instead of silently disappearing. - Chatto avatars in Discord: forwarded messages include the author's
avatar URL (resolved via
batch_get_users) as the webhook avatar. - Docker: adds a multi-stage
Dockerfile(non-root runtime) and a compose service definition.
Layout
Sources are organised by chat platform, with shared (chatto-side) code at
the repo root. Setuptools remaps the on-disk discord/ and slack/
directories into subpackages of chatto_bridge so that the discord/
folder does not shadow the pypi discord.py package at import time —
see [tool.setuptools.package-dir] in pyproject.toml.
/
├── chatto_bridge/ # shared, imported as `chatto_bridge`
│ ├── events.py # RoomEvent, subject parser, protobuf decoder
│ ├── engine.py # Chatto client, session recovery, message posting
│ ├── mapping.py # room ↔ channel map, settings, message-link table
│ └── _pb/ # generated chatto.core.evt.v1 bindings (gitignored)
├── discord/ # imported as `chatto_bridge.discord`
│ ├── __main__.py # entrypoint (also the `chatto-bridge` script)
│ ├── bot.py # commands.Bot subclass; loads cogs
│ ├── config.py # env → typed config
│ └── cogs/
│ ├── nats_listener.py # subscribe live.evt.room.>, dispatch to bot
│ ├── chatto_to_discord.py # forward chatto events to discord webhooks
│ ├── discord_to_chatto.py # forward discord messages via chattolib
│ ├── room_resolver.py # room ID/URL resolution
│ └── admin.py # /bridge link|unlink|list|forward_bots commands
├── slack/ # imported as `chatto_bridge.slack` (placeholder)
├── proto/ # fetched chatto protos (gitignored)
├── scripts/generate_pb.sh # fetches protos + runs protoc
├── docs/nats.md # subjects consumed + write-path rationale
├── tests/
└── pyproject.toml
License
- chatto-bridge's own code is licensed under MPL-2.0 (Mozilla Public License 2.0) — a weak, file-level copyleft. You can use, distribute, and embed chatto-bridge in commercial or proprietary software; modifications to the bridge's own files must be released under MPL-2.0.
- Any vendored Chatto protobuf sources under
proto/chatto/**and their generated bindings are Apache-2.0, matching upstreamchattocorp/chatto.
See LICENSING.md for the full picture and REUSE.toml for the machine-readable licence map.