# Telegram Gateway Setup

Complete workflow for configuring and starting the Telegram messaging gateway in Hermes Agent.

## Prerequisites

- Bot token from [@BotFather](https://t.me/BotFather)
- User ID(s) who are allowed to communicate with the bot

## Step 1: Store Credentials in `.env`

```
TELEGRAM_BOT_TOKEN=<your-bot-token>
TELEGRAM_ALLOWED_USERS=<user-id-1>,<user-id-2>,...
TELEGRAM_HOME_CHANNEL=<default-chat-id>
```

Example:
```
TELEGRAM_BOT_TOKEN=123456:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_ALLOWED_USERS=123456789
TELEGRAM_HOME_CHANNEL=123456789
```

## Step 2: Configure `config.yaml`

Set the following values in `~/.hermes/config.yaml`:

```yaml
gateway:
  enabled: true
  platform: telegram

telegram:
  enabled: true
  allowed_users:
    - "123456789"
  home_channel: "123456789"
  reactions: false
  channel_prompts: {}
```

## Step 3: Install and Start the Gateway Service

```bash
# Install as systemd user service
hermes gateway install

# Start the service
hermes gateway start

# Check status
hermes gateway status
```

## Step 4: Verify Connection

Check logs:
```bash
cat ~/.hermes/logs/gateway.log | grep -i telegram
```

Expected output:
```
INFO gateway.platforms.telegram: [Telegram] Connected to Telegram (polling mode)
INFO gateway.run: ✓ telegram connected
```

## Troubleshooting

### Gateway not connecting
- Verify the bot token in `.env` is correct
- Check that `TELEGRAM_BOT_TOKEN` is set (not just in config.yaml)
- Restart the gateway: `hermes gateway restart`

### Messages not received
- Verify `TELEGRAM_ALLOWED_USERS` contains your user ID
- Check `journalctl --user -u hermes-gateway -n 50` for errors
- Ensure systemd linger is enabled: `loginctl enable-linger $USER`

### Gateway dies on logout
- Enable linger: `sudo loginctl enable-linger $USER`
- Or run in foreground: `hermes gateway run`

### Port conflicts
- The gateway uses polling mode by default (no port needed)
- No port conflicts possible with polling mode