0
# Bot API
1

2
The Bot class provides direct access to all Telegram Bot API methods. It handles HTTP requests, response parsing, and file operations while maintaining full compatibility with the official Telegram Bot API.
3

4
## Capabilities
5

6
### Bot Initialization
7

8
Create and configure a Bot instance with authentication token and optional settings.
9

10
```python { .api }
11
class Bot:
12
    def __init__(
13
        self,
14
        token: str,
15
        base_url: str = "https://api.telegram.org/bot",
16
        base_file_url: str = "https://api.telegram.org/file/bot",
17
        request: BaseRequest = None,
18
        get_updates_request: BaseRequest = None,
19
        private_key: bytes = None,
20
        private_key_password: bytes = None,
21
        local_mode: bool = False
22
    ): ...
23
```
24

25
Usage example:
26

27
```python
28
from telegram import Bot
29

30
# Basic initialization
31
bot = Bot(token="YOUR_BOT_TOKEN")
32

33
# With custom configuration
34
from telegram.request import HTTPXRequest
35
bot = Bot(
36
    token="YOUR_BOT_TOKEN",
37
    request=HTTPXRequest(connection_pool_size=8)
38
)
39
```
40

41
### Sending Messages
42

43
Send text messages with formatting, reply parameters, and keyboard attachments.
44

45
```python { .api }
46
async def send_message(
47
    self,
48
    chat_id: int | str,
49
    text: str,
50
    parse_mode: str = None,
51
    entities: list[MessageEntity] = None,
52
    link_preview_options: LinkPreviewOptions = None,
53
    disable_notification: bool = None,
54
    protect_content: bool = None,
55
    reply_parameters: ReplyParameters = None,
56
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
57
    message_thread_id: int = None,
58
    business_connection_id: str = None
59
) -> Message: ...
60
```
61

62
Usage example:
63

64
```python
65
from telegram.constants import ParseMode
66

67
# Simple text message
68
message = await bot.send_message(chat_id=123456, text="Hello World!")
69

70
# Formatted message with keyboard
71
from telegram import InlineKeyboardMarkup, InlineKeyboardButton
72

73
keyboard = InlineKeyboardMarkup([
74
    [InlineKeyboardButton("Option 1", callback_data="opt1")]
75
])
76

77
message = await bot.send_message(
78
    chat_id=123456,
79
    text="Choose an option:",
80
    parse_mode=ParseMode.MARKDOWN_V2,
81
    reply_markup=keyboard
82
)
83
```
84

85
### Sending Media
86

87
Send photos, videos, documents, audio files, and other media with captions and formatting.
88

