0
# Telegram Types
1

2
Complete type system covering all Telegram Bot API objects including messages, users, chats, files, and update structures.
3

4
## Capabilities
5

6
### Update Structure
7

8
Container for all incoming updates from Telegram.
9

10
```python { .api }
11
class Update:
12
    update_id: int
13
    message: Message | None
14
    edited_message: Message | None
15
    channel_post: Message | None
16
    edited_channel_post: Message | None
17
    business_connection: BusinessConnection | None
18
    business_message: Message | None
19
    edited_business_message: Message | None
20
    deleted_business_messages: BusinessMessagesDeleted | None
21
    message_reaction: MessageReactionUpdated | None
22
    message_reaction_count: MessageReactionCountUpdated | None
23
    inline_query: InlineQuery | None
24
    chosen_inline_result: ChosenInlineResult | None
25
    callback_query: CallbackQuery | None
26
    shipping_query: ShippingQuery | None
27
    pre_checkout_query: PreCheckoutQuery | None
28
    purchased_paid_media: PaidMediaPurchased | None
29
    poll: Poll | None
30
    poll_answer: PollAnswer | None
31
    my_chat_member: ChatMemberUpdated | None
32
    chat_member: ChatMemberUpdated | None
33
    chat_join_request: ChatJoinRequest | None
34
    chat_boost: ChatBoostUpdated | None
35
    removed_chat_boost: ChatBoostRemoved | None
36
    
37
    def effective_message(self) -> Message | None: ...
38
    def effective_chat(self) -> Chat | None: ...
39
    def effective_user(self) -> User | None: ...
40
```
41

42
### Message Types
43

44
Core message structure and related types.
45

46
```python { .api }
47
class Message:
48
    message_id: int
49
    message_thread_id: int | None
50
    from_user: User | None
51
    sender_chat: Chat | None
52
    sender_boost_count: int | None
53
    sender_business_bot: User | None
54
    date: datetime.datetime
55
    business_connection_id: str | None
56
    chat: Chat
57
    forward_origin: MessageOrigin | None
58
    is_topic_message: bool | None
59
    is_automatic_forward: bool | None
60
    reply_to_message: 'Message' | None
61
    external_reply: ExternalReplyInfo | None
62
    quote: TextQuote | None
63
    reply_to_story: Story | None
64
    via_bot: User | None
65
    edit_date: datetime.datetime | None
66
    has_protected_content: bool | None
67
    is_from_offline: bool | None
68
    media_group_id: str | None
69
    author_signature: str | None
70
    text: str | None
71
    entities: list[MessageEntity] | None
72
    link_preview_options: LinkPreviewOptions | None
73
    effect_id: str | None
74
    animation: Animation | None
75
    audio: Audio | None
76
    document: Document | None
77
    paid_media: PaidMediaInfo | None
78
    photo: list[PhotoSize] | None
79
    sticker: Sticker | None
80
    story: Story | None
81
    video: Video | None
82
    video_note: VideoNote | None
83
    voice: Voice | None
84
    caption: str | None
85
    caption_entities: list[MessageEntity] | None
86
    show_caption_above_media: bool | None
87
    has_media_spoiler: bool | None
88
    contact: Contact | None
89
    dice: Dice | None
90
    game: Game | None
91
    poll: Poll | None
92
    venue: Venue | None
93
    location: Location | None
94
    new_chat_members: list[User] | None
95
    left_chat_member: User | None
96
    new_chat_title: str | None
97
    new_chat_photo: list[PhotoSize] | None
98
    delete_chat_photo: bool | None
99
    group_chat_created: bool | None
100
    supergroup_chat_created: bool | None
101
    channel_chat_created: bool | None
102
    message_auto_delete_timer_changed: MessageAutoDeleteTimerChanged | None
103
    migrate_to_chat_id: int | None
104
    migrate_from_chat_id: int | None
105
    pinned_message: MaybeInaccessibleMessage | None
106
    invoice: Invoice | None
107
    successful_payment: SuccessfulPayment | None
108
    refunded_payment: RefundedPayment | None
109
    users_shared: UsersShared | None
110
    chat_shared: ChatShared | None
111
    connected_website: str | None
112
    write_access_allowed: WriteAccessAllowed | None
113
    passport_data: PassportData | None
114
    proximity_alert_triggered: ProximityAlertTriggered | None
115
    boost_added: ChatBoostAdded | None
116
    chat_background_set: ChatBackground | None
117
    forum_topic_created: ForumTopicCreated | None
118
    forum_topic_edited: ForumTopicEdited | None
119
    forum_topic_closed: ForumTopicClosed | None
120
    forum_topic_reopened: ForumTopicReopened | None
121
    general_forum_topic_hidden: GeneralForumTopicHidden | None
122
    general_forum_topic_unhidden: GeneralForumTopicUnhidden | None
123
    giveaway_created: GiveawayCreated | None
124
    giveaway: Giveaway | None
125
    giveaway_winners: GiveawayWinners | None
126
    giveaway_completed: GiveawayCompleted | None
127
    video_chat_scheduled: VideoChatScheduled | None
128
    video_chat_started: VideoChatStarted | None
129
    video_chat_ended: VideoChatEnded | None
130
    video_chat_participants_invited: VideoChatParticipantsInvited | None
131
    web_app_data: WebAppData | None
132
    reply_markup: InlineKeyboardMarkup | None
133
    
134
    async def reply_text(self, text: str, **kwargs) -> 'Message': ...
135
    async def reply_photo(self, photo: InputFile | str, **kwargs) -> 'Message': ...
136
    async def reply_audio(self, audio: InputFile | str, **kwargs) -> 'Message': ...
137
    async def reply_document(self, document: InputFile | str, **kwargs) -> 'Message': ...
138
    async def reply_video(self, video: InputFile | str, **kwargs) -> 'Message': ...
139
    async def reply_animation(self, animation: InputFile | str, **kwargs) -> 'Message': ...
140
    async def reply_sticker(self, sticker: InputFile | str, **kwargs) -> 'Message': ...
141
    async def reply_video_note(self, video_note: InputFile | str, **kwargs) -> 'Message': ...
142
    async def reply_voice(self, voice: InputFile | str, **kwargs) -> 'Message': ...
143
    async def reply_location(self, latitude: float, longitude: float, **kwargs) -> 'Message': ...
144
    async def reply_venue(self, latitude: float, longitude: float, title: str, address: str, **kwargs) -> 'Message': ...
145
    async def reply_contact(self, phone_number: str, first_name: str, **kwargs) -> 'Message': ...
146
    async def reply_poll(self, question: str, options: list[str], **kwargs) -> 'Message': ...
147
    async def reply_dice(self, emoji: str = None, **kwargs) -> 'Message': ...
148
    async def edit_text(self, text: str, **kwargs) -> 'Message' | bool: ...
149
    async def edit_caption(self, caption: str = None, **kwargs) -> 'Message' | bool: ...
150
    async def edit_media(self, media: InputMedia, **kwargs) -> 'Message' | bool: ...
151
    async def edit_reply_markup(self, reply_markup: InlineKeyboardMarkup = None, **kwargs) -> 'Message' | bool: ...
152
    async def delete(self, **kwargs) -> bool: ...
153
    async def pin(self, **kwargs) -> bool: ...
154
    async def unpin(self, **kwargs) -> bool: ...
155
    async def forward(self, chat_id: int | str, **kwargs) -> 'Message': ...
156
    async def copy(self, chat_id: int | str, **kwargs) -> MessageId: ...
157
    
158
    def parse_entity(self, entity: MessageEntity) -> str: ...
159
    def parse_entities(self, types: list[str] = None) -> dict[MessageEntity, str]: ...
160
    def parse_caption_entity(self, entity: MessageEntity) -> str: ...
161
    def parse_caption_entities(self, types: list[str] = None) -> dict[MessageEntity, str]: ...
162

163
class InaccessibleMessage:
164
    chat: Chat
165
    message_id: int
166
    date: int
167

168
MaybeInaccessibleMessage = Message | InaccessibleMessage
169

170
class MessageId:
171
    message_id: int
172

173
class MessageEntity:
174
    type: str
175
    offset: int
176
    length: int
177
    url: str | None
178
    user: User | None
179
    language: str | None
180
    custom_emoji_id: str | None
181
```
182

