0
# API Methods
1
2
Complete coverage of all 162+ Telegram Bot API methods for sending messages, managing chats, handling payments, games, stickers, and webhooks. All methods are accessible through the Bot instance with automatic serialization and type safety.
3
4
## Capabilities
5
6
### Message Operations
7
8
Methods for sending, editing, and managing messages.
9
10
```python { .api }
11
async def send_message(
12
chat_id: int | str,
13
text: str,
14
business_connection_id: str | None = None,
15
message_thread_id: int | None = None,
16
direct_messages_topic_id: int | None = None,
17
parse_mode: str | None = None,
18
entities: list[MessageEntity] | None = None,
19
link_preview_options: LinkPreviewOptions | None = None,
20
disable_notification: bool | None = None,
21
protect_content: bool | None = None,
22
allow_paid_broadcast: bool | None = None,
23
message_effect_id: str | None = None,
24
reply_parameters: ReplyParameters | None = None,
25
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
26
) -> Message:
27
"""Send text messages"""
28
29
async def send_photo(
30
chat_id: int | str,
31
photo: InputFile | str,
32
business_connection_id: str | None = None,
33
message_thread_id: int | None = None,
34
direct_messages_topic_id: int | None = None,
35
caption: str | None = None,
36
parse_mode: str | None = None,
37
caption_entities: list[MessageEntity] | None = None,
38
show_caption_above_media: bool | None = None,
39
has_spoiler: bool | None = None,
40
disable_notification: bool | None = None,
41
protect_content: bool | None = None,
42
allow_paid_broadcast: bool | None = None,
43
message_effect_id: str | None = None,
44
suggested_post_parameters: SuggestedPostParameters | None = None,
45
reply_parameters: ReplyParameters | None = None,
46
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
47
) -> Message:
48
"""Send photos"""
49
50
async def send_audio(
51
chat_id: int | str,
52
audio: InputFile | str,
53
caption: str | None = None,
54
parse_mode: str | None = None,
55
caption_entities: list[MessageEntity] | None = None,
56
duration: int | None = None,
57
performer: str | None = None,
58
title: str | None = None,
59
thumbnail: InputFile | str | None = None,
60
disable_notification: bool | None = None,
61
protect_content: bool | None = None,
62
reply_to_message_id: int | None = None,
63
allow_sending_without_reply: bool | None = None,
64
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
65
) -> Message:
66
"""Send audio files"""
67
68
async def send_document(
69
chat_id: int | str,
70
document: InputFile | str,
71
thumbnail: InputFile | str | None = None,
72
caption: str | None = None,
73
parse_mode: str | None = None,
74
caption_entities: list[MessageEntity] | None = None,
75
disable_content_type_detection: bool | None = None,
76
disable_notification: bool | None = None,
77
protect_content: bool | None = None,
78
reply_to_message_id: int | None = None,
79
allow_sending_without_reply: bool | None = None,
80
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
81
) -> Message:
82
"""Send general files"""
83
84
async def send_video(
85
chat_id: int | str,
86
video: InputFile | str,
87
duration: int | None = None,
88
width: int | None = None,
89
height: int | None = None,
90
thumbnail: InputFile | str | None = None,
91
caption: str | None = None,
92
parse_mode: str | None = None,
93
caption_entities: list[MessageEntity] | None = None,
94
has_spoiler: bool | None = None,
95
supports_streaming: bool | None = None,
96
disable_notification: bool | None = None,
97
protect_content: bool | None = None,
98
reply_to_message_id: int | None = None,
99
allow_sending_without_reply: bool | None = None,
100
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
101
) -> Message:
102
"""Send video files"""
103
104
async def send_animation(
105
chat_id: int | str,
106
animation: InputFile | str,
107
duration: int | None = None,
108
width: int | None = None,
109
height: int | None = None,
110
thumbnail: InputFile | str | None = None,
111
caption: str | None = None,
112
parse_mode: str | None = None,
113
caption_entities: list[MessageEntity] | None = None,
114
has_spoiler: bool | None = None,
115
disable_notification: bool | None = None,
116
protect_content: bool | None = None,
117
reply_to_message_id: int | None = None,
118
allow_sending_without_reply: bool | None = None,
119
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
120
) -> Message:
121
"""Send animation files (GIF or H.264/MPEG-4 AVC video without sound)"""
122
123
async def send_voice(
124
chat_id: int | str,
125
voice: InputFile | str,
126
caption: str | None = None,
127
parse_mode: str | None = None,
128
caption_entities: list[MessageEntity] | None = None,
129
duration: int | None = None,
130
disable_notification: bool | None = None,
131
protect_content: bool | None = None,
132
reply_to_message_id: int | None = None,
133
allow_sending_without_reply: bool | None = None,
134
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
135
) -> Message:
136
"""Send voice messages"""
137
138
async def send_video_note(
139
chat_id: int | str,
140
video_note: InputFile | str,
141
duration: int | None = None,
142
length: int | None = None,
143
thumbnail: InputFile | str | None = None,
144
disable_notification: bool | None = None,
145
protect_content: bool | None = None,
146
reply_to_message_id: int | None = None,
147
allow_sending_without_reply: bool | None = None,
148
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
149
) -> Message:
150
"""Send video messages (circular videos)"""
151
152
async def send_media_group(
153
chat_id: int | str,
154
media: list[InputMediaAudio | InputMediaDocument | InputMediaPhoto | InputMediaVideo],
155
disable_notification: bool | None = None,
156
protect_content: bool | None = None,
157
reply_to_message_id: int | None = None,
158
allow_sending_without_reply: bool | None = None
159
) -> list[Message]:
160
"""Send a group of photos, videos, documents or audios as an album"""
161
162
async def send_location(
163
chat_id: int | str,
164
latitude: float,
165
longitude: float,
166
horizontal_accuracy: float | None = None,
167
live_period: int | None = None,
168
heading: int | None = None,
169
proximity_alert_radius: int | None = None,
170
disable_notification: bool | None = None,
171
protect_content: bool | None = None,
172
reply_to_message_id: int | None = None,
173
allow_sending_without_reply: bool | None = None,
174
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
175
) -> Message:
176
"""Send point on the map"""
177
178
async def send_venue(
179
chat_id: int | str,
180
latitude: float,
181
longitude: float,
182
title: str,
183
address: str,
184
foursquare_id: str | None = None,
185
foursquare_type: str | None = None,
186
google_place_id: str | None = None,
187
google_place_type: str | None = None,
188
disable_notification: bool | None = None,
189
protect_content: bool | None = None,
190
reply_to_message_id: int | None = None,
191
allow_sending_without_reply: bool | None = None,
192
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
193
) -> Message:
194
"""Send information about a venue"""
195
196
async def send_contact(
197
chat_id: int | str,
198
phone_number: str,
199
first_name: str,
200
last_name: str | None = None,
201
vcard: str | None = None,
202
disable_notification: bool | None = None,
203
protect_content: bool | None = None,
204
reply_to_message_id: int | None = None,
205
allow_sending_without_reply: bool | None = None,
206
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
207
) -> Message:
208
"""Send phone contacts"""
209
210
async def send_poll(
211
chat_id: int | str,
212
question: str,
213
options: list[str],
214
is_anonymous: bool | None = None,
215
type: str | None = None,
216
allows_multiple_answers: bool | None = None,
217
correct_option_id: int | None = None,
218
explanation: str | None = None,
219
explanation_parse_mode: str | None = None,
220
explanation_entities: list[MessageEntity] | None = None,
221
open_period: int | None = None,
222
close_date: datetime.datetime | None = None,
223
is_closed: bool | None = None,
224
disable_notification: bool | None = None,
225
protect_content: bool | None = None,
226
reply_to_message_id: int | None = None,
227
allow_sending_without_reply: bool | None = None,
228
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
229
) -> Message:
230
"""Send native polls"""
231
232
async def send_dice(
233
chat_id: int | str,
234
emoji: str | None = None,
235
disable_notification: bool | None = None,
236
protect_content: bool | None = None,
237
reply_to_message_id: int | None = None,
238
allow_sending_without_reply: bool | None = None,
239
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
240
) -> Message:
241
"""Send animated emoji that will display a random value"""
242
```
243
244
### Message Editing
245
246
Methods for editing existing messages.
247
248
```python { .api }
249
async def edit_message_text(
250
text: str,
251
chat_id: int | str | None = None,
252
message_id: int | None = None,
253
inline_message_id: str | None = None,
254
parse_mode: str | None = None,
255
entities: list[MessageEntity] | None = None,
256
disable_web_page_preview: bool | None = None,
257
reply_markup: InlineKeyboardMarkup | None = None
258
) -> Message | bool:
259
"""Edit text and game messages"""
260
261
async def edit_message_caption(
262
chat_id: int | str | None = None,
263
message_id: int | None = None,
264
inline_message_id: str | None = None,
265
caption: str | None = None,
266
parse_mode: str | None = None,
267
caption_entities: list[MessageEntity] | None = None,
268
reply_markup: InlineKeyboardMarkup | None = None
269
) -> Message | bool:
270
"""Edit captions of messages"""
271
272
async def edit_message_media(
273
media: InputMedia,
274
chat_id: int | str | None = None,
275
message_id: int | None = None,
276
inline_message_id: str | None = None,
277
reply_markup: InlineKeyboardMarkup | None = None
278
) -> Message | bool:
279
"""Edit animation, audio, document, photo, or video messages"""
280
281
async def edit_message_reply_markup(
282
chat_id: int | str | None = None,
283
message_id: int | None = None,
284
inline_message_id: str | None = None,
285
reply_markup: InlineKeyboardMarkup | None = None
286
) -> Message | bool:
287
"""Edit only the reply markup of messages"""
288
289
async def edit_message_live_location(
290
latitude: float,
291
longitude: float,
292
chat_id: int | str | None = None,
293
message_id: int | None = None,
294
inline_message_id: str | None = None,
295
horizontal_accuracy: float | None = None,
296
heading: int | None = None,
297
proximity_alert_radius: int | None = None,
298
reply_markup: InlineKeyboardMarkup | None = None
299
) -> Message | bool:
300
"""Edit live location messages"""
301
302
async def stop_message_live_location(
303
chat_id: int | str | None = None,
304
message_id: int | None = None,
305
inline_message_id: str | None = None,
306
reply_markup: InlineKeyboardMarkup | None = None
307
) -> Message | bool:
308
"""Stop updating a live location message"""
309
```
310
311
### Message Management
312
313
Methods for managing messages (delete, forward, copy).
314
315
```python { .api }
316
async def delete_message(chat_id: int | str, message_id: int) -> bool:
317
"""Delete a message"""
318
319
async def delete_messages(chat_id: int | str, message_ids: list[int]) -> bool:
320
"""Delete multiple messages simultaneously"""
321
322
async def forward_message(
323
chat_id: int | str,
324
from_chat_id: int | str,
325
message_id: int,
326
disable_notification: bool | None = None,
327
protect_content: bool | None = None
328
) -> Message:
329
"""Forward messages of any kind"""
330
331
async def forward_messages(
332
chat_id: int | str,
333
from_chat_id: int | str,
334
message_ids: list[int],
335
disable_notification: bool | None = None,
336
protect_content: bool | None = None
337
) -> list[MessageId]:
338
"""Forward multiple messages of any kind"""
339
340
async def copy_message(
341
chat_id: int | str,
342
from_chat_id: int | str,
343
message_id: int,
344
caption: str | None = None,
345
parse_mode: str | None = None,
346
caption_entities: list[MessageEntity] | None = None,
347
disable_notification: bool | None = None,
348
protect_content: bool | None = None,
349
reply_to_message_id: int | None = None,
350
allow_sending_without_reply: bool | None = None,
351
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
352
) -> MessageId:
353
"""Copy messages of any kind"""
354
355
async def copy_messages(
356
chat_id: int | str,
357
from_chat_id: int | str,
358
message_ids: list[int],
359
disable_notification: bool | None = None,
360
protect_content: bool | None = None,
361
remove_caption: bool | None = None
362
) -> list[MessageId]:
363
"""Copy multiple messages of any kind"""
364
```
365
366
### Chat Information
367
368
Methods for retrieving chat and member information.
369
370
```python { .api }
371
async def get_chat(chat_id: int | str) -> Chat:
372
"""Get up to date information about the chat"""
373
374
async def get_chat_administrators(chat_id: int | str) -> list[ChatMember]:
375
"""Get a list of administrators in a chat"""
376
377
async def get_chat_member_count(chat_id: int | str) -> int:
378
"""Get the number of members in a chat"""
379
380
async def get_chat_member(chat_id: int | str, user_id: int) -> ChatMember:
381
"""Get information about a member of a chat"""
382
383
async def get_chat_menu_button(chat_id: int | None = None) -> MenuButton:
384
"""Get the current value of the bot's menu button in a private chat"""
385
```
386
387
### Chat Management
388
389
Methods for managing chat members and permissions.
390
391
```python { .api }
392
async def ban_chat_member(
393
chat_id: int | str,
394
user_id: int,
395
until_date: datetime.datetime | None = None,
396
revoke_messages: bool | None = None
397
) -> bool:
398
"""Ban a user in a group, a supergroup or a channel"""
399
400
async def unban_chat_member(
401
chat_id: int | str,
402
user_id: int,
403
only_if_banned: bool | None = None
404
) -> bool:
405
"""Unban a previously banned user in a supergroup or channel"""
406
407
async def restrict_chat_member(
408
chat_id: int | str,
409
user_id: int,
410
permissions: ChatPermissions,
411
use_independent_chat_permissions: bool | None = None,
412
until_date: datetime.datetime | None = None
413
) -> bool:
414
"""Restrict a user in a supergroup"""
415
416
async def promote_chat_member(
417
chat_id: int | str,
418
user_id: int,
419
is_anonymous: bool | None = None,
420
can_manage_chat: bool | None = None,
421
can_delete_messages: bool | None = None,
422
can_manage_video_chats: bool | None = None,
423
can_restrict_members: bool | None = None,
424
can_promote_members: bool | None = None,
425
can_change_info: bool | None = None,
426
can_invite_users: bool | None = None,
427
can_post_messages: bool | None = None,
428
can_edit_messages: bool | None = None,
429
can_pin_messages: bool | None = None,
430
can_manage_topics: bool | None = None
431
) -> bool:
432
"""Promote or demote a user in a supergroup or a channel"""
433
434
async def set_chat_administrator_custom_title(
435
chat_id: int | str,
436
user_id: int,
437
custom_title: str
438
) -> bool:
439
"""Set a custom title for an administrator in a supergroup promoted by the bot"""
440
441
async def set_chat_permissions(
442
chat_id: int | str,
443
permissions: ChatPermissions,
444
use_independent_chat_permissions: bool | None = None
445
) -> bool:
446
"""Set default chat permissions for all members"""
447
```
448
449
### Chat Configuration
450
451
Methods for configuring chat settings.
452
453
```python { .api }
454
async def set_chat_title(chat_id: int | str, title: str) -> bool:
455
"""Change the title of a chat"""
456
457
async def set_chat_description(chat_id: int | str, description: str | None = None) -> bool:
458
"""Change the description of a group, a supergroup or a channel"""
459
460
async def set_chat_photo(chat_id: int | str, photo: InputFile) -> bool:
461
"""Set a new profile photo for the chat"""
462
463
async def delete_chat_photo(chat_id: int | str) -> bool:
464
"""Delete a chat photo"""
465
466
async def pin_chat_message(
467
chat_id: int | str,
468
message_id: int,
469
disable_notification: bool | None = None
470
) -> bool:
471
"""Add a message to the list of pinned messages in a chat"""
472
473
async def unpin_chat_message(chat_id: int | str, message_id: int | None = None) -> bool:
474
"""Remove a message from the list of pinned messages in a chat"""
475
476
async def unpin_all_chat_messages(chat_id: int | str) -> bool:
477
"""Clear the list of pinned messages in a chat"""
478
479
async def leave_chat(chat_id: int | str) -> bool:
480
"""Leave a group, supergroup or channel"""
481
```
482
483
### Bot Configuration
484
485
Methods for configuring bot settings and information.
486
487
```python { .api }
488
async def get_me() -> User:
489
"""Get basic info about the bot"""
490
491
async def log_out() -> bool:
492
"""Log out from the cloud Bot API server"""
493
494
async def close() -> bool:
495
"""Close the bot instance"""
496
497
async def set_my_commands(
498
commands: list[BotCommand],
499
scope: BotCommandScope | None = None,
500
language_code: str | None = None
501
) -> bool:
502
"""Change the list of the bot's commands"""
503
504
async def get_my_commands(
505
scope: BotCommandScope | None = None,
506
language_code: str | None = None
507
) -> list[BotCommand]:
508
"""Get the current list of the bot's commands"""
509
510
async def delete_my_commands(
511
scope: BotCommandScope | None = None,
512
language_code: str | None = None
513
) -> bool:
514
"""Delete the list of the bot's commands"""
515
516
async def set_my_name(name: str | None = None, language_code: str | None = None) -> bool:
517
"""Change the bot's name"""
518
519
async def get_my_name(language_code: str | None = None) -> BotName:
520
"""Get the current bot name"""
521
522
async def set_my_description(
523
description: str | None = None,
524
language_code: str | None = None
525
) -> bool:
526
"""Change the bot's description"""
527
528
async def get_my_description(language_code: str | None = None) -> BotDescription:
529
"""Get the current bot description"""
530
531
async def set_my_short_description(
532
short_description: str | None = None,
533
language_code: str | None = None
534
) -> bool:
535
"""Change the bot's short description"""
536
537
async def get_my_short_description(language_code: str | None = None) -> BotShortDescription:
538
"""Get the current bot short description"""
539
540
async def set_chat_menu_button(
541
chat_id: int | None = None,
542
menu_button: MenuButton | None = None
543
) -> bool:
544
"""Change the bot's menu button in a private chat"""
545
```
546
547
### Webhook Management
548
549
Methods for managing webhooks.
550
551
```python { .api }
552
async def set_webhook(
553
url: str,
554
certificate: InputFile | None = None,
555
ip_address: str | None = None,
556
max_connections: int | None = None,
557
allowed_updates: list[str] | None = None,
558
drop_pending_updates: bool | None = None,
559
secret_token: str | None = None
560
) -> bool:
561
"""Specify a URL and receive incoming updates via an outgoing webhook"""
562
563
async def delete_webhook(drop_pending_updates: bool | None = None) -> bool:
564
"""Remove webhook integration"""
565
566
async def get_webhook_info() -> WebhookInfo:
567
"""Get current webhook status"""
568
```
569
570
### Inline Queries
571
572
Methods for handling inline queries and callback queries.
573
574
```python { .api }
575
async def answer_inline_query(
576
inline_query_id: str,
577
results: list[InlineQueryResult],
578
cache_time: int | None = None,
579
is_personal: bool | None = None,
580
next_offset: str | None = None,
581
button: InlineQueryResultsButton | None = None
582
) -> bool:
583
"""Send answers to an inline query"""
584
585
async def answer_callback_query(
586
callback_query_id: str,
587
text: str | None = None,
588
show_alert: bool | None = None,
589
url: str | None = None,
590
cache_time: int | None = None
591
) -> bool:
592
"""Send answers to callback queries sent from inline keyboards"""
593
```
594
595
### File Operations
596
597
Methods for working with files.
598
599
```python { .api }
600
async def get_file(file_id: str) -> File:
601
"""Get basic info about a file and prepare it for downloading"""
602
603
async def get_user_profile_photos(
604
user_id: int,
605
offset: int | None = None,
606
limit: int | None = None
607
) -> UserProfilePhotos:
608
"""Get a list of profile pictures for a user"""
609
```
610
611
### Games
612
613
Methods for handling games.
614
615
```python { .api }
616
async def send_game(
617
chat_id: int,
618
game_short_name: str,
619
disable_notification: bool | None = None,
620
protect_content: bool | None = None,
621
reply_to_message_id: int | None = None,
622
allow_sending_without_reply: bool | None = None,
623
reply_markup: InlineKeyboardMarkup | None = None
624
) -> Message:
625
"""Send a game"""
626
627
async def set_game_score(
628
user_id: int,
629
score: int,
630
force: bool | None = None,
631
disable_edit_message: bool | None = None,
632
chat_id: int | None = None,
633
message_id: int | None = None,
634
inline_message_id: str | None = None
635
) -> Message | bool:
636
"""Set the score of the specified user in a game message"""
637
638
async def get_game_high_scores(
639
user_id: int,
640
chat_id: int | None = None,
641
message_id: int | None = None,
642
inline_message_id: str | None = None
643
) -> list[GameHighScore]:
644
"""Get data for high score tables"""
645
```
646
647
## Usage Examples
648
649
### Sending Different Message Types
650
651
```python
652
from aiogram import Bot
653
from aiogram.types import FSInputFile, InlineKeyboardMarkup, InlineKeyboardButton
654
655
bot = Bot(token="YOUR_TOKEN")
656
657
# Text message
658
await bot.send_message(chat_id, "Hello, World!")
659
660
# Photo with caption
661
photo = FSInputFile("photo.jpg")
662
await bot.send_photo(chat_id, photo, caption="Beautiful photo!")
663
664
# Document
665
document = FSInputFile("document.pdf")
666
await bot.send_document(chat_id, document)
667
668
# Message with inline keyboard
669
keyboard = InlineKeyboardMarkup(inline_keyboard=[
670
[InlineKeyboardButton(text="Click me!", callback_data="button_clicked")]
671
])
672
await bot.send_message(chat_id, "Choose an option:", reply_markup=keyboard)
673
```
674
675
### Editing Messages
676
677
```python
678
# Edit message text
679
message = await bot.send_message(chat_id, "Original text")
680
await bot.edit_message_text(
681
chat_id=chat_id,
682
message_id=message.message_id,
683
text="Updated text"
684
)
685
686
# Edit message with new keyboard
687
new_keyboard = InlineKeyboardMarkup(inline_keyboard=[
688
[InlineKeyboardButton(text="New button", callback_data="new_action")]
689
])
690
await bot.edit_message_reply_markup(
691
chat_id=chat_id,
692
message_id=message.message_id,
693
reply_markup=new_keyboard
694
)
695
```
696
697
### Chat Management
698
699
```python
700
# Get chat info
701
chat = await bot.get_chat(chat_id)
702
print(f"Chat title: {chat.title}")
703
704
# Ban user
705
await bot.ban_chat_member(chat_id, user_id)
706
707
# Promote user to admin
708
await bot.promote_chat_member(
709
chat_id=chat_id,
710
user_id=user_id,
711
can_delete_messages=True,
712
can_invite_users=True
713
)
714
715
# Set chat title
716
await bot.set_chat_title(chat_id, "New Chat Title")
717
```