89
```python { .api }
90
async def send_photo(
91
    self,
92
    chat_id: int | str,
93
    photo: InputFile | str,
94
    caption: str = None,
95
    parse_mode: str = None,
96
    caption_entities: list[MessageEntity] = None,
97
    show_caption_above_media: bool = None,
98
    has_spoiler: bool = None,
99
    disable_notification: bool = None,
100
    protect_content: bool = None,
101
    reply_parameters: ReplyParameters = None,
102
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
103
    message_thread_id: int = None,
104
    business_connection_id: str = None
105
) -> Message: ...
106

107
async def send_video(
108
    self,
109
    chat_id: int | str,
110
    video: InputFile | str,
111
    duration: int = None,
112
    width: int = None,
113
    height: int = None,
114
    thumbnail: InputFile | str = None,
115
    caption: str = None,
116
    parse_mode: str = None,
117
    caption_entities: list[MessageEntity] = None,
118
    show_caption_above_media: bool = None,
119
    has_spoiler: bool = None,
120
    supports_streaming: bool = None,
121
    disable_notification: bool = None,
122
    protect_content: bool = None,
123
    reply_parameters: ReplyParameters = None,
124
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
125
    message_thread_id: int = None,
126
    business_connection_id: str = None
127
) -> Message: ...
128

129
async def send_document(
130
    self,
131
    chat_id: int | str,
132
    document: InputFile | str,
133
    thumbnail: InputFile | str = None,
134
    caption: str = None,
135
    parse_mode: str = None,
136
    caption_entities: list[MessageEntity] = None,
137
    disable_content_type_detection: bool = None,
138
    disable_notification: bool = None,
139
    protect_content: bool = None,
140
    reply_parameters: ReplyParameters = None,
141
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
142
    message_thread_id: int = None,
143
    business_connection_id: str = None
144
) -> Message: ...
145

146
async def send_audio(
147
    self,
148
    chat_id: int | str,
149
    audio: InputFile | str,
150
    caption: str = None,
151
    parse_mode: str = None,
152
    caption_entities: list[MessageEntity] = None,
153
    duration: int = None,
154
    performer: str = None,
155
    title: str = None,
156
    thumbnail: InputFile | str = None,
157
    disable_notification: bool = None,
158
    protect_content: bool = None,
159
    reply_parameters: ReplyParameters = None,
160
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
161
    message_thread_id: int = None,
162
    business_connection_id: str = None
163
) -> Message: ...
164

165
async def send_voice(
166
    self,
167
    chat_id: int | str,
168
    voice: InputFile | str,
169
    duration: int = None,
170
    caption: str = None,
171
    parse_mode: str = None,
172
    caption_entities: list[MessageEntity] = None,
173
    disable_notification: bool = None,
174
    protect_content: bool = None,
175
    reply_parameters: ReplyParameters = None,
176
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
177
    message_thread_id: int = None,
178
    business_connection_id: str = None
179
) -> Message: ...
180

181
async def send_video_note(
182
    self,
183
    chat_id: int | str,
184
    video_note: InputFile | str,
185
    duration: int = None,
186
    length: int = None,
187
    thumbnail: InputFile | str = None,
188
    disable_notification: bool = None,
189
    protect_content: bool = None,
190
    reply_parameters: ReplyParameters = None,
191
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
192
    message_thread_id: int = None,
193
    business_connection_id: str = None
194
) -> Message: ...
195

196
async def send_animation(
197
    self,
198
    chat_id: int | str,
199
    animation: InputFile | str,
200
    duration: int = None,
201
    width: int = None,
202
    height: int = None,
203
    thumbnail: InputFile | str = None,
204
    caption: str = None,
205
    parse_mode: str = None,
206
    caption_entities: list[MessageEntity] = None,
207
    has_spoiler: bool = None,
208
    disable_notification: bool = None,
209
    protect_content: bool = None,
210
    reply_parameters: ReplyParameters = None,
211
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
212
    message_thread_id: int = None,
213
    business_connection_id: str = None
214
) -> Message: ...
215

216
async def send_sticker(
217
    self,
218
    chat_id: int | str,
219
    sticker: InputFile | str,
220
    emoji: str = None,
221
    disable_notification: bool = None,
222
    protect_content: bool = None,
223
    reply_parameters: ReplyParameters = None,
224
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
225
    message_thread_id: int = None,
226
    business_connection_id: str = None
227
) -> Message: ...
228
```
229

230
Usage examples:
231

232
```python
233
# Send a voice message
234
with open("voice.ogg", "rb") as voice_file:
235
    await bot.send_voice(chat_id=123456, voice=voice_file, caption="Voice message")
236

237
# Send an animation (GIF)
238
await bot.send_animation(
239
    chat_id=123456, 
240
    animation="https://example.com/animation.gif",
241
    caption="Check this out!"
242
)
243

244
# Send a sticker
245
await bot.send_sticker(chat_id=123456, sticker="CAACAgIAAxkBAAI...")
246

247
# Send a video note (circular video)
248
with open("video_note.mp4", "rb") as video_file:
249
    await bot.send_video_note(chat_id=123456, video_note=video_file, duration=30)
250
```
251

252
### Sending Location & Contacts
253

254
Send location data, venue information, and contact details.
255