183
### User and Chat Types
184

185
User information and chat details.
186

187
```python { .api }
188
class User:
189
    id: int
190
    is_bot: bool
191
    first_name: str
192
    last_name: str | None
193
    username: str | None
194
    language_code: str | None
195
    is_premium: bool | None
196
    added_to_attachment_menu: bool | None
197
    can_join_groups: bool | None
198
    can_read_all_group_messages: bool | None
199
    supports_inline_queries: bool | None
200
    can_connect_to_business: bool | None
201
    has_main_web_app: bool | None
202
    
203
    def full_name(self) -> str: ...
204
    def name(self) -> str: ...
205
    def mention_markdown(self, name: str = None) -> str: ...
206
    def mention_html(self, name: str = None) -> str: ...
207

208
class Chat:
209
    id: int
210
    type: str
211
    title: str | None
212
    username: str | None
213
    first_name: str | None
214
    last_name: str | None
215
    is_forum: bool | None
216
    
217
    def full_name(self) -> str: ...
218
    def name(self) -> str: ...
219
    async def leave(self, **kwargs) -> bool: ...
220
    async def get_administrators(self, **kwargs) -> list[ChatMember]: ...
221
    async def get_member_count(self, **kwargs) -> int: ...
222
    async def get_member(self, user_id: int, **kwargs) -> ChatMember: ...
223
    async def ban_member(self, user_id: int, **kwargs) -> bool: ...
224
    async def unban_member(self, user_id: int, **kwargs) -> bool: ...
225
    async def restrict_member(self, user_id: int, permissions: ChatPermissions, **kwargs) -> bool: ...
226
    async def promote_member(self, user_id: int, **kwargs) -> bool: ...
227
    async def set_permissions(self, permissions: ChatPermissions, **kwargs) -> bool: ...
228
    async def set_administrator_custom_title(self, user_id: int, custom_title: str, **kwargs) -> bool: ...
229
    async def pin_message(self, message_id: int, **kwargs) -> bool: ...
230
    async def unpin_message(self, message_id: int = None, **kwargs) -> bool: ...
231
    async def unpin_all_messages(self, **kwargs) -> bool: ...
232
    async def send_message(self, text: str, **kwargs) -> Message: ...
233
    # ... (all Bot send methods available as Chat methods)
234

235
class ChatFullInfo(Chat):
236
    accent_color_id: int | None
237
    max_reaction_count: int | None
238
    photo: ChatPhoto | None
239
    active_usernames: list[str] | None
240
    birthdate: Birthdate | None
241
    business_intro: BusinessIntro | None
242
    business_location: BusinessLocation | None
243
    business_opening_hours: BusinessOpeningHours | None
244
    personal_chat: Chat | None
245
    available_reactions: list[ReactionType] | None
246
    background_custom_emoji_id: str | None
247
    profile_accent_color_id: int | None
248
    profile_background_custom_emoji_id: str | None
249
    emoji_status_custom_emoji_id: str | None
250
    emoji_status_expiration_date: datetime.datetime | None
251
    bio: str | None
252
    has_private_forwards: bool | None
253
    has_restricted_voice_and_video_messages: bool | None
254
    join_to_send_messages: bool | None
255
    join_by_request: bool | None
256
    description: str | None
257
    invite_link: str | None
258
    pinned_message: Message | None
259
    permissions: ChatPermissions | None
260
    can_send_paid_media: bool | None
261
    slow_mode_delay: int | None
262
    unrestrict_boost_count: int | None
263
    message_auto_delete_time: int | None
264
    has_aggressive_anti_spam_enabled: bool | None
265
    has_hidden_members: bool | None
266
    has_protected_content: bool | None
267
    has_visible_history: bool | None
268
    sticker_set_name: str | None
269
    can_set_sticker_set: bool | None
270
    custom_emoji_sticker_set_name: str | None
271
    linked_chat_id: int | None
272
    location: ChatLocation | None
273

274
class ChatMember:
275
    user: User
276
    status: str
277
    until_date: datetime.datetime | None
278

279
class ChatMemberOwner(ChatMember):
280
    is_anonymous: bool
281
    custom_title: str | None
282

283
class ChatMemberAdministrator(ChatMember):
284
    can_be_edited: bool
285
    can_manage_chat: bool
286
    can_post_messages: bool | None
287
    can_edit_messages: bool | None
288
    can_delete_messages: bool
289
    can_manage_video_chats: bool
290
    can_restrict_members: bool
291
    can_promote_members: bool
292
    can_change_info: bool
293
    can_invite_users: bool
294
    can_pin_messages: bool | None
295
    can_manage_topics: bool | None
296
    is_anonymous: bool
297
    custom_title: str | None
298

299
class ChatMemberMember(ChatMember):
300
    until_date: datetime.datetime | None
301

302
class ChatMemberRestricted(ChatMember):
303
    is_member: bool
304
    can_send_messages: bool
305
    can_send_audios: bool
306
    can_send_documents: bool
307
    can_send_photos: bool
308
    can_send_videos: bool
309
    can_send_video_notes: bool
310
    can_send_voice_notes: bool
311
    can_send_polls: bool
312
    can_send_other_messages: bool
313
    can_add_web_page_previews: bool
314
    can_change_info: bool
315
    can_invite_users: bool
316
    can_pin_messages: bool
317
    can_manage_topics: bool
318
    until_date: datetime.datetime | None
319

320
class ChatMemberLeft(ChatMember):
321
    pass
322

323
class ChatMemberBanned(ChatMember):
324
    until_date: datetime.datetime | None
325

326
class ChatPermissions:
327
    can_send_messages: bool | None
328
    can_send_audios: bool | None
329
    can_send_documents: bool | None
330
    can_send_photos: bool | None
331
    can_send_videos: bool | None
332
    can_send_video_notes: bool | None
333
    can_send_voice_notes: bool | None
334
    can_send_polls: bool | None
335
    can_send_other_messages: bool | None
336
    can_add_web_page_previews: bool | None
337
    can_change_info: bool | None
338
    can_invite_users: bool | None
339
    can_pin_messages: bool | None
340
    can_manage_topics: bool | None
341
```
342

