From 572e276db93a6021c9c4e33b89cf2ad96fffb3f6 Mon Sep 17 00:00:00 2001
From: Roger Gonzalez <roger@rogs.me>
Date: Wed, 27 Nov 2024 17:35:26 -0300
Subject: [PATCH] Add Telegram bridge configuration guide to README

---
 .gitignore                        |   3 +
 config/mautrix-telegram/README.md | 148 +++++++++++++++++++++++++++++-
 config/mautrix-whatsapp/README.md |   2 +-
 3 files changed, 151 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index fa9e3d0..f5a0fb4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,6 @@ config/dendrite/
 
 # Mautrix-Whatsapp config
 config/mautrix-whatsapp/*.yaml
+
+# Mautrix-Telegram config
+config/mautrix-telegram/*.yaml
diff --git a/config/mautrix-telegram/README.md b/config/mautrix-telegram/README.md
index 4640904..8d580b5 100644
--- a/config/mautrix-telegram/README.md
+++ b/config/mautrix-telegram/README.md
@@ -1 +1,147 @@
-# TODO
+# Telegram Bridge Setup Guide
+
+This guide will help you set up the Telegram bridge for your Dendrite Matrix server.
+
+## Prerequisites
+
+Before starting, ensure that:
+- Dendrite is properly configured and running.
+- The `telegram` database was created during the initial setup.
+- You have your domain name ready.
+- You have your [Telegram API credentials](#obtaining-telegram-api-credentials) (we'll cover this below).
+
+## Obtaining Telegram API Credentials
+
+Before configuring the bridge, you'll need to obtain API credentials from Telegram:
+
+1. Visit [my.telegram.org](https://my.telegram.org) and log in.
+2. Go to "API development tools".
+3. Create a new application if you haven't already.
+4. Note down your `api_id` and `api_hash` - you'll need these later.
+
+## Setup Steps
+
+1. Navigate to the Telegram configuration directory:
+
+```sh
+cd config/mautrix-telegram
+```
+
+2. Generate the initial configuration file:
+
+```sh
+docker run --rm -v `pwd`:/data:z dock.mau.dev/mautrix/telegram
+```
+
+3. Edit the generated `config.yaml` file. You may need administrative privileges (sudo) to edit this file.
+
+### Required Configuration Changes
+
+Make the following modifications to your `config.yaml`:
+
+#### Homeserver Settings
+```yaml
+homeserver:
+    address: http://monolith:8008  # Internal Docker network address
+    domain: your.domain.com        # Replace with your actual domain
+```
+
+#### Appservice Settings
+```yaml
+appservice:
+    address: http://telegram:29317  # Internal bridge address
+    hostname: 0.0.0.0              # Listen on all interfaces
+```
+
+#### Bridge Settings
+```yaml
+bridge:
+    permissions:
+        '*': relaybot
+        public.your.domain.com: user     # Replace with your domain
+        your.domain.com: full
+        "@yourusername:your.domain.com": admin  # Replace with your Matrix ID
+    
+    # Add your Telegram API credentials
+telegram:
+    api_id: 123456      # Replace with your api_id
+    api_hash: "abcdef"  # Replace with your api_hash
+```
+
+#### Database Connection
+Update the database URI to use the Telegram-specific database:
+
+```yaml
+# Original:
+# postgres://dendrite:password@postgres/dendrite?sslmode=disable
+
+# Modified (note 'telegram' database name):
+postgres://dendrite:password@postgres/telegram?sslmode=disable
+```
+
+4. Generate the registration file:
+
+```sh
+docker run --rm -v `pwd`:/data:z dock.mau.dev/mautrix/telegram
+```
+
+5. Configure Dendrite to use the Telegram bridge by editing `config/dendrite/dendrite.yaml`:
+
+```yaml
+app_service_api:
+    config_files: 
+        - "/etc/telegram/registration.yaml"
+```
+
+## Starting the Bridge
+
+1. Start the Telegram bridge service:
+
+```sh
+docker compose up -d mautrix-telegram
+```
+
+2. Restart Dendrite to load the new bridge configuration:
+
+```sh
+docker compose restart monolith
+```
+
+## Verifying the Setup
+
+1. Check if the bridge is running:
+
+```sh
+docker compose logs mautrix-telegram
+```
+
+You should see messages indicating the bridge has started successfully.
+
+## Using the Bridge
+
+1. Start a chat with `@telegrambot:your.domain.com` in your Matrix client
+2. Send the command `!tg login` to start the login process
+3. Follow the bot's instructions to:
+   - Provide your phone number
+   - Enter the verification code sent to your Telegram app
+   - Complete two-factor authentication if enabled
+4. Proceed to set up the [Discord Bridge](../mautrix-discord/README.md)
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Bridge Not Starting**
+   - Check logs: `docker compose logs mautrix-telegram`.
+   - Verify database connection string.
+   - Ensure API credentials are correct.
+
+2. **Login Issues**
+   - Confirm your phone number format (including country code).
+   - Check if your account has 2FA enabled.
+   - Verify API credentials are correct.
+
+3. **Message Delivery Problems**
+   - Verify bridge service is running.
+   - Check bridge permissions in config.
+   - Ensure Telegram session is still valid.
diff --git a/config/mautrix-whatsapp/README.md b/config/mautrix-whatsapp/README.md
index c2446a9..25e65f5 100644
--- a/config/mautrix-whatsapp/README.md
+++ b/config/mautrix-whatsapp/README.md
@@ -101,7 +101,7 @@ docker compose logs mautrix-whatsapp
 
 You should see messages indicating the bridge has started successfully.
 
-## Next Steps
+## Using the Bridge
 
 - Set up your WhatsApp account in Matrix by starting a chat with `@whatsappbot:your.domain.com`.
 - Follow the bot's instructions to link your WhatsApp account.