256
```python { .api }
257
async def send_location(
258
    self,
259
    chat_id: int | str,
260
    latitude: float,
261
    longitude: float,
262
    horizontal_accuracy: float = None,
263
    live_period: int = None,
264
    heading: int = None,
265
    proximity_alert_radius: int = None,
266
    disable_notification: bool = None,
267
    protect_content: bool = None,
268
    reply_parameters: ReplyParameters = None,
269
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
270
    message_thread_id: int = None,
271
    business_connection_id: str = None
272
) -> Message: ...
273

274
async def send_venue(
275
    self,
276
    chat_id: int | str,
277
    latitude: float,
278
    longitude: float,
279
    title: str,
280
    address: str,
281
    foursquare_id: str = None,
282
    foursquare_type: str = None,
283
    google_place_id: str = None,
284
    google_place_type: str = None,
285
    disable_notification: bool = None,
286
    protect_content: bool = None,
287
    reply_parameters: ReplyParameters = None,
288
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
289
    message_thread_id: int = None,
290
    business_connection_id: str = None
291
) -> Message: ...
292

293
async def send_contact(
294
    self,
295
    chat_id: int | str,
296
    phone_number: str,
297
    first_name: str,
298
    last_name: str = None,
299
    vcard: str = None,
300
    disable_notification: bool = None,
301
    protect_content: bool = None,
302
    reply_parameters: ReplyParameters = None,
303
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
304
    message_thread_id: int = None,
305
    business_connection_id: str = None
306
) -> Message: ...
307
```
308

309
Usage examples:
310

311
```python
312
# Send current location
313
await bot.send_location(
314
    chat_id=123456, 
315
    latitude=37.7749, 
316
    longitude=-122.4194
317
)
318

319
# Send live location that updates for 1 hour
320
await bot.send_location(
321
    chat_id=123456,
322
    latitude=37.7749,
323
    longitude=-122.4194,
324
    live_period=3600,  # 1 hour in seconds
325
    horizontal_accuracy=50
326
)
327

328
# Send venue information
329
await bot.send_venue(
330
    chat_id=123456,
331
    latitude=37.7749,
332
    longitude=-122.4194,
333
    title="Golden Gate Park",
334
    address="San Francisco, CA, USA",
335
    foursquare_id="49e3a8c3f964a520fd1a1fe3"
336
)
337

338
# Send contact information
339
await bot.send_contact(
340
    chat_id=123456,
341
    phone_number="+1234567890",
342
    first_name="John",
343
    last_name="Doe",
344
    vcard="BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nTEL:+1234567890\nEND:VCARD"
345
)
346
```
347

348
### Getting Updates
349

350
Retrieve incoming updates using polling or webhook methods.
351

352
```python { .api }
353
async def get_updates(
354
    self,
355
    offset: int = None,
356
    limit: int = None,
357
    timeout: int = None,
358
    allowed_updates: list[str] = None
359
) -> list[Update]: ...
360

361
async def set_webhook(
362
    self,
363
    url: str,
364
    certificate: InputFile = None,
365
    ip_address: str = None,
366
    max_connections: int = None,
367
    allowed_updates: list[str] = None,
368
    drop_pending_updates: bool = None,
369
    secret_token: str = None
370
) -> bool: ...
371

372
async def delete_webhook(self, drop_pending_updates: bool = None) -> bool: ...
373

374
async def get_webhook_info(self) -> WebhookInfo: ...
375
```
376

377
### Bot Information
378

379
Get information about the bot and manage bot settings.
380

381
```python { .api }
382
async def get_me(self) -> User: ...
383

384
async def log_out(self) -> bool: ...
385

386
async def close(self) -> bool: ...
387

388
async def set_my_commands(
389
    self,
390
    commands: list[BotCommand],
391
    scope: BotCommandScope = None,
392
    language_code: str = None
393
) -> bool: ...
394

395
async def delete_my_commands(
396
    self,
397
    scope: BotCommandScope = None,
398
    language_code: str = None
399
) -> bool: ...
400

401
async def get_my_commands(
402
    self,
403
    scope: BotCommandScope = None,
404
    language_code: str = None
405
) -> list[BotCommand]: ...
406
```
407

408
### Chat Management
409

410
Manage chat members, permissions, and chat settings.
411

