AI Starter Package
Guides/Telegram Setup

Telegram Bot Setup for AI Agents

Connect your AI brain to Telegram so you can send tasks, receive updates, and interact with your agent from any device — without opening a terminal.

TelegramBot APIFree API

Why Connect AI Agents to Telegram?

Always-on mobile access

Send tasks to your AI agent from anywhere, get responses instantly in the app you already use.

Rich message types

Telegram supports text, files, images, voice, buttons, and inline keyboards — richer than SMS or email.

Group channels

Run a private group where your AI agent participates alongside your team, answering questions and logging updates.

Webhook-friendly

Telegram's webhook API is simple, well-documented, and free — no paid tier required.

Step 1 — Create a Bot via BotFather

1

Open BotFather

Search for @BotFather in Telegram. This is the official bot that manages all Telegram bots. Start a conversation and send:

/newbot
2

Name Your Bot

BotFather will ask for a display name and a username. The username must end in bot. Example: MyAIBrainBot.

3

Save the Bot Token

BotFather will reply with your token — a string like 1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Store it immediately in your environment file:

# .env.local
TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF1234...
TELEGRAM_SECRET_HEADER=your-random-secret-string
Keep this secret
Anyone with your bot token can send messages as your bot. Never commit it to source control.

Webhook vs Polling Architecture

Webhook

Telegram pushes updates to your server URL in real time

Pros
  • +Near-instant message delivery
  • +No idle resource usage
  • +Scales to many users
Cons
  • –Requires a public HTTPS URL
  • –Needs SSL certificate
Best for: Production deployments with a server or Vercel/Railway endpoint

Polling

Your bot repeatedly asks Telegram for new messages

Pros
  • +Works on localhost
  • +No public URL needed
  • +Easy to debug
Cons
  • –Adds latency (poll interval)
  • –Wastes resources when idle
Best for: Local development and testing

Connecting to Claude Code via Webhook

The simplest architecture: a Next.js API route receives Telegram messages, passes them to Claude Code via the Anthropic API, and sends the response back.

// src/app/api/telegram/route.ts
export async function POST(req: Request) {
const body = await req.json();
const message = body.message?.text;
const chatId = body.message?.chat?.id;
// Validate secret header
const secret = req.headers.get("X-Telegram-Bot-Api-Secret-Token");
if (secret !== process.env.TELEGRAM_SECRET_HEADER) {
return new Response("Unauthorized", { status: 401 });
}
// Send to Claude, return response
// ... anthropic.messages.create(...)
}

Security Considerations

Store token in environment variables
Never hardcode the bot token in source code. Use TELEGRAM_BOT_TOKEN in .env.
Validate the secret header
Telegram webhook requests include a X-Telegram-Bot-Api-Secret-Token header. Verify it on every request.
Whitelist allowed user IDs
Only respond to messages from your own Telegram user ID. Reject all others.
Rate-limit responses
Add a simple rate limiter to prevent your AI agent from being spammed into expensive API calls.
Log all interactions
Write every message and response to a log file. This is your audit trail if something goes wrong.

Get Your Agent Connected in 48 Hours

Our managed agent packages include Telegram integration — webhook setup, Claude routing, security hardening, and a private bot configured to your workflow.

See PricingDiscord Setup Instead