or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

Files

docs

api-methods.mdbot-and-dispatcher.mdfilters-and-handlers.mdindex.mdstate-management.mdtypes-and-objects.mdutilities-and-enums.md

api-methods.mddocs/

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

```