Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/grammyjs/grammY/llms.txt

Use this file to discover all available pages before exploring further.

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

Build docs developers (and LLMs) love

Get started for freeTalk to us