# Add Telegram

> Add Telegram as a channel. Use when the user says "add telegram", "connect telegram", "set up telegram bot", or "telegram channel".

- Skill: `ivo-toby/add-telegram` (Agent Skill)
- Install (CLI): `npx get-skill add ivo-toby/add-telegram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivo-toby/add-telegram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ivo-toby (https://skillmd.com/u/ivo-toby)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/ivo-toby/add-telegram

---


# Add Telegram Channel

Walk the user through adding a Telegram bot channel to Talon. One question at a time.

## Phase 1: Pre-flight

Check if a telegram channel already exists:

```bash
npx talonctl list-channels
```

If one exists, ask the user if they want to add another or reconfigure.

## Phase 2: Create the Bot

Ask: **"Do you already have a Telegram bot token?"**

If no, walk them through it:

> 1. Open Telegram and search for **@BotFather**
> 2. Send `/newbot`
> 3. Choose a display name (e.g. "Talon Assistant")
> 4. Choose a username — must end with `bot` (e.g. `talon_assistant_bot`)
> 5. BotFather will reply with a token like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`
> 6. Copy that token

Wait for the user to provide the token. **Never store the actual token in config** — use an env var placeholder.

## Phase 3: Add the Channel

Ask for a channel name (suggest `my-telegram`), then:

```bash
npx talonctl add-channel --name <name> --type telegram
```

Then edit `talond.yaml` to set the config section for this channel:

```yaml
config:
  botToken: ${TELEGRAM_BOT_TOKEN}
  pollingTimeoutSec: 30
```

Tell the user to add to `.env`:

```
TELEGRAM_BOT_TOKEN=<their-actual-token>
```

## Phase 4: Restrict Access (Recommended)

Ask: **"Do you want to restrict the bot to specific chats?"**

If yes, explain how to get chat IDs:

> 1. Start a conversation with your bot in Telegram
> 2. Send any message
> 3. Open `https://api.telegram.org/bot<TOKEN>/getUpdates` in a browser
> 4. Find `"chat":{"id":12345678}` — that's your chat ID
> 5. For groups: add the bot to the group, send a message, check getUpdates again (group IDs are negative numbers like `-1001234567890`)

Then edit the channel config to add:

```yaml
config:
  botToken: ${TELEGRAM_BOT_TOKEN}
  pollingTimeoutSec: 30
  allowedChatIds:
    - "12345678"
```

## Phase 5: Bind a Persona

```bash
npx talonctl list-personas
```

Ask which persona to bind, then:

```bash
npx talonctl bind --persona <name> --channel <channel-name>
```

If no personas exist yet, suggest creating one first.

## Phase 6: Validate

```bash
npx talonctl env-check
npx talonctl doctor
```

Report any issues and help fix them.

## Phase 7: Group Chat Setup

If the user mentions group chats, explain:

> **Group Privacy:** By default, Telegram bots only see messages that @mention them in groups. To let the bot see all messages:
>
> 1. Open @BotFather
> 2. Send `/mybots` and select your bot
> 3. Go to **Bot Settings** > **Group Privacy** > **Turn off**
>
> After changing this, **remove and re-add the bot to the group** for it to take effect.

## Phase 8: Verify

Tell the user:

> 1. Make sure talond is running (or restart it)
> 2. Send a message to the bot in Telegram
> 3. You should get a response within a few seconds

If it doesn't work:

```bash
# Check if token is valid
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"

# Check logs
journalctl --user -u talond -f
```

## Images (optional)

Telegram photos and image-MIME documents are ingested automatically. To let the
bound persona answer what a photo shows it needs exactly two things — existing
personas gain neither on upgrade:

```bash
npx talonctl set-capabilities --persona <persona> --add subagent.invoke:*
```

plus `vision` in that persona's `subagents` list in `talond.yaml` (there is no
`talonctl` command for persona sub-agent assignment). The shipped `vision` manifest
declares `requiredCapabilities: []`, so no image capability is part of an
Inspection. Pixels go only to the `vision` sub-agent; the persona itself stays
text-only.

Separately, `image.read:thread` is an **independent** model-free lookup grant for
the thread's Images and saved Findings (`image_lookup`). It needs no vision
assignment and never calls a model — recommended so the persona can re-read an
existing Finding, but not required for Inspections.

Telegram-specific behaviour worth warning the user about:

- **Photos usually lose EXIF.** Telegram recompresses photos, so GPS and capture
  time are typically gone. When metadata matters, tell the user to send the
  **original as a document** — for a format Talon already accepts (see below); this
  helps but cannot guarantee preservation.
- **HEIC is rejected** (`unsupported_mime`), which matters because iOS photos
  default to it. It must be **converted to JPEG, static PNG, or static WebP before
  sending**. Sending a HEIC as a document does **not** work: an unsupported image
  MIME in a document is rejected as `unsupported_mime` without even being
  downloaded, and it still burns one of the message's upload slots.
- **Albums stay separate messages**, each producing its own Image; a burst is not
  coalesced.
- **Up to 5 images per message** by default (`images.maxPerMessage`); the rest
  are rejected `count_limit` without being downloaded.
- **Polling is sequential.** While an image-bearing message is fetched and
  normalized that connector delivers nothing else — up to roughly 120 seconds,
  affecting every chat on this bot token.
- Normalized files are deleted after `images.retentionHours` (default 24h).
  Image records, GPS/EXIF and saved Findings persist beyond that.

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Bot not responding | Check `TELEGRAM_BOT_TOKEN` in `.env`, restart talond |
| Bot only responds to @mentions in groups | Disable Group Privacy in BotFather (see Phase 7) |
| "Unauthorized" errors in logs | Token is wrong or revoked — get new one from BotFather |
| Bot responds to strangers | Add `allowedChatIds` to config (see Phase 4) |
| Duplicate responses | Check if multiple instances of talond are running |

## Config Reference

```yaml
channels:
  - name: my-telegram
    type: telegram
    config:
      botToken: ${TELEGRAM_BOT_TOKEN}    # Required
      pollingTimeoutSec: 30              # Optional (default: 30)
      allowedChatIds:                    # Optional — restrict to specific chats
        - "12345678"
```

## How It Works

- Talon uses long-polling (`getUpdates`) — no webhook URL or public server needed
- Each Telegram chat maps to one Talon thread
- Of a photo's renditions, the largest one that fits the size limits becomes a
  single Image; the others are not separate Images
- Markdown formatting is auto-converted to Telegram's MarkdownV2
- Typing indicator is shown while the agent processes