343
### File Types
344

345
Media and file representations.
346

347
```python { .api }
348
class PhotoSize:
349
    file_id: str
350
    file_unique_id: str
351
    width: int
352
    height: int
353
    file_size: int | None
354
    
355
    async def get_file(self, **kwargs) -> File: ...
356

357
class Audio:
358
    file_id: str
359
    file_unique_id: str
360
    duration: int
361
    performer: str | None
362
    title: str | None
363
    file_name: str | None
364
    mime_type: str | None
365
    file_size: int | None
366
    thumbnail: PhotoSize | None
367
    
368
    async def get_file(self, **kwargs) -> File: ...
369

370
class Document:
371
    file_id: str
372
    file_unique_id: str
373
    thumbnail: PhotoSize | None
374
    file_name: str | None
375
    mime_type: str | None
376
    file_size: int | None
377
    
378
    async def get_file(self, **kwargs) -> File: ...
379

380
class Video:
381
    file_id: str
382
    file_unique_id: str
383
    width: int
384
    height: int
385
    duration: int
386
    thumbnail: PhotoSize | None
387
    file_name: str | None
388
    mime_type: str | None
389
    file_size: int | None
390
    
391
    async def get_file(self, **kwargs) -> File: ...
392

393
class Animation:
394
    file_id: str
395
    file_unique_id: str
396
    width: int
397
    height: int
398
    duration: int
399
    thumbnail: PhotoSize | None
400
    file_name: str | None
401
    mime_type: str | None
402
    file_size: int | None
403
    
404
    async def get_file(self, **kwargs) -> File: ...
405

406
class Voice:
407
    file_id: str
408
    file_unique_id: str
409
    duration: int
410
    mime_type: str | None
411
    file_size: int | None
412
    
413
    async def get_file(self, **kwargs) -> File: ...
414

415
class VideoNote:
416
    file_id: str
417
    file_unique_id: str
418
    length: int
419
    duration: int
420
    thumbnail: PhotoSize | None
421
    file_size: int | None
422
    
423
    async def get_file(self, **kwargs) -> File: ...
424

425
class Contact:
426
    phone_number: str
427
    first_name: str
428
    last_name: str | None
429
    user_id: int | None
430
    vcard: str | None
431

432
class Location:
433
    longitude: float
434
    latitude: float
435
    horizontal_accuracy: float | None
436
    live_period: int | None
437
    heading: int | None
438
    proximity_alert_radius: int | None
439

440
class Venue:
441
    location: Location
442
    title: str
443
    address: str
444
    foursquare_id: str | None
445
    foursquare_type: str | None
446
    google_place_id: str | None
447
    google_place_type: str | None
448

449
class File:
450
    file_id: str
451
    file_unique_id: str
452
    file_size: int | None
453
    file_path: str | None
454
    
455
    async def download_to_drive(self, custom_path: str = None) -> str: ...
456
    async def download_as_bytearray(self) -> bytearray: ...
457
```
458

