Chatto <-> Discord bridge
  • Python 97.5%
  • Shell 1.8%
  • Dockerfile 0.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-15 06:18:29 +02:00
.beans refactor: plugin architecture with proper inheritance, engine.run(), and public API (chatto-bridge-rytk) 2026-08-04 16:01:50 +01:00
.superpowers/sdd/2025-08-04-bridge-refactor refactor: plugin architecture with proper inheritance, engine.run(), and public API (chatto-bridge-rytk) 2026-08-04 16:01:50 +01:00
chatto_bridge Added file transfer Discord -> Chatto 2026-11-15 05:11:42 +02:00
discord Uncommented permission requirement 2026-11-15 06:18:29 +02:00
docs feat: update chattolib, fix proto generation, add tests and docs (chatto-bridge-6dfy) 2026-08-04 14:00:31 +01:00
LICENSES Initial commit: Discord ↔ Chatto bridge bot scaffold 2026-07-14 01:13:28 +01:00
nostr refactor: plugin architecture with proper inheritance, engine.run(), and public API (chatto-bridge-rytk) 2026-08-04 16:01:50 +01:00
scripts generate_pb.sh: fetch full proto tree, pull buf/validate, add WKT path 2026-10-15 17:54:59 +03:00
slack refactor: plugin architecture with proper inheritance, engine.run(), and public API (chatto-bridge-rytk) 2026-08-04 16:01:50 +01:00
tests refactor: plugin architecture with proper inheritance, engine.run(), and public API (chatto-bridge-rytk) 2026-08-04 16:01:50 +01:00
.beans.yml feat: update chattolib, fix proto generation, add tests and docs (chatto-bridge-6dfy) 2026-08-04 14:00:31 +01:00
.env.example Initial commit: Discord ↔ Chatto bridge bot scaffold 2026-07-14 01:13:28 +01:00
.gitignore Add Dockerfile with pinned CHATTO_REF build arg 2026-10-15 17:54:44 +03:00
Dockerfile Add Dockerfile with pinned CHATTO_REF build arg 2026-10-15 17:54:44 +03:00
LICENSE Initial commit: Discord ↔ Chatto bridge bot scaffold 2026-07-14 01:13:28 +01:00
LICENSING.md Split sources by chat platform: /discord/, /slack/, /chatto_bridge/ 2026-07-14 01:59:27 +01:00
pyproject.toml Fixed connectrpc version, Added error logs in engine.py 2026-10-31 22:02:02 +02:00
README.md Updated README.md (new features, minor corrections) 2026-11-15 06:15:27 +02:00
REUSE.toml Split sources by chat platform: /discord/, /slack/, /chatto_bridge/ 2026-07-14 01:59:27 +01:00

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**: snippet quote 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 link slash 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).

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_posted event 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 as attachment_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.v1 to chatto.core.evt.v1. scripts/generate_pb.sh fetches the full recursive proto tree (surviving directory reshuffles) and pulls the buf/validate + well-known-type dependencies.
  • No version pinning: unlike upstream, no CHATTO_REF build 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 to chatto_bridge.discord at install time, so intra-package imports use the installed name, and ChattoBridgeBot is imported at runtime, not just under TYPE_CHECKING.
  • Namespace collision: chattolib ships its own generated chatto package; the bridge merges its _pb/chatto tree into the existing package's __path__ so chatto.core.evt.v1 resolves at runtime.
  • Encrypted message bodies: Chatto v0.5 reserves the body field on message_posted (text travels per-user-encrypted in a separate message_body event), so the Chatto → Discord direction now fetches the decrypted message through the ConnectRPC API via ChattoClient.get_message instead of reading the NATS payload. Author display names resolve through batch_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**: snippet quotes in Discord.
  • Edits: a persistent message-link table maps bridged messages to their counterparts on both platforms; on_message_edit and Chatto message_edited events 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 with attachment_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 upstream chattocorp/chatto.

See LICENSING.md for the full picture and REUSE.toml for the machine-readable licence map.