# Telegram Bot Setup Guide

This guide covers creating and configuring a Telegram bot for kugetsu Phase 3 (Chat Integration).

## Create a Telegram Bot

### Step 1: Start BotFather

1. Open Telegram and search for **@BotFather**
2. Click **Start** to begin

### Step 2: Create New Bot

Send the command:
```
/newbot
```

BotFather will ask for:
1. **Name** - A human-readable name (e.g., "Kugetsu Bot")
2. **Username** - Must end in `bot` (e.g., `kugetsu_agent_bot`)

### Step 3: Save Your Token

BotFather will give you a token like:
```
1234567890:ABCdefGHIjklMNOpqrSTUvwxyz123456789
```

**⚠️ Keep this token secret!** It allows access to your bot.

### Step 4: Set Bot Description (Optional)

```
/setdescription
```
Enter a description like: "Kugetsu Chat Agent - Interact with your agent via Telegram"

### Step 5: Set Bot Picture (Optional)

```
/setuserpic
```
Upload a profile picture for the bot.

---

## Configure Hermes for Telegram

*(This section will be expanded when Phase 3 implementation begins)*

### Required Environment Variables

```bash
TELEGRAM_BOT_TOKEN="your-bot-token-here"
TELEGRAM_API_ID="your-api-id"  # From https://my.telegram.org
TELEGRAM_API_HASH="your-api-hash"  # From https://my.telegram.org
```

### Hermes Configuration

```yaml
# hermes/config.yaml
telegram:
  enabled: true
  bot_token: ${TELEGRAM_BOT_TOKEN}
```

---

## Security Notes

- **Never commit bot tokens** to version control
- Use environment variables or secrets management
- Rotate tokens if compromised: `/revoke` in BotFather

---

## Troubleshooting

### Bot Not Responding

1. Check bot token is correct
2. Verify Hermes is running and connected
3. Check bot has not been blocked by user

### "Bot was blocked by the user"

The user has blocked your bot. They need to unblock it or start a new chat.

---

## See Also

- [Phase 3: Chat Integration (Issue #19)](../issues/19)
- [kugetsu Chat Architecture](kugetsu-chat.md)