459
### Callback and Inline Types
460

461
Callback queries and inline query handling.
462

463
```python { .api }
464
class CallbackQuery:
465
    id: str
466
    from_user: User
467
    message: MaybeInaccessibleMessage | None
468
    inline_message_id: str | None
469
    chat_instance: str
470
    data: str | None
471
    game_short_name: str | None
472
    
473
    async def answer(self, text: str = None, show_alert: bool = None, url: str = None, cache_time: int = None, **kwargs) -> bool: ...
474
    async def edit_message_text(self, text: str, **kwargs) -> Message | bool: ...
475
    async def edit_message_caption(self, caption: str = None, **kwargs) -> Message | bool: ...
476
    async def edit_message_reply_markup(self, reply_markup: InlineKeyboardMarkup = None, **kwargs) -> Message | bool: ...
477
    async def delete_message(self, **kwargs) -> bool: ...
478

479
class InlineQuery:
480
    id: str
481
    from_user: User
482
    query: str
483
    offset: str
484
    chat_type: str | None
485
    location: Location | None
486
    
487
    async def answer(self, results: list[InlineQueryResult], **kwargs) -> bool: ...
488

489
class ChosenInlineResult:
490
    result_id: str
491
    from_user: User
492
    location: Location | None
493
    inline_message_id: str | None
494
    query: str
495
```
496

497
### Poll Types
498

499
Poll and voting structures.
500

501
```python { .api }
502
class Poll:
503
    id: str
504
    question: str
505
    question_entities: list[MessageEntity] | None
506
    options: list[PollOption]
507
    total_voter_count: int
508
    is_closed: bool
509
    is_anonymous: bool
510
    type: str
511
    allows_multiple_answers: bool
512
    correct_option_id: int | None
513
    explanation: str | None
514
    explanation_entities: list[MessageEntity] | None
515
    open_period: int | None
516
    close_date: datetime.datetime | None
517

518
class PollOption:
519
    text: str
520
    text_entities: list[MessageEntity] | None
521
    voter_count: int
522
    special_entities: list[MessageEntity] | None
523

524
class PollAnswer:
525
    poll_id: str
526
    option_ids: list[int]
527
    voter_chat: Chat | None
528
    user: User | None
529
```
530

531
## Type Hierarchies
532

533
### Message Origin Types
534

535
```python { .api }
536
class MessageOrigin:
537
    type: str
538
    date: datetime.datetime
539

540
class MessageOriginUser(MessageOrigin):
541
    sender_user: User
542

543
class MessageOriginHiddenUser(MessageOrigin):
544
    sender_user_name: str
545

546
class MessageOriginChat(MessageOrigin):
547
    sender_chat: Chat
548
    author_signature: str | None
549

550
class MessageOriginChannel(MessageOrigin):
551
    chat: Chat
552
    message_id: int
553
    author_signature: str | None
554
```
555

556
### Reaction Types
557

558
```python { .api }
559
class ReactionType:
560
    type: str
561

562
class ReactionTypeEmoji(ReactionType):
563
    emoji: str
564

565
class ReactionTypeCustomEmoji(ReactionType):
566
    custom_emoji_id: str
567

568
class ReactionTypePaid(ReactionType):
569
    pass
570
```
571

572
### Background Types
573