412
```python { .api }
413
async def get_chat(self, chat_id: int | str) -> ChatFullInfo: ...
414

415
async def get_chat_administrators(self, chat_id: int | str) -> list[ChatMember]: ...
416

417
async def get_chat_member_count(self, chat_id: int | str) -> int: ...
418

419
async def get_chat_member(self, chat_id: int | str, user_id: int) -> ChatMember: ...
420

421
async def set_chat_sticker_set(self, chat_id: int | str, sticker_set_name: str) -> bool: ...
422

423
async def delete_chat_sticker_set(self, chat_id: int | str) -> bool: ...
424

425
async def ban_chat_member(
426
    self,
427
    chat_id: int | str,
428
    user_id: int,
429
    until_date: int = None,
430
    revoke_messages: bool = None
431
) -> bool: ...
432

433
async def unban_chat_member(
434
    self,
435
    chat_id: int | str,
436
    user_id: int,
437
    only_if_banned: bool = None
438
) -> bool: ...
439

440
async def restrict_chat_member(
441
    self,
442
    chat_id: int | str,
443
    user_id: int,
444
    permissions: ChatPermissions,
445
    use_independent_chat_permissions: bool = None,
446
    until_date: int = None
447
) -> bool: ...
448

449
async def promote_chat_member(
450
    self,
451
    chat_id: int | str,
452
    user_id: int,
453
    is_anonymous: bool = None,
454
    can_manage_chat: bool = None,
455
    can_post_messages: bool = None,
456
    can_edit_messages: bool = None,
457
    can_delete_messages: bool = None,
458
    can_manage_video_chats: bool = None,
459
    can_restrict_members: bool = None,
460
    can_promote_members: bool = None,
461
    can_change_info: bool = None,
462
    can_invite_users: bool = None,
463
    can_pin_messages: bool = None,
464
    can_manage_topics: bool = None
465
) -> bool: ...
466

467
async def set_chat_title(
468
    self,
469
    chat_id: int | str,
470
    title: str
471
) -> bool: ...
472

473
async def set_chat_description(
474
    self,
475
    chat_id: int | str,
476
    description: str = None
477
) -> bool: ...
478

479
async def pin_chat_message(
480
    self,
481
    chat_id: int | str,
482
    message_id: int,
483
    disable_notification: bool = None,
484
    business_connection_id: str = None
485
) -> bool: ...
486

487
async def unpin_chat_message(
488
    self,
489
    chat_id: int | str,
490
    message_id: int = None,
491
    business_connection_id: str = None
492
) -> bool: ...
493
```
494

495
Usage examples:
496

497
```python
498
# Update chat title
499
await bot.set_chat_title(chat_id=-123456789, title="New Group Title")
500

501
# Update chat description
502
await bot.set_chat_description(
503
    chat_id=-123456789, 
504
    description="This is the new group description"
505
)
506

507
# Clear description by passing None
508
await bot.set_chat_description(chat_id=-123456789, description=None)
509

510
# Pin a message
511
await bot.pin_chat_message(chat_id=-123456789, message_id=12345)
512

513
# Unpin a specific message
514
await bot.unpin_chat_message(chat_id=-123456789, message_id=12345)
515

516
# Unpin most recent pinned message
517
await bot.unpin_chat_message(chat_id=-123456789)
518
```
519

520
### File Operations
521

522
Download files and get file information.
523

524
```python { .api }
525
async def get_file(self, file_id: str) -> File: ...
526
```
527

528
Usage example:
529

530
```python
531
# Get file object and download
532
file = await bot.get_file(file_id="BAADBAADrwADBREAAYdaO-...")
533
await file.download_to_drive("downloaded_file.jpg")
534
```
535

536
### Message Operations
537

538
Edit, forward, copy, and delete messages.
539

