# Telegram Webhook Agent

> Let Telegram messages trigger agent responses via webhooks

- Skill: `loopyluci/telegram-webhook-agent` (Agent Skill)
- Install (CLI): `npx skillmds@latest add loopyluci/telegram-webhook-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/loopyluci/telegram-webhook-agent/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: LoopyLuci (https://skillmd.com/u/loopyluci)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/loopyluci/telegram-webhook-agent

---


# Telegram Webhook Agent

Set up a webhook so incoming Telegram messages trigger the agent. This enables bidirectional communication — the user messages the agent on Telegram and it responds.

## Architecture

```
User → Telegram → Webhook URL → Hermes Gateway → Agent Processes → Reply
```

## Setup

### 1. Create a Telegram Bot

```bash
# Talk to @BotFather on Telegram
/newbot
# Name: MyAgent
# Username: MyAgent_bot
# Save the token: 123456:ABCdef...
```

### 2. Configure Hermes Gateway

Set the bot token and webhook route in `config.yaml`:

```yaml
gateway:
  telegram:
    bot_token: "123456:ABCdef..."   # From BotFather
    webhook_url: "https://your-domain.com/webhook/telegram"
    allowed_user_ids:
      - 1350214376  # Your Telegram user ID (get from @userinfobot)
```

Or via CLI:
```bash
hermes config set gateway.telegram.bot_token "123456:ABCdef..."
hermes config set gateway.telegram.webhook_url "https://your-domain.com/webhook/telegram"
hermes config set gateway.telegram.allowed_user_ids "[1350214376]"
```

### 3. Set Up the Webhook

```bash
# Register webhook with Telegram
curl -F "url=https://your-domain.com/webhook/telegram" \
     "https://api.telegram.org/bot<TOKEN>/setWebhook"

# Verify
curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"
```

### 4. Expose Local Server (Dev)

Use ngrok for development:

```bash
ngrok http 8080
# Copy the https://xxxx.ngrok.io URL
# Set webhook_url to https://xxxx.ngrok.io/webhook/telegram
```

## How Replies Work

1. User sends a message to the bot on Telegram
2. Telegram POSTs the update to the webhook URL
3. Hermes gateway receives it, creates a session
4. Agent processes and responds
5. Response is delivered back to the Telegram chat

## Filtering

Restrict which users can interact:

```yaml
gateway.telegram.allowed_user_ids:
  - 1350214376   # Only this user
  # - 987654321  # Add more user IDs
```

Block unknown users silently (no error message sent).

## Security

- Keep bot tokens secret — anyone with the token controls your bot
- Use `allowed_user_ids` to prevent abuse
- Set `webhook_url` to HTTPS only (Telegram rejects HTTP)
- Rotate tokens if compromised via `BotFather → /revoke`

## Troubleshooting

**Webhook not responding** — check ngrok/tunnel is running and the URL matches.

**Messages not arriving** — verify `getWebhookInfo` returns `has_custom_certificate: false` and `pending_update_count: 0`.

**Wrong user responding** — the gateway checks `allowed_user_ids` before processing.