574
```python { .api }
575
class BackgroundFill:
576
    type: str
577

578
class BackgroundFillSolid(BackgroundFill):
579
    color: int
580

581
class BackgroundFillGradient(BackgroundFill):
582
    top_color: int
583
    bottom_color: int
584
    rotation_angle: int
585

586
class BackgroundFillFreeformGradient(BackgroundFill):
587
    colors: list[int]
588

589
class BackgroundType:
590
    type: str
591

592
class BackgroundTypeFill(BackgroundType):
593
    fill: BackgroundFill
594
    dark_theme_dimming: int
595

596
class BackgroundTypeWallpaper(BackgroundType):
597
    document: Document
598
    dark_theme_dimming: int
599
    is_blurred: bool | None
600
    is_moving: bool | None
601

602
class BackgroundTypePattern(BackgroundType):
603
    document: Document
604
    fill: BackgroundFill
605
    intensity: int
606
    is_inverted: bool | None
607
    is_moving: bool | None
608

609
class BackgroundTypeChatTheme(BackgroundType):
610
    theme_name: str
611

612
class ChatBackground:
613
    type: BackgroundType
614
```
615

616
### Transaction Types
617

618
```python { .api }
619
class TransactionPartner:
620
    type: str
621

622
class TransactionPartnerUser(TransactionPartner):
623
    user: User
624
    invoice_payload: str | None
625
    subscription_period: int | None
626
    paid_media: list[PaidMedia] | None
627
    paid_media_payload: str | None
628

629
class TransactionPartnerFragment(TransactionPartner):
630
    withdrawal_state: RevenueWithdrawalState | None
631

632
class TransactionPartnerTelegramAds(TransactionPartner):
633
    pass
634

635
class TransactionPartnerTelegramApi(TransactionPartner):
636
    request_count: int
637

638
class TransactionPartnerOther(TransactionPartner):
639
    pass
640

641
class TransactionPartnerChat(TransactionPartner):
642
    chat: Chat
643
    invoice_payload: str | None
644

645
class TransactionPartnerAffiliateProgram(TransactionPartner):
646
    commission_per_mille: int
647

648
class AffiliateInfo:
649
    affiliate_user: User | None
650
    affiliate_chat: Chat | None
651
    commission_per_mille: int
652
    amount: int
653
    nanostar_amount: int | None
654

655
class StarTransaction:
656
    id: str
657
    amount: int
658
    nanostar_amount: int | None
659
    date: datetime.datetime
660
    source: TransactionPartner | None
661
    receiver: TransactionPartner | None
662

663
class StarTransactions:
664
    transactions: list[StarTransaction]
665

666
class RevenueWithdrawalState:
667
    type: str
668

669
class RevenueWithdrawalStatePending(RevenueWithdrawalState):
670
    pass
671

672
class RevenueWithdrawalStateSucceeded(RevenueWithdrawalState):
673
    date: datetime.datetime
674
    url: str
675

676
class RevenueWithdrawalStateFailed(RevenueWithdrawalState):
677
    pass
678
```
679

680
### Business Types
681

682
```python { .api }
683
class BusinessConnection:
684
    id: str
685
    user: User
686
    user_chat_id: int
687
    date: datetime.datetime
688
    can_reply: bool
689
    is_enabled: bool
690

691
class BusinessIntro:
692
    title: str | None
693
    message: str | None
694
    sticker: Sticker | None
695

696
class BusinessLocation:
697
    address: str
698
    location: Location | None
699

700
class BusinessOpeningHours:
701
    time_zone_name: str
702
    opening_hours: list[BusinessOpeningHoursInterval]
703

704
class BusinessOpeningHoursInterval:
705
    opening_minute: int
706
    closing_minute: int
707

708
class BusinessMessagesDeleted:
709
    business_connection_id: str
710
    chat: Chat
711
    message_ids: list[int]
712
```
713

714
### Gift Types
715

716
```python { .api }
717
class Gift:
718
    id: str
719
    sticker: Sticker
720
    star_count: int
721
    total_count: int | None
722
    remaining_count: int | None
723

724
class Gifts:
725
    gifts: list[Gift]
726
```
727

728
### Birthdate Type
729

730
```python { .api }
731
class Birthdate:
732
    day: int
733
    month: int
734
    year: int | None
735
```