# Telegram

Telegram access uses Bot API long polling so users can DM the bot, mention it in a group, or reply to it to query and control devices; photo, voice, and document messages are received as hints but do not replace full vision or voice access.

## Usage Modes

| Mode | Trigger | Notes |
| --- | --- | --- |
| Bot DM | Send text directly to the bot | Good for personal remote status queries and control commands. |
| Group mention | Type `@bot_username` with a message | Good for team collaboration. Group messages are ignored unless the bot is mentioned. |
| Reply to bot | Reply to the bot's previous message | Useful for continuing a group conversation without mentioning the bot every time. |
| Photos, voice, and files | Send a media message, optionally with text | The message enters the channel with a hint. Use dedicated device access capabilities for full vision or voice interactions. |

## Create a Telegram Bot

1. Open the official `@BotFather` in Telegram.
2. Send `/newbot`.
3. Follow the prompts to set bot name and username.
4. Copy the Bot Token.
5. Add the bot to a group if group usage is needed.

## Configure Device Agent

Open **Settings → Channels → Telegram** and fill in:

| Field | `.env` | Description |
| --- | --- | --- |
| Enabled | `TELEGRAM_ENABLED` | Starts the Telegram channel |
| Bot Token | `TELEGRAM_BOT_TOKEN` | Token generated by `@BotFather` |
| Allow list | `TELEGRAM_ALLOW_FROM` | Optional numeric Telegram user ID allow list |

You can also configure it in `.env`:

```bash
TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=123456:ABC-...
TELEGRAM_ALLOW_FROM=123456789,987654321
```

Restart the service after saving.

## Verify Access

1. Confirm the service has restarted.
2. Check logs for `Telegram: enabled` and `Bot started (long polling)`.
3. Send a DM to the bot.
4. Mention the bot in a group, or reply to a bot message.
5. If the allow list is enabled, make sure the sender numeric ID is included.

In groups, messages are ignored unless the bot is mentioned or the message replies to the bot.

## Checks

- No DM response: confirm the Bot Token is correct and the service can reach Telegram Bot API.
- No group response: mention the bot or reply to a bot message.
- Allow list blocks messages: use the numeric Telegram user ID.