540
```python { .api }
541
async def edit_message_text(
542
    self,
543
    text: str,
544
    chat_id: int | str = None,
545
    message_id: int = None,
546
    inline_message_id: str = None,
547
    parse_mode: str = None,
548
    entities: list[MessageEntity] = None,
549
    link_preview_options: LinkPreviewOptions = None,
550
    reply_markup: InlineKeyboardMarkup = None
551
) -> Message | bool: ...
552

553
async def edit_message_caption(
554
    self,
555
    chat_id: int | str = None,
556
    message_id: int = None,
557
    inline_message_id: str = None,
558
    caption: str = None,
559
    parse_mode: str = None,
560
    caption_entities: list[MessageEntity] = None,
561
    show_caption_above_media: bool = None,
562
    reply_markup: InlineKeyboardMarkup = None
563
) -> Message | bool: ...
564

565
async def edit_message_reply_markup(
566
    self,
567
    chat_id: int | str = None,
568
    message_id: int = None,
569
    inline_message_id: str = None,
570
    reply_markup: InlineKeyboardMarkup = None
571
) -> Message | bool: ...
572

573
async def delete_message(self, chat_id: int | str, message_id: int) -> bool: ...
574

575
async def forward_message(
576
    self,
577
    chat_id: int | str,
578
    from_chat_id: int | str,
579
    message_id: int,
580
    disable_notification: bool = None,
581
    protect_content: bool = None,
582
    message_thread_id: int = None
583
) -> Message: ...
584

585
async def copy_message(
586
    self,
587
    chat_id: int | str,
588
    from_chat_id: int | str,
589
    message_id: int,
590
    caption: str = None,
591
    parse_mode: str = None,
592
    caption_entities: list[MessageEntity] = None,
593
    show_caption_above_media: bool = None,
594
    disable_notification: bool = None,
595
    protect_content: bool = None,
596
    reply_parameters: ReplyParameters = None,
597
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
598
    message_thread_id: int = None
599
) -> MessageId: ...
600
```
601

602
### Inline Queries
603

604
Handle inline query results and prepared inline messages.
605

606
```python { .api }
607
async def answer_inline_query(
608
    self,
609
    inline_query_id: str,
610
    results: list[InlineQueryResult],
611
    cache_time: int = None,
612
    is_personal: bool = None,
613
    next_offset: str = None,
614
    button: InlineQueryResultsButton = None
615
) -> bool: ...
616

617
async def save_prepared_inline_message(
618
    self,
619
    user_id: int,
620
    result: InlineQueryResult,
621
    allow_user_chats: bool = None,
622
    allow_bot_chats: bool = None,
623
    allow_group_chats: bool = None,
624
    allow_channel_chats: bool = None
625
) -> PreparedInlineMessage: ...
626
```
627

628
### Callback Queries
629

630
Answer callback queries from inline keyboard buttons.
631

632
```python { .api }
633
async def answer_callback_query(
634
    self,
635
    callback_query_id: str,
636
    text: str = None,
637
    show_alert: bool = None,
638
    url: str = None,
639
    cache_time: int = None
640
) -> bool: ...
641
```
642

643
## Types
644

645
```python { .api }
646
class BotCommand:
647
    command: str
648
    description: str
649
    def __init__(self, command: str, description: str): ...
650

651
class BotCommandScope:
652
    type: str
653

654
class BotCommandScopeDefault(BotCommandScope):
655
    def __init__(self): ...
656

657
class BotCommandScopeAllPrivateChats(BotCommandScope):
658
    def __init__(self): ...
659

660
class BotCommandScopeAllGroupChats(BotCommandScope):
661
    def __init__(self): ...
662

663
class BotCommandScopeAllChatAdministrators(BotCommandScope):
664
    def __init__(self): ...
665

666
class BotCommandScopeChat(BotCommandScope):
667
    chat_id: int | str
668
    def __init__(self, chat_id: int | str): ...
669

670
class BotCommandScopeChatAdministrators(BotCommandScope):
671
    chat_id: int | str
672
    def __init__(self, chat_id: int | str): ...
673

674
class BotCommandScopeChatMember(BotCommandScope):
675
    chat_id: int | str
676
    user_id: int
677
    def __init__(self, chat_id: int | str, user_id: int): ...
678

679
class WebhookInfo:
680
    url: str
681
    has_custom_certificate: bool
682
    pending_update_count: int
683
    ip_address: str | None
684
    last_error_date: int | None
685
    last_error_message: str | None
686
    last_synchronization_error_date: int | None
687
    max_connections: int | None
688
    allowed_updates: list[str] | None
689
```