> ## 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.

# Types

> Core TypeScript types and interfaces for Telegram Bot API

grammY re-exports all types from the [grammY types package](https://github.com/grammyjs/types), 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.

```typescript theme={null}
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:**

```typescript theme={null}
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.

```typescript theme={null}
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:**

```typescript theme={null}
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.

```typescript theme={null}
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:**

```typescript theme={null}
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).

```typescript theme={null}
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:**

```typescript theme={null}
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.).

```typescript theme={null}
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:**

```typescript theme={null}
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

```typescript theme={null}
interface PhotoSize {
  file_id: string
  file_unique_id: string
  width: number
  height: number
  file_size?: number
}
```

### Document

```typescript theme={null}
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:**

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
interface CallbackQuery {
  id: string
  from: User
  message?: Message
  inline_message_id?: string
  chat_instance: string
  data?: string
  game_short_name?: string
}
```

**Usage:**

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

## Payment Types

### PreCheckoutQuery

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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](https://github.com/grammyjs/types). You can import any type you need:

```typescript theme={null}
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](https://core.telegram.org/bots/api) and the [grammY types repository](https://github.com/grammyjs/types).

## 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`).

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
import { ALL_CHAT_PERMISSIONS } from "grammy";

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

## See Also

* [Filter Types](/api/filter-types) - Type narrowing with filter queries
* [Middleware Types](/api/middleware-types) - Middleware function signatures
* [Context](/api/context) - The context object