@photon-ai/telegram-ts

Typed TypeScript client and Zod schemas for the Telegram Bot API, generated daily from the official documentation.

• Fully typed — every method, request, and response is generated from the live spec.
• Runtime-validated — request bodies and responses are checked against Zod schemas automatically.
• Tree-shakeable — import only the methods you use.
• Universal — runs on Node 18+, Bun, Deno, Cloudflare Workers, and browsers (the fetch client is bundled; zod is the only runtime dependency).
• Versioned to Telegram — the package version mirrors the Bot API version (e.g. 10.0.x ⇒ Bot API 10.0).

Install

npm install @photon-ai/telegram-ts zod
# or: bun add @photon-ai/telegram-ts zod

Usage

Create a client bound to your bot token, then pass it to any method:

import { createTelegramClient, sendMessage, getMe } from "@photon-ai/telegram-ts";

const client = createTelegramClient({ token: process.env.BOT_TOKEN! });

const me = await getMe({ client });
console.log(me.result.username);

const sent = await sendMessage({
  client,
  body: { chat_id: 123456789, text: "Hello from @photon-ai/telegram-ts" },
});
console.log(sent.result.message_id);

Successful responses are returned directly as { ok: true, result } — read .result for the typed payload.

Error handling

When Telegram rejects a request (ok: false), the call throws a typed TelegramApiError:

import { TelegramApiError, sendMessage } from "@photon-ai/telegram-ts";

try {
  await sendMessage({ client, body: { chat_id: 1, text: "hi" } });
} catch (error) {
  if (error instanceof TelegramApiError) {
    console.error(error.errorCode, error.telegramDescription);
    if (error.parameters?.retry_after) {
      // rate limited — back off for error.parameters.retry_after seconds
    }
  }
}

Validating untrusted input

Request and response validation is already wired into every method. For data you receive elsewhere (e.g. raw webhook payloads), the generated Zod schemas are exposed under schemas:

import { schemas, type Update } from "@photon-ai/telegram-ts";

app.post("/webhook", (req, res) => {
  const update = schemas.zUpdate.parse(req.body) as Update;
  // ...handle the validated update
});

Self-hosted Bot API server

const client = createTelegramClient({
  token: process.env.BOT_TOKEN!,
  baseUrl: "https://bot-api.internal.example.com",
});

Custom fetch

const client = createTelegramClient({
  token: process.env.BOT_TOKEN!,
  fetch: myInstrumentedFetch,
});

Versioning

The package version mirrors the Telegram Bot API version: MAJOR.MINOR track the Bot API release, and PATCH covers regeneration and tooling fixes within the same Bot API version. Installing @photon-ai/telegram-ts@10 gives you Bot API 10.x.

License

MIT