Telegram bridge — connection and admin guide

Status: bridge live on the chat CT (mautrix-telegram, appservice registered with tuwunel). Bot: @occupymedia_bot. This page is the operator + end-user guide.

What it does

Each collective's open room can be attached to a Telegram group. Outsiders talk from Telegram with no Matrix account; collective members answer from Element. Everything in the open room still flows through the archive (shares into the group's files folder, indexed, searchable).

Closed production rooms are never bridged — they are end-to-end encrypted and the bridge has no keys. This is by design.

For collective admins

Create the Telegram group (public link recommended — it's the outsiders' door) or use an existing one.
Add @occupymedia_bot to the group and promote it to admin.
In BotFather: /setprivacy → @occupymedia_bot → Disable — without this the bot cannot read group messages.
From Matrix (Element), in the collective's open room, a bridge admin sends the bridge command to link the room. The bridge bot account (@telegrambot:chat.occupymedia.cc) then relays both ways.

Contribution policy reminder (disclosed at join time): messages and files that outsiders post through the open room are archived into the collective's library the same as member posts. Telegram participants are subject to the same moderation (redaction propagates; archive entries get marked unavailable and links die).

For outsiders (Telegram side)

Join the collective's public Telegram group.
Everything you post is visible to the collective and archived in their public library. Same rules as posting to any public channel of the collective.
You do not need a Matrix account. No account is created on this server for you beyond a relay placeholder.

How it works (for operators)

The bridge is mautrix-telegram on CT 152, compose project occ-chat, service mautrix-telegram (profile bridges), config + database in the occ-chat_mautrix_telegram_data volume.
It registers with tuwunel as an appservice (inline declaration in /opt/occupymedia/tuwunel.toml, [appservice.telegram] — as_token, hs_token, sender_localpart telegrambot, user namespaces for @telegrambot and @telegram_* ghosts).
Telegram API credentials: api_id / api_hash from the operator's my.telegram.org app "OccupyMediaBridge" + the BotFather token for @occupymedia_bot, all in the bridge's config.yaml (mode 600, in the data volume — never in git).
Appservice registration file: /opt/occupymedia/appservices/registration.yaml (mounted read-only into tuwunel at /appservices, loaded via appservice_dir).

Operations

Task	How
Restart bridge	`docker restart occ-chat-mautrix-telegram-1` (CT 152)
Logs	`docker logs -f occ-chat-mautrix-telegram-1`
Config	volume `occ-chat_mautrix_telegram_data` → `config.yaml`
Re-register appservice with tuwunel	admin room: `!admin appservices list` / `register` (or the inline TOML section — both load)
Known-good boot	logs end with the bridge serving on :29317 and no `Configuration error`

Failure modes seen in practice

as_token was not accepted → the appservice registration is not loaded by tuwunel (check the inline section and /appservices mount), or the tokens were regenerated on one side only.
invalid permissions level X → this mautrix generation only accepts relay, commands, user, admin in bridge.permissions — "relaybot" and "full" are not valid.
disk quota exceeded at container start → host kernel keyring quota (LXC+Docker); raised + persisted on the host in /etc/sysctl.d/99-lxc-keys.conf.
oCIS strconv.ParseInt "" on uploads → a client sent a chunked PUT without Content-Length; fixed in the archive bot (buffer + explicit content-length).

Roadmap

Telegram login (userbot) for the operator's own account — richer bridging (history, DMs), at the cost of operating a userbot (ban risk if it behaves spammy). Not enabled; the bot path covers the collective use case.
Per-collective Telegram groups auto-created at collective creation.
Contribution-policy banners posted into bridged groups by the guide bot.

4.2 KiB Raw Permalink Blame History