xmpp-server-prosody/references/telegram-bridge-slidge.md

XMPP↔Telegram bridge via Slidge (Etap 4, nixg.ru) — decision & planning notes

Date: 2026-08-29. State: PLANNED, not yet implemented end-to-end. Verify component details against slidge docs (docs.slidge.im) and the image's env before deploying.

Decision recap (user-driven)

• Matterbridge (XMPP MUC ↔ Telegram-group mirror, one binary, connects as a regular XMPP client) — proposed and REJECTED by the user ("вариант А мне не интересен"). It mirrors rooms/groups only, no contact roster.
• mautrix-telegram — WRONG TOOL for XMPP: it is a Matrix↔Telegram puppeting bridge requiring a Matrix homeserver (Synapse/Dendrite). It cannot attach to Prosody. Do not propose it again for this project.
• Slidge (https://slidge.im) — correct class of tool: an XMPP transport/gateway that maps a foreign network's contacts into virtual XMPP JIDs.

How Slidge attaches (expected shape)

• Implements XEP-0114 (external components). Connects to Prosody's component port, default 5347.
• Prosody side — GLOBAL section of prosody.cfg.lua (mod_component is bundled in the stock prosody/prosody image; present at /usr/lib/prosody/modules/mod_component.lua):

  component_ports = { 5347 }
  component_secrets = { ["telegram.nixg.ru"] = "<random-secret>" }
  

  The old commented line -- Component "telegram.chat.nixg.ru" "xmpp_component" in /opt/icq/config/prosody.cfg.lua was wrong on two counts: module name xmpp_component doesn't exist, and a Component stanza is not needed for a self-connecting external component — component_ports/secrets activate it.
• Container: ghcr.io/slidge/slidge-telegram (or build from ghcr.io/slidge/slidge + telegram plugin). Must share the prosody docker network (icq_default) to reach icq-prosody:5347. Volume for the Telethon session (./slidge/data), config via env or slidge.toml.
• Telegram side: login with a user account via Telethon/MTProto (NOT a bot). Contact mapping: +79123456789@telegram.nixg.ru.
• Onboarding: XMPP user contacts telegram@telegram.nixg.ru → Slidge walks through pairing (QR/code) → roster fills with Telegram contacts. Full feature set is best in native clients (Gajim/Dino/Conversations); Converse web works basically (roster) but is limited.

Pitfalls / risks

• ⚠️ MTProto user login violates Telegram ToS → account ban risk. Require a dedicated spare number/account, never the user's main one. State this explicitly to the user before proceeding.
• Port 5347 must stay inside the docker network — do NOT expose via iptables/DNAT or Caddy.
• No end-to-end encryption through the bridge (Slidge may do OMEMO on the XMPP leg; Telegram leg has its own crypto).
• Plan file (full task breakdown): /opt/hermes/.hermes/plans/2026-08-29_085200-telegram-bridge.md