Telegram Bot API - Complete Types Reference

Telegram Bot API - Complete Types Reference

Based on Bot API 9.4 (February 2026). All types are JSON-serialized objects.

Core Types

Update

The root object for incoming updates. Contains update_id and exactly ONE of:

User

Chat

ChatFullInfo

Extended chat information returned by getChat. Includes all Chat fields plus:

Message Type

The central type. Key fields:

Identification & Metadata

Content Fields

Reply & Forward

Media Fields

Keyboard/Reply Markup

MessageEntity

Special entities in message text or caption:

Fields: offset (Integer), length (Integer), type (String)

Keyboard & Reply Markup Types

InlineKeyboardMarkup

Grid of buttons shown inline with message.

{
  "inline_keyboard": [
    [{"text": "Button 1", "callback_data": "btn1"}, {"text": "Button 2", "url": "https://example.com"}],
    [{"text": "Full width", "callback_data": "btn3"}]
  ]
}

InlineKeyboardButton

ReplyKeyboardMarkup

Custom keyboard below input field.

KeyboardButton

ReplyKeyboardRemove

Remove custom keyboard: {"remove_keyboard": true, "selective": false}

ForceReply

Force reply to bot's message: {"force_reply": true, "input_field_placeholder": "Type here...", "selective": false}

Media Types

PhotoSize

Video

All PhotoSize fields plus: duration, thumbnail, file_name, mime_type, qualities (VideoQuality[])

VideoQuality (Bot API 9.4)

Audio

Fields: file_id, file_unique_id, duration, performer, title, file_name, mime_type, file_size, thumbnail

Document

Fields: file_id, file_unique_id, thumbnail, file_name, mime_type, file_size

Voice

Fields: file_id, file_unique_id, duration, mime_type, file_size

VideoNote

Fields: file_id, file_unique_id, length (diameter), duration, thumbnail, file_size

Animation

Fields: file_id, file_unique_id, width, height, duration, thumbnail, file_name, mime_type, file_size

Sticker

Chat Member Types

ChatMember Variants

ChatPermissions

Default permissions for group members:

Callback & Inline Query Types

CallbackQuery

InlineQuery

Payment Types

Invoice

Fields: title, description, start_parameter, currency, total_amount

SuccessfulPayment

Fields: currency, total_amount, invoice_payload, shipping_option_id, order_info, telegram_payment_charge_id, provider_payment_charge_id

ShippingQuery

Fields: id, from, invoice_payload, shipping_address

PreCheckoutQuery

Fields: id, from, currency, total_amount, invoice_payload, shipping_option_id, order_info

ShippingAddress

Fields: country_code, state, city, street_line1, street_line2, post_code

LabeledPrice

Fields: label (String), amount (Integer - price in smallest currency unit, e.g., cents)

Reaction Types

ReactionTypeEmoji

Standard emoji reaction: {"type": "emoji", "emoji": "👍"}

ReactionTypeCustomEmoji

Custom emoji reaction: {"type": "custom_emoji", "custom_emoji_id": "emoji_id"}

ReactionTypePaid

Paid reaction: {"type": "paid"}

Forum Topic Types

Business Types

Gift Types (Bot API 9.3-9.4)

Paid Media Types

Checklist Types (Bot API 9.2)

Giveaway Types

Background Types

Passport Types

Element types: personal_details, passport, driver_license, identity_card, internal_passport, address, utility_bill, bank_statement, rental_agreement, passport_registration, temporary_registration, phone_number, email

Web App Types

Service Message Types

These appear as fields in Message for system events:

Response Format

All API responses follow this structure:

{
  "ok": true,
  "result": { ... }
}

Error response:

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: message text is empty"
}

ResponseParameters

Returned in error responses when special action needed: