0
# Types and Objects
1
2
Complete type system covering all Telegram objects including messages, users, chats, keyboards, media, payments, and inline queries. Over 319 classes with full type safety and automatic serialization/deserialization.
3
4
## Capabilities
5
6
### Core Objects
7
8
Fundamental Telegram objects that form the basis of the Bot API.
9
10
```python { .api }
11
class TelegramObject:
12
"""Base class for all Telegram objects with automatic serialization"""
13
pass
14
15
class Update(TelegramObject):
16
"""Represents an incoming update containing events"""
17
update_id: int
18
message: Message | None
19
edited_message: Message | None
20
channel_post: Message | None
21
edited_channel_post: Message | None
22
business_connection: BusinessConnection | None
23
business_message: Message | None
24
edited_business_message: Message | None
25
deleted_business_messages: BusinessMessagesDeleted | None
26
message_reaction: MessageReactionUpdated | None
27
message_reaction_count: MessageReactionCountUpdated | None
28
inline_query: InlineQuery | None
29
chosen_inline_result: ChosenInlineResult | None
30
callback_query: CallbackQuery | None
31
shipping_query: ShippingQuery | None
32
pre_checkout_query: PreCheckoutQuery | None
33
purchased_paid_media: PaidMediaPurchased | None
34
poll: Poll | None
35
poll_answer: PollAnswer | None
36
my_chat_member: ChatMemberUpdated | None
37
chat_member: ChatMemberUpdated | None
38
chat_join_request: ChatJoinRequest | None
39
chat_boost: ChatBoostUpdated | None
40
removed_chat_boost: ChatBoostRemoved | None
41
42
class User(TelegramObject):
43
"""Represents a Telegram user or bot"""
44
id: int
45
is_bot: bool
46
first_name: str
47
last_name: str | None
48
username: str | None
49
language_code: str | None
50
is_premium: bool | None
51
added_to_attachment_menu: bool | None
52
can_join_groups: bool | None
53
can_read_all_group_messages: bool | None
54
supports_inline_queries: bool | None
55
56
class Chat(TelegramObject):
57
"""Represents a chat (private, group, supergroup, or channel)"""
58
id: int
59
type: str # "private", "group", "supergroup", "channel"
60
title: str | None
61
username: str | None
62
first_name: str | None
63
last_name: str | None
64
is_forum: bool | None
65
description: str | None
66
invite_link: str | None
67
pinned_message: Message | None
68
permissions: ChatPermissions | None
69
slow_mode_delay: int | None
70
message_auto_delete_time: int | None
71
has_protected_content: bool | None
72
sticker_set_name: str | None
73
can_set_sticker_set: bool | None
74
linked_chat_id: int | None
75
location: ChatLocation | None
76
```
77
78
### Message Objects
79
80
Message-related objects including content, entities, and replies.
81
82
```python { .api }
83
class Message(TelegramObject):
84
"""Represents a message"""
85
message_id: int
86
message_thread_id: int | None
87
from_user: User | None
88
sender_chat: Chat | None
89
date: datetime.datetime
90
chat: Chat
91
forward_from: User | None
92
forward_from_chat: Chat | None
93
forward_from_message_id: int | None
94
forward_signature: str | None
95
forward_sender_name: str | None
96
forward_date: datetime.datetime | None
97
is_topic_message: bool | None
98
is_automatic_forward: bool | None
99
reply_to_message: Message | None
100
via_bot: User | None
101
edit_date: datetime.datetime | None
102
has_protected_content: bool | None
103
media_group_id: str | None
104
author_signature: str | None
105
text: str | None
106
entities: list[MessageEntity] | None
107
animation: Animation | None
108
audio: Audio | None
109
document: Document | None
110
photo: list[PhotoSize] | None
111
sticker: Sticker | None
112
story: Story | None
113
video: Video | None
114
video_note: VideoNote | None
115
voice: Voice | None
116
caption: str | None
117
caption_entities: list[MessageEntity] | None
118
has_media_spoiler: bool | None
119
contact: Contact | None
120
dice: Dice | None
121
game: Game | None
122
poll: Poll | None
123
venue: Venue | None
124
location: Location | None
125
new_chat_members: list[User] | None
126
left_chat_member: User | None
127
new_chat_title: str | None
128
new_chat_photo: list[PhotoSize] | None
129
delete_chat_photo: bool | None
130
group_chat_created: bool | None
131
supergroup_chat_created: bool | None
132
channel_chat_created: bool | None
133
message_auto_delete_timer_changed: MessageAutoDeleteTimerChanged | None
134
migrate_to_chat_id: int | None
135
migrate_from_chat_id: int | None
136
pinned_message: Message | None
137
invoice: Invoice | None
138
successful_payment: SuccessfulPayment | None
139
connected_website: str | None
140
write_access_allowed: WriteAccessAllowed | None
141
passport_data: PassportData | None
142
proximity_alert_triggered: ProximityAlertTriggered | None
143
forum_topic_created: ForumTopicCreated | None
144
forum_topic_edited: ForumTopicEdited | None
145
forum_topic_closed: ForumTopicClosed | None
146
forum_topic_reopened: ForumTopicReopened | None
147
general_forum_topic_hidden: GeneralForumTopicHidden | None
148
general_forum_topic_unhidden: GeneralForumTopicUnhidden | None
149
video_chat_scheduled: VideoChatScheduled | None
150
video_chat_started: VideoChatStarted | None
151
video_chat_ended: VideoChatEnded | None
152
video_chat_participants_invited: VideoChatParticipantsInvited | None
153
web_app_data: WebAppData | None
154
reply_markup: InlineKeyboardMarkup | None
155
156
async def answer(self, text: str, **kwargs) -> Message:
157
"""Reply to this message"""
158
159
async def reply(self, text: str, **kwargs) -> Message:
160
"""Reply to this message (alias for answer)"""
161
162
async def edit_text(self, text: str, **kwargs) -> Message | bool:
163
"""Edit this message's text"""
164
165
async def delete(self) -> bool:
166
"""Delete this message"""
167
168
async def forward(self, chat_id: int | str) -> Message:
169
"""Forward this message to another chat"""
170
171
async def copy(self, chat_id: int | str, **kwargs) -> MessageId:
172
"""Copy this message to another chat"""
173
174
class MessageEntity(TelegramObject):
175
"""Represents one special entity in a text message"""
176
type: str # "mention", "hashtag", "cashtag", "bot_command", "url", etc.
177
offset: int
178
length: int
179
url: str | None
180
user: User | None
181
language: str | None
182
custom_emoji_id: str | None
183
```
184
185
### Media Objects
186
187
Objects representing various media types and files.
188
189
```python { .api }
190
class PhotoSize(TelegramObject):
191
"""Represents one size of a photo or a file/sticker thumbnail"""
192
file_id: str
193
file_unique_id: str
194
width: int
195
height: int
196
file_size: int | None
197
198
class Audio(TelegramObject):
199
"""Represents an audio file"""
200
file_id: str
201
file_unique_id: str
202
duration: int
203
performer: str | None
204
title: str | None
205
file_name: str | None
206
mime_type: str | None
207
file_size: int | None
208
thumbnail: PhotoSize | None
209
210
class Document(TelegramObject):
211
"""Represents a general file"""
212
file_id: str
213
file_unique_id: str
214
thumbnail: PhotoSize | None
215
file_name: str | None
216
mime_type: str | None
217
file_size: int | None
218
219
class Video(TelegramObject):
220
"""Represents a video file"""
221
file_id: str
222
file_unique_id: str
223
width: int
224
height: int
225
duration: int
226
thumbnail: PhotoSize | None
227
file_name: str | None
228
mime_type: str | None
229
file_size: int | None
230
231
class Animation(TelegramObject):
232
"""Represents an animation file (GIF or H.264/MPEG-4 AVC video without sound)"""
233
file_id: str
234
file_unique_id: str
235
width: int
236
height: int
237
duration: int
238
thumbnail: PhotoSize | None
239
file_name: str | None
240
mime_type: str | None
241
file_size: int | None
242
243
class Voice(TelegramObject):
244
"""Represents a voice note"""
245
file_id: str
246
file_unique_id: str
247
duration: int
248
mime_type: str | None
249
file_size: int | None
250
251
class VideoNote(TelegramObject):
252
"""Represents a video message"""
253
file_id: str
254
file_unique_id: str
255
length: int
256
duration: int
257
thumbnail: PhotoSize | None
258
file_size: int | None
259
```
260
261
### Input File Types
262
263
Types for handling file uploads and media input.
264
265
```python { .api }
266
class InputFile:
267
"""Base class for input files"""
268
pass
269
270
class FSInputFile(InputFile):
271
"""Input file from filesystem"""
272
def __init__(self, path: str | Path, filename: str | None = None, chunk_size: int = 65536):
273
"""
274
Parameters:
275
- path: Path to the file
276
- filename: Custom filename (defaults to file basename)
277
- chunk_size: Size of chunks for reading file
278
"""
279
280
class BufferedInputFile(InputFile):
281
"""Input file from bytes in memory"""
282
def __init__(self, file: bytes, filename: str):
283
"""
284
Parameters:
285
- file: File content as bytes
286
- filename: Filename for the upload
287
"""
288
289
class URLInputFile(InputFile):
290
"""Input file from URL"""
291
def __init__(self, url: str, filename: str | None = None, chunk_size: int = 65536):
292
"""
293
Parameters:
294
- url: URL to download file from
295
- filename: Custom filename
296
- chunk_size: Size of chunks for downloading
297
"""
298
299
class InputMedia:
300
"""Base class for input media objects"""
301
type: str
302
media: str | InputFile
303
caption: str | None
304
parse_mode: str | None
305
caption_entities: list[MessageEntity] | None
306
307
class InputMediaPhoto(InputMedia):
308
"""Represents a photo to be sent"""
309
type: str = "photo"
310
has_spoiler: bool | None
311
312
class InputMediaVideo(InputMedia):
313
"""Represents a video to be sent"""
314
type: str = "video"
315
width: int | None
316
height: int | None
317
duration: int | None
318
supports_streaming: bool | None
319
has_spoiler: bool | None
320
thumbnail: str | InputFile | None
321
322
class InputMediaAnimation(InputMedia):
323
"""Represents an animation file (GIF or H.264/MPEG-4 AVC video without sound) to be sent"""
324
type: str = "animation"
325
width: int | None
326
height: int | None
327
duration: int | None
328
has_spoiler: bool | None
329
thumbnail: str | InputFile | None
330
331
class InputMediaAudio(InputMedia):
332
"""Represents an audio file to be sent"""
333
type: str = "audio"
334
duration: int | None
335
performer: str | None
336
title: str | None
337
thumbnail: str | InputFile | None
338
339
class InputMediaDocument(InputMedia):
340
"""Represents a general file to be sent"""
341
type: str = "document"
342
disable_content_type_detection: bool | None
343
thumbnail: str | InputFile | None
344
```
345
346
### Keyboard Types
347
348
Objects for creating inline and reply keyboards.
349
350
```python { .api }
351
class InlineKeyboardMarkup(TelegramObject):
352
"""Represents an inline keyboard"""
353
inline_keyboard: list[list[InlineKeyboardButton]]
354
355
class InlineKeyboardButton(TelegramObject):
356
"""Represents one button of an inline keyboard"""
357
text: str
358
url: str | None
359
login_url: LoginUrl | None
360
callback_data: str | None
361
web_app: WebAppInfo | None
362
switch_inline_query: str | None
363
switch_inline_query_current_chat: str | None
364
callback_game: CallbackGame | None
365
pay: bool | None
366
367
class ReplyKeyboardMarkup(TelegramObject):
368
"""Represents a custom keyboard with reply options"""
369
keyboard: list[list[KeyboardButton]]
370
is_persistent: bool | None
371
resize_keyboard: bool | None
372
one_time_keyboard: bool | None
373
input_field_placeholder: str | None
374
selective: bool | None
375
376
class KeyboardButton(TelegramObject):
377
"""Represents one button of the reply keyboard"""
378
text: str
379
request_user: KeyboardButtonRequestUser | None
380
request_chat: KeyboardButtonRequestChat | None
381
request_contact: bool | None
382
request_location: bool | None
383
request_poll: KeyboardButtonPollType | None
384
web_app: WebAppInfo | None
385
386
class ReplyKeyboardRemove(TelegramObject):
387
"""Removes the current custom keyboard"""
388
remove_keyboard: bool = True
389
selective: bool | None
390
391
class ForceReply(TelegramObject):
392
"""Forces Telegram clients to display a reply interface"""
393
force_reply: bool = True
394
input_field_placeholder: str | None
395
selective: bool | None
396
```
397
398
### Chat Management Types
399
400
Objects for managing chat members, permissions, and administration.
401
402
```python { .api }
403
class ChatMember(TelegramObject):
404
"""Base class for chat members"""
405
status: str
406
user: User
407
408
class ChatMemberOwner(ChatMember):
409
"""Represents a chat member that owns the chat"""
410
status: str = "creator"
411
is_anonymous: bool
412
custom_title: str | None
413
414
class ChatMemberAdministrator(ChatMember):
415
"""Represents a chat member that has administrator privileges"""
416
status: str = "administrator"
417
can_be_edited: bool
418
can_manage_chat: bool
419
can_delete_messages: bool
420
can_manage_video_chats: bool
421
can_restrict_members: bool
422
can_promote_members: bool
423
can_change_info: bool
424
can_invite_users: bool
425
can_post_messages: bool | None
426
can_edit_messages: bool | None
427
can_pin_messages: bool | None
428
can_manage_topics: bool | None
429
is_anonymous: bool
430
custom_title: str | None
431
432
class ChatMemberMember(ChatMember):
433
"""Represents a chat member that has no additional privileges"""
434
status: str = "member"
435
436
class ChatMemberRestricted(ChatMember):
437
"""Represents a chat member that is under certain restrictions"""
438
status: str = "restricted"
439
is_member: bool
440
can_send_messages: bool
441
can_send_audios: bool
442
can_send_documents: bool
443
can_send_photos: bool
444
can_send_videos: bool
445
can_send_video_notes: bool
446
can_send_voice_notes: bool
447
can_send_polls: bool
448
can_send_other_messages: bool
449
can_add_web_page_previews: bool
450
can_change_info: bool
451
can_invite_users: bool
452
can_pin_messages: bool
453
can_manage_topics: bool
454
until_date: datetime.datetime
455
456
class ChatMemberLeft(ChatMember):
457
"""Represents a chat member that isn't currently a member of the chat"""
458
status: str = "left"
459
460
class ChatMemberBanned(ChatMember):
461
"""Represents a chat member that was banned in the chat"""
462
status: str = "kicked"
463
until_date: datetime.datetime
464
465
class ChatPermissions(TelegramObject):
466
"""Describes actions that a non-administrator user is allowed to take in a chat"""
467
can_send_messages: bool | None
468
can_send_audios: bool | None
469
can_send_documents: bool | None
470
can_send_photos: bool | None
471
can_send_videos: bool | None
472
can_send_video_notes: bool | None
473
can_send_voice_notes: bool | None
474
can_send_polls: bool | None
475
can_send_other_messages: bool | None
476
can_add_web_page_previews: bool | None
477
can_change_info: bool | None
478
can_invite_users: bool | None
479
can_pin_messages: bool | None
480
can_manage_topics: bool | None
481
482
class ChatAdministratorRights(TelegramObject):
483
"""Represents the rights of an administrator in a chat"""
484
is_anonymous: bool
485
can_manage_chat: bool
486
can_delete_messages: bool
487
can_manage_video_chats: bool
488
can_restrict_members: bool
489
can_promote_members: bool
490
can_change_info: bool
491
can_invite_users: bool
492
can_post_messages: bool | None
493
can_edit_messages: bool | None
494
can_pin_messages: bool | None
495
can_manage_topics: bool | None
496
```
497
498
### Inline Query Types
499
500
Objects for handling inline queries and results.
501
502
```python { .api }
503
class InlineQuery(TelegramObject):
504
"""Represents an incoming inline query"""
505
id: str
506
from_user: User
507
query: str
508
offset: str
509
chat_type: str | None
510
location: Location | None
511
512
class CallbackQuery(TelegramObject):
513
"""Represents an incoming callback query from an inline keyboard button"""
514
id: str
515
from_user: User
516
message: Message | None
517
inline_message_id: str | None
518
chat_instance: str
519
data: str | None
520
game_short_name: str | None
521
522
async def answer(self, text: str | None = None, show_alert: bool = False, **kwargs) -> bool:
523
"""Answer the callback query"""
524
525
class InlineQueryResult(TelegramObject):
526
"""Base class for inline query results"""
527
type: str
528
id: str
529
530
class InlineQueryResultArticle(InlineQueryResult):
531
"""Represents a link to an article or web page"""
532
type: str = "article"
533
title: str
534
input_message_content: InputMessageContent
535
reply_markup: InlineKeyboardMarkup | None
536
url: str | None
537
hide_url: bool | None
538
description: str | None
539
thumbnail_url: str | None
540
thumbnail_width: int | None
541
thumbnail_height: int | None
542
543
class InlineQueryResultPhoto(InlineQueryResult):
544
"""Represents a link to a photo"""
545
type: str = "photo"
546
photo_url: str
547
thumbnail_url: str
548
photo_width: int | None
549
photo_height: int | None
550
title: str | None
551
description: str | None
552
caption: str | None
553
parse_mode: str | None
554
caption_entities: list[MessageEntity] | None
555
reply_markup: InlineKeyboardMarkup | None
556
input_message_content: InputMessageContent | None
557
```
558
559
### Payment Types
560
561
Objects for handling payments and invoices.
562
563
```python { .api }
564
class Invoice(TelegramObject):
565
"""Contains basic information about an invoice"""
566
title: str
567
description: str
568
start_parameter: str
569
currency: str
570
total_amount: int
571
572
class LabeledPrice(TelegramObject):
573
"""Represents a portion of the price for goods or services"""
574
label: str
575
amount: int
576
577
class ShippingAddress(TelegramObject):
578
"""Represents a shipping address"""
579
country_code: str
580
state: str
581
city: str
582
street_line1: str
583
street_line2: str
584
post_code: str
585
586
class OrderInfo(TelegramObject):
587
"""Represents information about an order"""
588
name: str | None
589
phone_number: str | None
590
email: str | None
591
shipping_address: ShippingAddress | None
592
593
class ShippingOption(TelegramObject):
594
"""Represents one shipping option"""
595
id: str
596
title: str
597
prices: list[LabeledPrice]
598
599
class SuccessfulPayment(TelegramObject):
600
"""Contains basic information about a successful payment"""
601
currency: str
602
total_amount: int
603
invoice_payload: str
604
shipping_option_id: str | None
605
order_info: OrderInfo | None
606
telegram_payment_charge_id: str
607
provider_payment_charge_id: str
608
609
class ShippingQuery(TelegramObject):
610
"""Contains information about an incoming shipping query"""
611
id: str
612
from_user: User
613
invoice_payload: str
614
shipping_address: ShippingAddress
615
616
class PreCheckoutQuery(TelegramObject):
617
"""Contains information about an incoming pre-checkout query"""
618
id: str
619
from_user: User
620
currency: str
621
total_amount: int
622
invoice_payload: str
623
shipping_option_id: str | None
624
order_info: OrderInfo | None
625
```
626
627
### Business Features
628
629
Business account integration types for connecting with Telegram Business accounts.
630
631
```python { .api }
632
class BusinessConnection(TelegramObject):
633
"""Describes the connection of the bot with a business account"""
634
id: str
635
user: User
636
user_chat_id: int
637
date: datetime.datetime
638
is_enabled: bool
639
can_reply: bool
640
641
class BusinessMessagesDeleted(TelegramObject):
642
"""Messages were deleted from a connected business account"""
643
business_connection_id: str
644
chat: Chat
645
message_ids: list[int]
646
647
class MessageReactionUpdated(TelegramObject):
648
"""Change of a reaction on a message performed by a user"""
649
chat: Chat
650
message_id: int
651
date: datetime.datetime
652
old_reaction: list[ReactionType]
653
new_reaction: list[ReactionType]
654
user: User | None
655
actor_chat: Chat | None
656
657
class MessageReactionCountUpdated(TelegramObject):
658
"""Reactions to a message with anonymous reactions were changed"""
659
chat: Chat
660
message_id: int
661
date: datetime.datetime
662
reactions: list[ReactionCount]
663
```
664
665
### Chat Boost Features
666
667
Chat boost related types for managing channel and group boosts.
668
669
```python { .api }
670
class ChatBoostUpdated(TelegramObject):
671
"""A chat boost was added or changed"""
672
chat: Chat
673
boost: ChatBoost
674
675
class ChatBoostRemoved(TelegramObject):
676
"""A boost was removed from a chat"""
677
chat: Chat
678
boost_id: str
679
remove_date: datetime.datetime
680
source: ChatBoostSource
681
682
class ChatBoost(TelegramObject):
683
"""Contains information about a chat boost"""
684
boost_id: str
685
add_date: datetime.datetime
686
expiration_date: datetime.datetime
687
source: ChatBoostSource
688
689
class PaidMediaPurchased(TelegramObject):
690
"""A user purchased paid media with a non-empty payload"""
691
from_user: User
692
payload: str
693
```
694
695
### Link and Reply Options
696
697
Enhanced message options for link previews and reply parameters.
698
699
```python { .api }
700
class LinkPreviewOptions(TelegramObject):
701
"""Options used for link preview generation"""
702
is_disabled: bool | None = None
703
url: str | None = None
704
prefer_small_media: bool | None = None
705
prefer_large_media: bool | None = None
706
show_above_text: bool | None = None
707
708
class ReplyParameters(TelegramObject):
709
"""Describes reply parameters for the message being sent"""
710
message_id: int
711
chat_id: int | str | None = None
712
allow_sending_without_reply: bool | None = None
713
quote: str | None = None
714
quote_parse_mode: str | None = None
715
quote_entities: list[MessageEntity] | None = None
716
quote_position: int | None = None
717
718
class SuggestedPostParameters(TelegramObject):
719
"""Parameters of a suggested post to send"""
720
text: str | None = None
721
parse_mode: str | None = None
722
entities: list[MessageEntity] | None = None
723
media: list[InputMedia] | None = None
724
show_caption_above_media: bool | None = None
725
```
726
727
## Usage Examples
728
729
### Working with Messages
730
731
```python
732
from aiogram.types import Message, MessageEntity
733
734
async def handle_message(message: Message):
735
# Access message properties
736
print(f"Message ID: {message.message_id}")
737
print(f"From: {message.from_user.first_name if message.from_user else 'Unknown'}")
738
print(f"Text: {message.text}")
739
740
# Check message type
741
if message.photo:
742
print("Message contains a photo")
743
elif message.document:
744
print(f"Message contains document: {message.document.file_name}")
745
746
# Work with entities
747
if message.entities:
748
for entity in message.entities:
749
if entity.type == "url":
750
url = message.text[entity.offset:entity.offset + entity.length]
751
print(f"Found URL: {url}")
752
753
# Reply to message
754
await message.answer("Got your message!")
755
```
756
757
### File Upload Examples
758
759
```python
760
from aiogram.types import FSInputFile, BufferedInputFile, InputMediaPhoto
761
762
# Upload from filesystem
763
photo = FSInputFile("path/to/photo.jpg")
764
await bot.send_photo(chat_id, photo)
765
766
# Upload from memory
767
with open("image.png", "rb") as f:
768
photo_bytes = f.read()
769
photo = BufferedInputFile(photo_bytes, filename="image.png")
770
await bot.send_photo(chat_id, photo)
771
772
# Media group with mixed input types
773
media_group = [
774
InputMediaPhoto(media=FSInputFile("photo1.jpg"), caption="Photo 1"),
775
InputMediaPhoto(media=BufferedInputFile(photo_bytes, "photo2.png"), caption="Photo 2")
776
]
777
await bot.send_media_group(chat_id, media_group)
778
```
779
780
### Keyboard Creation
781
782
```python
783
from aiogram.types import InlineKeyboardMarkup, InlineKeyboardButton, ReplyKeyboardMarkup, KeyboardButton
784
785
# Inline keyboard
786
inline_kb = InlineKeyboardMarkup(inline_keyboard=[
787
[InlineKeyboardButton(text="Button 1", callback_data="btn1")],
788
[InlineKeyboardButton(text="Button 2", callback_data="btn2"),
789
InlineKeyboardButton(text="Button 3", callback_data="btn3")]
790
])
791
792
# Reply keyboard
793
reply_kb = ReplyKeyboardMarkup(
794
keyboard=[
795
[KeyboardButton(text="Contact", request_contact=True)],
796
[KeyboardButton(text="Location", request_location=True)],
797
[KeyboardButton(text="Poll", request_poll=KeyboardButtonPollType())]
798
],
799
resize_keyboard=True,
800
one_time_keyboard=True
801
)
802
803
await message.answer("Choose an option:", reply_markup=inline_kb)
804
```