Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
/**
* Telegram Bot API update webhook + Mini App proxy.
*
* Two callers share this endpoint:
* 1. Telegram POSTs bot updates here when the bot's webhook is registered
* to {publicBase}/api/telegram/update (shape: TelegramUpdate).
* 2. The Mini App frontend POSTs { initData, message } directly; the
* initData HMAC is verified server-side before proxying.
*
* The route:
* 1. Rejects when TELEGRAM_BOT_TOKEN is unset (never silently no-op).
* 2. Verifies initData when present (Mini App path).
* 3. Handles /start (returns the Mini App deep link) and everything else
* as a chat prompt proxied through the OmniRoute pipeline.
*/
import { timingSafeEqual } from "node:crypto";
import { NextResponse } from "next/server";
import { z } from "zod";
import { validateBody, isValidationFailure } from "@/shared/validation/helpers";
import type { TelegramUpdate } from "@/lib/telegram/botApi";
import { extractChatMessage, sendTelegramMessage } from "@/lib/telegram/botApi";
import {
getTelegramBotToken,
getTelegramWebhookSecret,
isTelegramEnabled,
isTelegramWebhookSecretConfigured,
} from "@/lib/telegram/config";
import { verifyInitData, parseInitData } from "@/lib/telegram/initData";
import { proxyChat } from "@/lib/telegram/chatProxy";
import { formatTelegramGatewayError } from "@/lib/telegram/errorMessage";
import { resolveOmniRouteBaseUrl } from "@/shared/utils/resolveOmniRouteBaseUrl";
/**
* Telegram update bodies are open-ended (many update types, evolving schema),
* so validation is deliberately loose: a JSON object with optional string
* fields for the two paths we handle. The initData HMAC check (Mini App path)
* and bot-token gate (webhook path) provide the real security.
*/
const telegramBodySchema = z
.object({
initData: z.string().optional(),
// `message` is a STRING on the Mini App path ({ initData, message }) and an
// OBJECT on the webhook path (a Telegram update). Constraining it to a
// string rejected every real webhook delivery with 400 before any auth or
// routing ran, so accept either shape here and let each branch validate the
// shape it actually needs.
message: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
update_id: z.number().optional(),
// allow unknown update fields
})
.passthrough();
/** Pull the numeric Telegram user id out of a verified initData string. */
function extractInitDataUserId(initData: string): number {
try {
const parsed = parseInitData(initData);
const userRaw = parsed["user"];
if (userRaw) {
const user = JSON.parse(userRaw) as { id?: number };
if (typeof user.id === "number" && user.id > 0) return user.id;
}
} catch {
// fall through to default
}
return 0;
}
function buildMiniAppLink(botUsername?: string): string {
const base = resolveOmniRouteBaseUrl();
// Deep link: t.me/<bot>?startapp= opens the Mini App with start_param.
const bot = botUsername || "YOUR_BOT";
return `https://t.me/${bot}?startapp=miniapp`;
}
const START_HELP =
"👋 Welcome! This bot bridges Telegram and your OmniRoute gateway.\n\n" +
"• Send any message and I'll route it through your configured models.\n" +
"• Open the Mini App for a full chat UI.";
export async function POST(request: Request) {
if (!isTelegramEnabled()) {
return NextResponse.json({ ok: false, error: "Telegram not configured" }, { status: 503 });
}
let rawBody: unknown;
try {
rawBody = await request.json();
} catch {
return NextResponse.json({ ok: false, error: "Invalid JSON" }, { status: 400 });
}
const validation = validateBody(telegramBodySchema, rawBody);
if (isValidationFailure(validation)) {
return NextResponse.json({ ok: false, error: "Invalid request" }, { status: 400 });
}
const body = validation.data as Record<string, unknown>;
// ── Mini App direct path: { initData, message } ──────────────────────────
const initData = typeof body.initData === "string" ? body.initData : "";
if (initData) {
const botToken = getTelegramBotToken();
if (!verifyInitData(initData, botToken)) {
return NextResponse.json({ ok: false, error: "Invalid initData signature" }, { status: 401 });
}
const message = typeof body.message === "string" ? body.message : "";
if (!message.trim()) {
return NextResponse.json({ ok: false, error: "message is required" }, { status: 400 });
}
// Resolve the Telegram user id from the verified initData for key mapping.
const telegramUserId = extractInitDataUserId(initData);
// Proxy synchronously and return the reply (Mini App awaits the fetch).
const reply = await proxyChat(telegramUserId, message);
return NextResponse.json({ ok: true, reply: reply || "⚠️ Empty gateway response." });
}
// ── Bot webhook path: TelegramUpdate ─────────────────────────────────────
// Unlike the Mini App branch above (which verifies the initData HMAC), a
// webhook body carries no proof of origin: `chat.id` is attacker-chosen and
// reaches proxyChat(), which mints a real API key and spends upstream quota.
// Telegram's `secret_token` echo is the only authentication available here.
if (!isTelegramWebhookSecretConfigured()) {
return NextResponse.json(
{ ok: false, error: "Telegram webhook secret not configured" },
{ status: 503 }
);
}
const presentedSecret = request.headers.get("x-telegram-bot-api-secret-token") || "";
if (!webhookSecretMatches(presentedSecret, getTelegramWebhookSecret())) {
return NextResponse.json({ ok: false, error: "Unauthorized" }, { status: 401 });
}
const update = body as unknown as TelegramUpdate;
const chat = extractChatMessage(update);
if (!chat) {
// Non-message updates (callback_query etc.) — acknowledge silently.
return NextResponse.json({ ok: true });
}
// Fire-and-forget reply: Telegram retries on 5xx, so always 200 after
// enqueueing the reply. Keep the handler non-blocking.
void handleAndReply(chat.chatId, chat.text, chat.messageId);
return NextResponse.json({ ok: true });
}
/**
* Constant-time comparison of the presented webhook secret against the
* configured one. A plain `===` short-circuits on the first differing byte and
* leaks the shared-prefix length through response timing; `timingSafeEqual`
* does not. It requires equal-length buffers, so a length mismatch is rejected
* up front (the length itself is not secret).
*
* Exported as a test seam only — not part of the route contract.
*/
export function webhookSecretMatches(presented: string, expected: string): boolean {
const a = Buffer.from(presented);
const b = Buffer.from(expected);
if (a.length !== b.length) return false;
return timingSafeEqual(a, b);
}
async function handleAndReply(chatId: number, text: string, messageId?: number): Promise<void> {
try {
const trimmed = text.trim();
if (trimmed === "/start" || trimmed === "/start@") {
const link = buildMiniAppLink();
await sendTelegramMessage({
chat_id: chatId,
text: `${START_HELP}\n\n🚀 Open the Mini App: ${link}`,
parse_mode: "Markdown",
});
return;
}
// Strip bot-command prefixes that aren't /start (e.g. /help).
if (trimmed.startsWith("/")) {
await sendTelegramMessage({
chat_id: chatId,
text: "Unsupported command. Try /start or just send a message.",
reply_to_message_id: messageId,
});
return;
}
const answer = await proxyChat(chatId, trimmed);
const reply = answer || "⚠️ The gateway returned an empty response.";
await sendTelegramMessage({
chat_id: chatId,
text: reply.length > 4096 ? `${reply.slice(0, 4090)}…` : reply,
parse_mode: "Markdown",
reply_to_message_id: messageId,
});
} catch (err) {
try {
await sendTelegramMessage({
chat_id: chatId,
text: formatTelegramGatewayError(err),
});
} catch {
// Nothing more we can do — the reply channel is down.
}
}
}