Telegram Setup

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/skills/telegram-setupThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Connect a Telegram bot to the Vellum Assistant gateway with automated webhook registration and credential storage

---
name: telegram-setup
description: Connect a Telegram bot to the Vellum Assistant gateway with automated webhook registration and credential storage
compatibility: "Designed for Vellum personal assistants"
metadata:
  icon: assets/icon.svg
  emoji: "🤖"
  vellum:
    category: "messaging"
    display-name: "Telegram Setup"
    activation-hints:
      - "Telegram bot setup, webhook configuration, or BotFather token"
      - "User wants to connect Telegram to the assistant"
      - "Telegram group, supergroup, or channel messages not arriving"
    avoid-when:
      - "User wants to send/receive Telegram messages (use messaging skill instead)"
---

You are helping your user connect a Telegram bot. The wizard collects the token, the rest of setup runs automatically, and you confirm it worked.

DO NOT use this skill for runtime Telegram operations (sending, replying, reading). That is the separate messaging skill.

## Supported chats

Telegram works in private chats and in groups and supergroups. In a private chat the assistant answers every message. In a group it answers only a message that addresses it: an @mention of the bot's username, a command such as `/summary@botname`, or a reply to one of its posts. Every other group message is dropped on purpose and never reaches the assistant; the gateway log records each drop with the reason `bot_not_mentioned`. Broadcast channels are not supported.

Telegram's privacy mode (on by default) already delivers only mentions, replies, and commands to a bot. The assistant applies the same rule itself, so promoting the bot to admin or turning privacy mode off does not make it answer unaddressed messages.

Tell the user this during setup and in the Step 5 summary. When a group message got no reply, first check that it mentioned the bot or replied to it, before diagnosing webhook or credential failures. Forum topics work: a reply lands in the topic the message was in.

## What happens without you

Saving the token in the wizard triggers all of this:

| Step                                               | Runs                          |
| -------------------------------------------------- | ----------------------------- |
| Validate the token against `getMe`                 | Automatically, on save        |
| Store `telegram.botId` and `telegram.botUsername`  | Automatically, on save        |
| Generate the webhook secret                        | Automatically, on save        |
| Register the platform callback route               | Automatically, on save        |
| Tell Telegram where to send updates (`setWebhook`) | Automatically, after the save |
| Install the bot commands (`setMyCommands`)         | Automatically, after the save |

⚠️ CRITICAL: **Never run `setWebhook`, `setMyCommands`, or `assistant webhooks register` yourself, and never generate the webhook secret.** `reconcileTelegramWebhook` is idempotent and already runs on the credential change the save produces. Doing it by hand races it, which is how a webhook ends up pointing somewhere stale.

Your job is Steps 1 to 5 below: open the wizard, confirm delivery, link the user's identity.

## Step 1: Check existing configuration

⚠️ CRITICAL: **If you got here from a wizard-closed notification, or the user just said they finished setup, go straight to Step 3.** A successful save leaves both credentials in place, so this step would find them and read it as "already configured" at exactly the moment that means the opposite. Stopping there skips the delivery check and the identity verification, which is the failure this flow exists to prevent.

Otherwise, run `assistant credentials list --search telegram` (via the bash tool). Note whether `bot_token` and `webhook_secret` are present.

- **Neither present** → continue to Step 2.
- **Both present** → credentials existing does not mean Telegram works, so
  check before saying so. Run Step 3's `assistant channels get telegram --json`
  and read `webhook_delivery`.
  - **`passed: true`, no `indeterminate`** → already set up and confirmed.
    Offer to show status or reconfigure, and stop here unless the user wants a
    reset.
  - **`passed: true` with `indeterminate: true`** → do NOT stop here. Nothing
    is broken, but nothing is confirmed: the registration record is missing, or
    Telegram was unreachable just now. Stopping would skip both the recovery in
    Step 3 and the identity verification in Step 4. Go to Step 3 and re-check.
  - **`passed: false`** → configured but not delivering. This is what the
    Channels page shows as incomplete, and it is why the user may have asked. Go
    to Step 3 and work the recovery rather than reporting it as already set up.

> ✓ Checkpoint: You named which fields are present before branching. Do not skip the call and guess.

## Step 2: Open the setup wizard

Call `ui_show` with `surface_type: "channel_setup"` and `data: { channel: "telegram" }`. The wizard is non-blocking: the tool returns immediately.

⚠️ CRITICAL: **Tool call first, announcement second, in the same turn.** Do not write any message saying the wizard is open until `ui_show` has returned success earlier in the same turn. A message claiming the wizard is open when the tool was never called shows the user an empty side panel.

After it returns success, tell the user:

> I've opened the Telegram setup wizard in the side panel. It walks you through creating the bot with @BotFather and brings its token back. Telegram works in private chats and in groups. In a group, mention the bot or reply to it to get an answer; broadcast channels are not supported. It'll let me know when you're done, and I'll check Telegram is actually delivering.

**Hand-off notification (phones and narrow windows).** On phone-sized clients setup opens on the Contacts page instead of a side drawer and cannot auto-notify. The client sends a hidden message like `[User action on channel_setup surface: moved the telegram setup to the Contacts page]`. When you receive it:

> It looks 

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/vellum-ai/vellum-assistant
git -C vellum-assistant checkout 19bc86343b63

Works in

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 19bc86343b63

Questions about Telegram Setup

• github.com/vellum-ai/vellum-assistant/tree/main/skills/telegram- — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology