telegram-api-fetch

TypeScript type definitions and client for the Telegram Bot API using Zod schemas.

Features

• 🔒 Type-Safe: Full TypeScript support with Zod schema validation
• 🚀 Modern: Built with Bun.sh and ESM modules
• 📦 Lightweight: Zero dependencies except Zod
• 🎯 Focused: Currently supports webhook validation and essential bot methods
• 🔄 Validated: Automatic runtime validation of incoming webhook updates
• 🎨 Keyboards: Full support for InlineKeyboardMarkup and ReplyKeyboardMarkup

Installation

# Using Bun (recommended)
bun add telegram-api-fetch

# Using npm
npm install telegram-api-fetch

# Using yarn
yarn add telegram-api-fetch

# Using pnpm
pnpm add telegram-api-fetch

Quick Start

Creating a Bot Client

import { TelegramBot } from 'telegram-api-fetch'

const bot = new TelegramBot({
  botToken: process.env.TELEGRAM_BOT_TOKEN!
})

Setting Up a Webhook

await bot.setWebhook({
  url: 'https://your-domain.com/webhook',
  secret_token: 'your-secret-token',
  allowed_updates: ['message', 'callback_query']
})

Sending Messages

// Simple text message
await bot.sendMessage({
  chat_id: 123456789,
  text: 'Hello from Telegram Bot API!'
})

// Message with inline keyboard
await bot.sendMessage({
  chat_id: 123456789,
  text: 'Choose an option:',
  reply_markup: {
    inline_keyboard: [
      [
        { text: '👍 Option 1', callback_data: 'opt_1' },
        { text: '👎 Option 2', callback_data: 'opt_2' }
      ]
    ]
  }
})

// Message with reply keyboard
await bot.sendMessage({
  chat_id: 123456789,
  text: 'Select from keyboard:',
  reply_markup: {
    keyboard: [
      [{ text: 'Button 1' }, { text: 'Button 2' }],
      [{ text: 'Share Contact', request_contact: true }]
    ],
    resize_keyboard: true,
    one_time_keyboard: true
  }
})

Sending Photos

// Send photo by URL
await bot.sendPhoto({
  chat_id: 123456789,
  photo: 'https://example.com/image.jpg',
  caption: 'Check this out!'
})

// Send photo with inline keyboard
await bot.sendPhoto({
  chat_id: 123456789,
  photo: 'https://example.com/image.jpg',
  caption: 'Do you like it?',
  reply_markup: {
    inline_keyboard: [
      [
        { text: '👍 Like', callback_data: 'like' },
        { text: '👎 Dislike', callback_data: 'dislike' }
      ]
    ]
  }
})

// Send photo by file_id
await bot.sendPhoto({
  chat_id: 123456789,
  photo: 'AgACAgIAAxkBAAIBY2...'
})

Validating Webhook Updates

import { UpdateSchema, type Update } from 'telegram-api-fetch'

// In your webhook handler
app.post('/webhook', async (req, res) => {
  // Verify secret token (recommended)
  const secretToken = req.headers['x-telegram-bot-api-secret-token']
  if (secretToken !== 'your-secret-token') {
    return res.sendStatus(401)
  }

  // Validate and parse the update
  const update: Update = UpdateSchema.parse(req.body)

  // Handle text messages
  if (update.message?.text) {
    const chatId = update.message.chat.id
    const text = update.message.text

    await bot.sendMessage({
      chat_id: chatId,
      text: `You said: ${text}`
    })
  }

  // Handle callback queries from inline keyboard buttons
  if (update.callback_query) {
    const query = update.callback_query
    const data = query.data
    const chatId = query.message?.chat.id
    
    if (chatId && data) {
      await bot.sendMessage({
        chat_id: chatId,
        text: `You selected: ${data}`
      })
    }
  }

  res.sendStatus(200)
})

Handling Callback Queries

Callback queries are triggered when users click inline keyboard buttons:

import { type CallbackQuery } from 'telegram-api-fetch'

async function handleCallbackQuery(query: CallbackQuery) {
  const chatId = query.message?.chat.id
  if (!chatId || !query.data) return

  // Parse callback data
  if (query.data.startsWith('vehicle_')) {
    const vehicleId = query.data.split('_')[1]
    
    await bot.sendMessage({
      chat_id: chatId,
      text: `🚗 Vehicle ${vehicleId} selected`,
      reply_markup: {
        inline_keyboard: [
          [
            { text: '✅ Start Check', callback_data: `check_${vehicleId}` },
            { text: '🔙 Back', callback_data: 'list_vehicles' }
          ]
        ]
      }
    })
  }
}

