Types

Core TypeScript types and interfaces for Telegram Bot API

grammY re-exports all types from the grammY types package, which provides TypeScript definitions for the complete Telegram Bot API.

Main Types

Update

Represents an incoming update from Telegram. An update is the fundamental unit that your bot receives.

interface Update {
  update_id: number
  message?: Message
  edited_message?: Message
  channel_post?: Message
  edited_channel_post?: Message
  business_connection?: BusinessConnection
  business_message?: Message
  edited_business_message?: Message
  deleted_business_messages?: DeletedBusinessMessages
  message_reaction?: MessageReactionUpdated
  message_reaction_count?: MessageReactionCountUpdated
  inline_query?: InlineQuery
  chosen_inline_result?: ChosenInlineResult
  callback_query?: CallbackQuery
  shipping_query?: ShippingQuery
  pre_checkout_query?: PreCheckoutQuery
  poll?: Poll
  poll_answer?: PollAnswer
  my_chat_member?: ChatMemberUpdated
  chat_member?: ChatMemberUpdated
  chat_join_request?: ChatJoinRequest
  chat_boost?: ChatBoostUpdated
  removed_chat_boost?: ChatBoostRemoved
  purchased_paid_media?: PurchasedPaidMedia
}

Usage:

bot.on('message', (ctx) => {
  const update: Update = ctx.update
  console.log(`Received update ${update.update_id}`)
})

Message

Represents a message in Telegram. This is one of the most commonly used types.

interface Message {
  message_id: number
  message_thread_id?: number
  from?: User
  sender_chat?: Chat
  sender_boost_count?: number
  sender_business_bot?: User
  date: number
  business_connection_id?: string
  chat: Chat
  forward_origin?: MessageOrigin
  is_topic_message?: boolean
  is_automatic_forward?: boolean
  reply_to_message?: Message
  external_reply?: ExternalReplyInfo
  quote?: TextQuote
  reply_to_story?: Story
  via_bot?: User
  edit_date?: number
  has_protected_content?: boolean
  is_from_offline?: boolean
  media_group_id?: string
  author_signature?: string
  text?: string
  entities?: MessageEntity[]
  link_preview_options?: LinkPreviewOptions
  effect_id?: string
  animation?: Animation
  audio?: Audio
  document?: Document
  paid_media?: PaidMediaInfo
  photo?: PhotoSize[]
  sticker?: Sticker
  story?: Story
  video?: Video
  video_note?: VideoNote
  voice?: Voice
  caption?: string
  caption_entities?: MessageEntity[]
  show_caption_above_media?: boolean
  has_media_spoiler?: boolean
  contact?: Contact
  dice?: Dice
  game?: Game
  poll?: Poll
  venue?: Venue
  location?: Location
  // ... and many more properties
}

Usage:

bot.on('message:text', (ctx) => {
  const message: Message = ctx.message
  console.log(`Message ${message.message_id} says: ${message.text}`)
})

User

Represents a Telegram user or bot.

interface User {
  id: number
  is_bot: boolean
  first_name: string
  last_name?: string
  username?: string
  language_code?: string
  is_premium?: boolean
  added_to_attachment_menu?: boolean
  can_join_groups?: boolean
  can_read_all_group_messages?: boolean
  supports_inline_queries?: boolean
  can_connect_to_business?: boolean
  has_main_web_app?: boolean
}

Usage:

bot.on('message', (ctx) => {
  const user: User | undefined = ctx.from
  if (user) {
    console.log(`Message from ${user.first_name} (ID: ${user.id})`)
  }
})

Chat

Represents a chat (private, group, supergroup, or channel).

interface Chat {
  id: number
  type: 'private' | 'group' | 'supergroup' | 'channel'
  title?: string
  username?: string
  first_name?: string
  last_name?: string
  is_forum?: boolean
  // ... additional properties based on chat type
}

Usage:

bot.on('message', (ctx) => {
  const chat: Chat = ctx.chat
  if (chat.type === 'private') {
    console.log('This is a private chat')
  } else {
    console.log(`Group chat: ${chat.title}`)
  }
})

Entity Types

MessageEntity

Represents formatting entities in messages (bold, links, mentions, etc.).

interface MessageEntity {
  type: 'mention' | 'hashtag' | 'cashtag' | 'bot_command' | 'url' | 'email' |
        'phone_number' | 'bold' | 'italic' | 'underline' | 'strikethrough' |
        'spoiler' | 'blockquote' | 'expandable_blockquote' | 'code' | 'pre' |
        'text_link' | 'text_mention' | 'custom_emoji'
  offset: number
  length: number
  url?: string
  user?: User
  language?: string
  custom_emoji_id?: string
}

