Looking for the chatbot template? It's now here.

Telegram

Configure the Telegram adapter for bot webhooks and messaging.

Installation

Terminal
pnpm add @chat-adapter/telegram

Usage

The adapter auto-detects TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET_TOKEN, TELEGRAM_BOT_USERNAME, and TELEGRAM_API_BASE_URL from environment variables:

lib/bot.ts
import { Chat } from "chat";
import { createTelegramAdapter } from "@chat-adapter/telegram";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    telegram: createTelegramAdapter(),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post(`You said: ${message.text}`);
});

Webhook route

app/api/webhooks/telegram/route.ts
import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.telegram(request);
}

Configure this URL as your bot webhook in BotFather / Telegram API:

Terminal
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/api/webhooks/telegram",
    "secret_token": "your-secret-token"
  }'

Configuration

All options are auto-detected from environment variables when not provided.

OptionRequiredDescription
botTokenNo*Telegram bot token. Auto-detected from TELEGRAM_BOT_TOKEN
secretTokenNoOptional webhook secret token. Auto-detected from TELEGRAM_WEBHOOK_SECRET_TOKEN
userNameNoBot username used for mention detection. Auto-detected from TELEGRAM_BOT_USERNAME or getMe
apiBaseUrlNoTelegram API base URL. Auto-detected from TELEGRAM_API_BASE_URL
loggerNoLogger instance (defaults to ConsoleLogger("info"))

*botToken is required — either via config or env vars.

Environment variables

.env.local
TELEGRAM_BOT_TOKEN=123456:ABCDEF...
TELEGRAM_WEBHOOK_SECRET_TOKEN=your-webhook-secret
TELEGRAM_BOT_USERNAME=mybot
# Optional (self-hosted API gateway)
TELEGRAM_API_BASE_URL=https://api.telegram.org

Features

FeatureSupported
MentionsYes
Reactions (add/remove)Yes
CardsText fallback + inline keyboard buttons/link buttons
ModalsNo
StreamingPost+Edit fallback
DMsYes
Ephemeral messagesNo
File uploadsSingle file (sendDocument)
Typing indicatorYes
Message historyCached messages seen/sent by the adapter

Notes

  • Telegram does not expose full historical message APIs to bots. fetchMessages / fetchChannelMessages return adapter-cached messages from the current process.
  • listThreads is not available for Telegram chats.
  • Button and LinkButton in card Actions render as inline keyboard buttons.
  • Telegram callback data is limited to 64 bytes. Keep button id/value payloads short.
  • Other rich card elements (images/select menus/radios) render as fallback text only.

On this page

GitHubEdit this page on GitHub