# 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"
```

6. Start the bridge service:

```sh
docker compose up -d mautrix-telegram
```

7. Restart Dendrite to load the new bridge configuration:

```sh
docker compose restart monolith
```

## Verifying the Setup

Check if the bridge is running:

```sh
docker compose logs mautrix-telegram
```

You should see messages indicating the bridge has started successfully. If the configuration files aren't present, the service will remain stopped - this is normal and prevents unnecessary restarts.

## 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.

## Troubleshooting

1. **Bridge Not Starting**
   - Verify that both config.yaml and registration.yaml exist.
   - Check file permissions.
   - Review logs with `docker compose logs mautrix-telegram`.
   - Verify 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.

## Next Steps

- Proceed to set up the [Discord Bridge](../mautrix-discord/README.md).

For more detailed information about bridge features and configuration options, visit the [mautrix-telegram documentation](https://docs.mau.fi/bridges/general/docker-setup.html?bridge=telegram).