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

Open BotFather

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

/newbot

Name Your Bot

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

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 Pricing Discord Setup Instead

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

Open BotFather

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

/newbot

Name Your Bot

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

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.