90 lines
4.2 KiB
Markdown
90 lines
4.2 KiB
Markdown
# 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
|
|
|
|
1. Create the Telegram group (public link recommended — it's the outsiders'
|
|
door) or use an existing one.
|
|
2. Add **@occupymedia_bot** to the group and **promote it to admin**.
|
|
3. In BotFather: `/setprivacy` → @occupymedia_bot → **Disable** — without this
|
|
the bot cannot read group messages.
|
|
4. 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.
|