Usage:

bot.on('message:entities:url', (ctx) => {
  const entities = ctx.message.entities!
  const urlEntities = entities.filter(e => e.type === 'url')
  console.log(`Found ${urlEntities.length} URL(s) in message`)
})

Media Types

PhotoSize

interface PhotoSize {
  file_id: string
  file_unique_id: string
  width: number
  height: number
  file_size?: number
}

Document

interface Document {
  file_id: string
  file_unique_id: string
  thumbnail?: PhotoSize
  file_name?: string
  mime_type?: string
  file_size?: number
}

Audio, Video, Voice, VideoNote

Similar structures for different media types, all containing:

• file_id: Unique identifier for the file
• file_unique_id: Unique identifier across all bots
• Type-specific properties (duration, width, height, etc.)

Usage:

bot.on('message:photo', (ctx) => {
  const photos: PhotoSize[] = ctx.message.photo
  const largest = photos[photos.length - 1]
  console.log(`Received photo: ${largest.file_id}`)
})

Inline Mode Types

InlineQuery

Represents an incoming inline query.

interface InlineQuery {
  id: string
  from: User
  query: string
  offset: string
  chat_type?: 'sender' | 'private' | 'group' | 'supergroup' | 'channel'
  location?: Location
}

CallbackQuery

Represents an incoming callback query from an inline button.

interface CallbackQuery {
  id: string
  from: User
  message?: Message
  inline_message_id?: string
  chat_instance: string
  data?: string
  game_short_name?: string
}

Usage:

bot.on('callback_query:data', async (ctx) => {
  const query: CallbackQuery = ctx.callbackQuery
  console.log(`Button clicked: ${query.data}`)
  await ctx.answerCallbackQuery()
})

Payment Types

PreCheckoutQuery

interface PreCheckoutQuery {
  id: string
  from: User
  currency: string
  total_amount: number
  invoice_payload: string
  shipping_option_id?: string
  order_info?: OrderInfo
}

Other Important Types

ChatMemberUpdated

Represents changes in chat member status.

interface ChatMemberUpdated {
  chat: Chat
  from: User
  date: number
  old_chat_member: ChatMember
  new_chat_member: ChatMember
  invite_link?: ChatInviteLink
  via_join_request?: boolean
  via_chat_folder_invite_link?: boolean
}

Poll

interface Poll {
  id: string
  question: string
  question_entities?: MessageEntity[]
  options: PollOption[]
  total_voter_count: number
  is_closed: boolean
  is_anonymous: boolean
  type: 'regular' | 'quiz'
  allows_multiple_answers: boolean
  correct_option_id?: number
  explanation?: string
  explanation_entities?: MessageEntity[]
  open_period?: number
  close_date?: number
}

InputFile

For uploading files to Telegram:

import { InputFile } from 'grammy'

// From local file path
const file1 = new InputFile('/path/to/file.jpg')

// From Buffer/Uint8Array
const file2 = new InputFile(buffer, 'photo.jpg')

// From ReadableStream
const file3 = new InputFile(stream, 'video.mp4')

// From URL (will be downloaded)
const file4 = new InputFile(new URL('https://example.com/image.png'))

await ctx.replyWithPhoto(file1)

Type Utilities

grammY exports all types from @grammyjs/types. You can import any type you need:

import type {
  Update,
  Message,
  User,
  Chat,
  InlineKeyboardMarkup,
  ReplyKeyboardMarkup,
  // ... and many more
} from 'grammy'

For the complete list of available types, see the Telegram Bot API documentation and the grammY types repository.

API Constants

grammY exports useful constants for working with the Bot API.

DEFAULT_UPDATE_TYPES

List of update types a bot receives by default (excludes chat_member, message_reaction, and message_reaction_count).

import { DEFAULT_UPDATE_TYPES } from "grammy";

// With long polling
bot.start({ allowed_updates: DEFAULT_UPDATE_TYPES });

// With webhooks
await bot.api.setWebhook(url, { allowed_updates: DEFAULT_UPDATE_TYPES });

ALL_UPDATE_TYPES

List of all available update types, including those not delivered by default.

import { ALL_UPDATE_TYPES } from "grammy";

// Receive all update types
bot.start({ allowed_updates: ALL_UPDATE_TYPES });

ALL_CHAT_PERMISSIONS

An object containing all chat permissions set to true. Useful for lifting all restrictions from a user.

import { ALL_CHAT_PERMISSIONS } from "grammy";

// Lift all restrictions
await ctx.restrictChatMember(userId, ALL_CHAT_PERMISSIONS);

See Also

• Filter Types - Type narrowing with filter queries
• Middleware Types - Middleware function signatures
• Context - The context object