# Telegram Setup Guide

## Creating a Bot

1. Open Telegram and search for **@BotFather**
2. Start a chat and send `/newbot`
3. Follow the prompts — choose a display name and a username (must end in `bot`)
4. BotFather replies with a **bot token** (a long string like `123456:ABC-DEF...`)
5. Copy the token — you'll paste it into the admin chat

## Connecting the Bot

1. Tell the admin agent you want to connect a Telegram bot
2. Find the **Telegram** row and click **Connect** (or open settings if already connected)
3. Paste the bot token from BotFather
4. The system probes the token to verify it — you'll see the bot's username confirmed
5. Choose whether this is an **admin bot** or a **public bot** (see below)
6. If it's a public bot, choose a DM policy (who can message it)
7. Click **Save & Connect**

## Admin Bot vs Public Bot

Each Telegram bot has an **Admin routing** toggle:

- **Admin bot** (toggle ON): Only users with admin bindings can message this bot. Everyone else is silently denied. Messages route to the admin agent. No DM policy applies — it's admin-only by design.
- **Public bot** (toggle OFF): DM policy applies to everyone equally, including admins. Messages route to the public agent. Use this for customer-facing bots.

A common setup is two bots: one admin bot for the business owner, one public bot for customers.

## Finding Your Telegram User ID

Admin bindings require your **numeric Telegram user ID** — not your username. Usernames can be changed or claimed by someone else, so they are not safe for admin access.

To find your user ID:

1. Open Telegram and search for **@userinfobot**
2. Start the chat and send `/start`
3. The bot instantly replies with your numeric ID (e.g. `123456789`), plus your name and language
4. Use this numeric ID when setting up admin bindings

## DM Policy Options (Public Bots Only)

| Policy | Behaviour |
|--------|-----------|
| **Respond to everyone** | Any Telegram user can message the bot and get a response |
| **Require approval** | Unknown senders receive a pairing code; an admin must approve them |
| **Whitelist only** | Only users in the allowlist can message the bot |
| **Disabled** | The bot ignores all DMs |

"Require approval" (pairing) is the default and recommended for most setups — it lets you control who talks to the bot without pre-configuring an allowlist.