// In your webhook handler
if (update.callback_query) {
  await handleCallbackQuery(update.callback_query)
}

See the complete Callback Queries Guide for:

• Callback data patterns and best practices
• Multi-step workflows
• Type-safe callback handling
• Real-world examples based on actual use cases

API Reference

TelegramBot

Main client class for interacting with the Telegram Bot API.

Constructor

new TelegramBot(config: TelegramConfig)

Config Options:

• botToken (string, required): Your bot token from @BotFather
• baseUrl (string, optional): API base URL (default: https://api.telegram.org)
• timeout (number, optional): Request timeout in milliseconds (default: 30000)

Methods

setWebhook(params: SetWebhookParams): Promise<boolean>

Configure a webhook to receive updates.

Parameters:

• url (string): HTTPS URL to send updates to
• secret_token (string, optional): Secret token for webhook verification
• allowed_updates (string[], optional): List of update types to receive
• max_connections (number, optional): Maximum simultaneous connections
• drop_pending_updates (boolean, optional): Drop all pending updates

sendMessage(params: SendMessageParams): Promise<TelegramMessage>

Send a text message.

Parameters:

• chat_id (number | string): Target chat ID or username
• text (string): Message text
• parse_mode (string, optional): Parse mode (Markdown, HTML, MarkdownV2)
• reply_markup (object, optional): Inline or reply keyboard
• reply_to_message_id (number, optional): ID of message to reply to
• disable_notification (boolean, optional): Send silently
• And more...

sendPhoto(params: SendPhotoParams): Promise<TelegramMessage>

Send a photo.

Parameters:

• chat_id (number | string): Target chat ID or username
• photo (string | Blob | File): Photo URL, file_id, or file to upload
• caption (string, optional): Photo caption
• parse_mode (string, optional): Parse mode for caption
• reply_markup (object, optional): Inline or reply keyboard
• And more...

Webhook Schemas

All webhook types are validated using Zod schemas:

• UpdateSchema: Main update object
• MessageSchema: Message object
• UserSchema: User object
• ChatSchema: Chat object
• PhotoSizeSchema: Photo size object
• CallbackQuerySchema: Callback query object
• LocationSchema: Location object
• MessageEntitySchema: Message entity object

Keyboard Types

InlineKeyboardMarkup

{
  inline_keyboard: [
    [
      { text: 'Button 1', callback_data: 'data_1' },
      { text: 'Button 2', url: 'https://example.com' }
    ]
  ]
}

ReplyKeyboardMarkup

{
  keyboard: [
    [{ text: 'Button 1' }, { text: 'Button 2' }],
    [{ text: 'Share Contact', request_contact: true }]
  ],
  resize_keyboard: true,
  one_time_keyboard: true
}

Examples

Check the examples/ directory for complete examples:

• basic-bot.ts: Comprehensive bot example with all features
• webhook-handler.ts: Complete webhook handler with callbacks
• callback-example.ts: Advanced callback patterns and workflows
• CALLBACKS.md: Complete guide to callback queries

Development

This project uses Bun.sh as the runtime and package manager.

# Install dependencies
bun install

# Run tests
bun test

# Run tests in watch mode
bun test:watch

# Build the library
bun run build

# Run linter
bun run lint:fix

# Type check
bun run type-check

Current API Coverage

Currently implemented methods:

• ✅ setWebhook - Configure webhook
• ✅ sendMessage - Send text messages
• ✅ sendPhoto - Send photos

Webhook Types

• ✅ Update validation with Zod schemas
• ✅ Message types (text, photo, location)
• ✅ User and Chat types
• ✅ Callback queries (inline keyboard buttons)
• ✅ Message entities (mentions, hashtags, links, etc.)
• ✅ Inline keyboards with reply_markup
• ✅ Reply keyboards

Coming Soon

• sendVideo - Send videos
• sendAudio - Send audio files
• sendDocument - Send documents
• editMessageText - Edit messages
• deleteMessage - Delete messages
• And more...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Dogalyir

Links

• Telegram Bot API Documentation
• GitHub Repository
• npm Package

Acknowledgments

This library provides type-safe TypeScript bindings for the Telegram Bot API, with automatic validation using Zod schemas. Perfect for building reliable Telegram bots with full type safety.