# Telegram Gateway Setup — Common Pitfalls

## First-Time Telegram Setup

When setting up Telegram for the first time, two distinct problems can occur depending on config state:

### Problem: "Unauthorized user" after sending pairing code

**Symptom:** User sends a message in Telegram, gets back "Hi~ I don't recognize you yet! here's your pairing code" — but then replying the code doesn't work, or the user gets "unauthorized" repeatedly.

**Root cause:** The pairing code alone does NOT auto-approve the user. You must explicitly approve via CLI.

**Fix:**
```bash
# See pending pairing requests
hermes pairing list

# Approve a specific code
hermes pairing approve telegram <CODE>

# Approve ALL pending for a user (e.g. if multiple codes issued)
hermes pairing approve telegram <CODE_1>
hermes pairing approve telegram <CODE_2>
```

After approval, the user just sends another message and it will work.

### Problem: "Unauthorized user" with no pairing code offered

**Symptom:** User sends a message, gets immediately rejected as "unauthorized" — no pairing code.

**Root cause:** Allowlist is configured but the user's Telegram ID is not in it.

**Fix — allow specific user:**
```bash
hermes config set telegram.allowed_users "<telegram_id>"
hermes gateway restart
```

**Fix — allow all users (quick setup):**
```bash
echo "GATEWAY_ALLOW_ALL_USERS=true" >> ~/.hermes/.env
hermes gateway restart
```

To find the user's Telegram ID: it's logged as the numeric ID in `journalctl --user -u hermes-gateway` when the unauthorized message arrives.

## Gateway Log Locations

```bash
# systemd service logs (most reliable)
journalctl --user -u hermes-gateway -f

# File fallback
tail -f ~/.hermes/logs/gateway.log
```

Look for `Unauthorized user` to find the numeric Telegram ID of blocked users.

## Telegram Bot Types

- **Bot (e.g. @YourHermesBot)**: Created via @BotFather. Receives messages sent directly to it. Used for direct 1:1 chats.
- **BotFather**: Only for creating/managing bots — NOT involved in pairing or authentication.

Pairing codes go to the bot, not BotFather.