0
# Messaging and Communication
1

2
Core messaging functionality for sending text messages, handling replies, forwarding, and copying messages between chats.
3

4
## Capabilities
5

6
### Basic Messaging
7

8
Core text messaging functionality with support for formatting, keyboards, and reply handling.
9

10
```javascript { .api }
11
/**
12
 * Send text message to chat
13
 * @param {number|string} chatId - Chat identifier
14
 * @param {string} text - Text message to send (1-4096 characters)
15
 * @param {object} [options] - Additional options
16
 * @returns {Promise<Message>}
17
 */
18
sendMessage(chatId, text, options): Promise<Message>;
19
```
20

21
**Usage Example:**
22

23
```javascript
24
// Simple text message
25
await bot.sendMessage(chatId, 'Hello, World!');
26

27
// Message with formatting
28
await bot.sendMessage(chatId, '*Bold text* and _italic text_', {
29
  parse_mode: 'Markdown'
30
});
31

32
// Message with HTML formatting
33
await bot.sendMessage(chatId, '<b>Bold</b> and <i>italic</i>', {
34
  parse_mode: 'HTML'
35
});
36

37
// Message with inline keyboard
38
await bot.sendMessage(chatId, 'Choose an option:', {
39
  reply_markup: {
40
    inline_keyboard: [
41
      [
42
        { text: 'Option 1', callback_data: 'opt_1' },
43
        { text: 'Option 2', callback_data: 'opt_2' }
44
      ],
45
      [
46
        { text: 'Visit Website', url: 'https://example.com' }
47
      ]
48
    ]
49
  }
50
});
51

52
// Message with reply keyboard
53
await bot.sendMessage(chatId, 'Select from menu:', {
54
  reply_markup: {
55
    keyboard: [
56
      ['🍕 Pizza', '🍔 Burger'],
57
      ['🥗 Salad', '🍜 Soup'],
58
      ['❌ Cancel']
59
    ],
60
    one_time_keyboard: true,
61
    resize_keyboard: true
62
  }
63
});
64

65
// Reply to specific message
66
await bot.sendMessage(chatId, 'This is a reply', {
67
  reply_to_message_id: messageId
68
});
69

70
// Silent message (no notification)
71
await bot.sendMessage(chatId, 'Silent message', {
72
  disable_notification: true
73
});
74
```
75

76
### Message Forwarding
77

78
Methods for forwarding messages between chats with support for single and batch operations.
79

80
```javascript { .api }
81
/**
82
 * Forward a message from one chat to another
83
 * @param {number|string} chatId - Target chat identifier
84
 * @param {number|string} fromChatId - Source chat identifier
85
 * @param {number} messageId - Message identifier to forward
86
 * @param {object} [options] - Additional options
87
 * @returns {Promise<Message>}
88
 */
89
forwardMessage(chatId, fromChatId, messageId, options): Promise<Message>;
90

91
/**
92
 * Forward multiple messages from one chat to another
93
 * @param {number|string} chatId - Target chat identifier
94
 * @param {number|string} fromChatId - Source chat identifier
95
 * @param {number[]} messageIds - Array of message identifiers to forward
96
 * @param {object} [options] - Additional options
97
 * @returns {Promise<MessageId[]>}
98
 */
99
forwardMessages(chatId, fromChatId, messageIds, options): Promise<MessageId[]>;
100
```
101

102
**Usage Example:**
103

104
```javascript
105
// Forward single message
106
const forwardedMessage = await bot.forwardMessage(
107
  targetChatId,     // Where to forward
108
  sourceChatId,     // Where from
109
  messageId,        // Which message
110
  {
111
    disable_notification: true
112
  }
113
);
114

115
// Forward multiple messages
116
const messageIds = [123, 124, 125];
117
const forwardedMessages = await bot.forwardMessages(
118
  targetChatId,
119
  sourceChatId,
120
  messageIds,
121
  {
122
    disable_notification: false,
123
    protect_content: true
124
  }
125
);
126

127
console.log(`Forwarded ${forwardedMessages.length} messages`);
128
```
129

130
### Message Copying
131

132
Methods for copying message content to other chats while allowing modifications.
133

134
```javascript { .api }
135
/**
136
 * Copy a message from one chat to another
137
 * @param {number|string} chatId - Target chat identifier
138
 * @param {number|string} fromChatId - Source chat identifier
139
 * @param {number} messageId - Message identifier to copy
140
 * @param {object} [options] - Additional options and modifications
141
 * @returns {Promise<MessageId>}
142
 */
143
copyMessage(chatId, fromChatId, messageId, options): Promise<MessageId>;
144

145
/**
146
 * Copy multiple messages from one chat to another
147
 * @param {number|string} chatId - Target chat identifier
148
 * @param {number|string} fromChatId - Source chat identifier
149
 * @param {number[]} messageIds - Array of message identifiers to copy
150
 * @param {object} [options] - Additional options
151
 * @returns {Promise<MessageId[]>}
152
 */
153
copyMessages(chatId, fromChatId, messageIds, options): Promise<MessageId[]>;
154
```
155

156
**Usage Example:**
157

158
```javascript
159
// Copy message with modified caption
160
const copiedMessage = await bot.copyMessage(
161
  targetChatId,
162
  sourceChatId,
163
  messageId,
164
  {
165
    caption: 'Modified caption for copied message',
166
    parse_mode: 'HTML',
167
    reply_markup: {
168
      inline_keyboard: [
169
        [{ text: 'New Button', callback_data: 'new_action' }]
170
      ]
171
    }
172
  }
173
);
174

175
// Copy multiple messages
176
const messageIds = [100, 101, 102];
177
const copiedMessages = await bot.copyMessages(
178
  targetChatId,
179
  sourceChatId,
180
  messageIds,
181
  {
182
    disable_notification: true,
183
    remove_caption: false
184
  }
185
);
186
```
187

188
### Message Editing
189

190
Methods for editing previously sent messages including text, captions, media, and keyboards.
191

192
```javascript { .api }
193
/**
194
 * Edit text of a message
195
 * @param {string} text - New text content
196
 * @param {object} [options] - Edit options with chat_id and message_id
197
 * @returns {Promise<Message|boolean>}
198
 */
199
editMessageText(text, options): Promise<Message|boolean>;
200

201
/**
202
 * Edit caption of a message
203
 * @param {string} caption - New caption text
204
 * @param {object} [options] - Edit options with chat_id and message_id
205
 * @returns {Promise<Message|boolean>}
206
 */
207
editMessageCaption(caption, options): Promise<Message|boolean>;
208

209
/**
210
 * Edit media content of a message
211
 * @param {object} media - New media object
212
 * @param {object} [options] - Edit options with chat_id and message_id
213
 * @returns {Promise<Message|boolean>}
214
 */
215
editMessageMedia(media, options): Promise<Message|boolean>;
216

217
/**
218
 * Edit reply markup (inline keyboard) of a message
219
 * @param {object} replyMarkup - New reply markup
220
 * @param {object} [options] - Edit options with chat_id and message_id
221
 * @returns {Promise<Message|boolean>}
222
 */
223
editMessageReplyMarkup(replyMarkup, options): Promise<Message|boolean>;
224
```
225

226
**Usage Example:**
227

228
```javascript
229
// Edit text message
230
await bot.editMessageText('Updated text content', {
231
  chat_id: chatId,
232
  message_id: messageId,
233
  parse_mode: 'HTML'
234
});
235

236
// Edit message caption
237
await bot.editMessageCaption('New caption with <b>formatting</b>', {
238
  chat_id: chatId,
239
  message_id: messageId,
240
  parse_mode: 'HTML'
241
});
242

243
// Edit inline keyboard
244
await bot.editMessageReplyMarkup({
245
  inline_keyboard: [
246
    [
247
      { text: 'Updated Button', callback_data: 'updated_action' },
248
      { text: 'Delete', callback_data: 'delete_message' }
249
    ]
250
  ]
251
}, {
252
  chat_id: chatId,
253
  message_id: messageId
254
});
255

256
// Edit media (photo to video)
257
await bot.editMessageMedia({
258
  type: 'video',
259
  media: 'https://example.com/video.mp4',
260
  caption: 'Updated video with new caption'
261
}, {
262
  chat_id: chatId,
263
  message_id: messageId
264
});
265

266
// Edit inline message (for inline query results)
267
await bot.editMessageText('Updated inline message', {
268
  inline_message_id: inlineMessageId
269
});
270
```
271

272
### Message Deletion
273

274
Methods for deleting messages from chats with support for single and batch operations.
275

276
```javascript { .api }
277
/**
278
 * Delete a message
279
 * @param {number|string} chatId - Chat identifier
280
 * @param {number} messageId - Message identifier to delete
281
 * @param {object} [options] - Additional options
282
 * @returns {Promise<boolean>}
283
 */
284
deleteMessage(chatId, messageId, options): Promise<boolean>;
285

286
/**
287
 * Delete multiple messages
288
 * @param {number|string} chatId - Chat identifier
289
 * @param {number[]} messageIds - Array of message identifiers to delete
290
 * @param {object} [options] - Additional options
291
 * @returns {Promise<boolean>}
292
 */
293
deleteMessages(chatId, messageIds, options): Promise<boolean>;
294
```
295

296
**Usage Example:**
297

298
```javascript
299
// Delete single message
300
const deleted = await bot.deleteMessage(chatId, messageId);
301
if (deleted) {
302
  console.log('Message deleted successfully');
303
}
304

305
// Delete multiple messages
306
const messageIds = [123, 124, 125, 126];
307
const allDeleted = await bot.deleteMessages(chatId, messageIds);
308
if (allDeleted) {
309
  console.log('All messages deleted successfully');
310
}
311

312
// Delete with error handling
313
try {
314
  await bot.deleteMessage(chatId, messageId);
315
} catch (error) {
316
  if (error.code === 'ETELEGRAM') {
317
    console.log('Cannot delete message:', error.message);
318
  }
319
}
320
```
321

322
### Callback Query Handling
323

324
Method for responding to inline keyboard button presses.
325

326
```javascript { .api }
327
/**
328
 * Answer callback query from inline keyboard
329
 * @param {string} callbackQueryId - Callback query identifier
330
 * @param {object} [options] - Answer options
331
 * @returns {Promise<boolean>}
332
 */
333
answerCallbackQuery(callbackQueryId, options): Promise<boolean>;
334
```
335

336
**Usage Example:**
337

338
```javascript
339
// Handle callback queries
340
bot.on('callback_query', async (callbackQuery) => {
341
  const data = callbackQuery.data;
342
  const messageId = callbackQuery.message.message_id;
343
  const chatId = callbackQuery.message.chat.id;
344
  
345
  // Answer the callback query
346
  await bot.answerCallbackQuery(callbackQuery.id, {
347
    text: `You clicked: ${data}`,
348
    show_alert: false
349
  });
350
  
351
  // Handle different callback data
352
  switch (data) {
353
    case 'delete_message':
354
      await bot.deleteMessage(chatId, messageId);
355
      break;
356
      
357
    case 'edit_message':
358
      await bot.editMessageText('Message was edited!', {
359
        chat_id: chatId,
360
        message_id: messageId
361
      });
362
      break;
363
      
364
    case 'show_alert':
365
      await bot.answerCallbackQuery(callbackQuery.id, {
366
        text: 'This is an alert!',
367
        show_alert: true
368
      });
369
      break;
370
  }
371
});
372

373
// Send message with callback buttons
374
await bot.sendMessage(chatId, 'Choose an action:', {
375
  reply_markup: {
376
    inline_keyboard: [
377
      [
378
        { text: '✏️ Edit', callback_data: 'edit_message' },
379
        { text: '🗑️ Delete', callback_data: 'delete_message' }
380
      ],
381
      [
382
        { text: '⚠️ Alert', callback_data: 'show_alert' }
383
      ]
384
    ]
385
  }
386
});
387
```
388

389
## Types
390

391
```javascript { .api }
392
interface Message {
393
  message_id: number;
394
  message_thread_id?: number;
395
  from?: User;
396
  sender_chat?: Chat;
397
  date: number;
398
  chat: Chat;
399
  forward_origin?: MessageOrigin;
400
  is_topic_message?: boolean;
401
  is_automatic_forward?: boolean;
402
  reply_to_message?: Message;
403
  external_reply?: ExternalReplyInfo;
404
  quote?: TextQuote;
405
  reply_to_story?: Story;
406
  via_bot?: User;
407
  edit_date?: number;
408
  has_protected_content?: boolean;
409
  media_group_id?: string;
410
  author_signature?: string;
411
  text?: string;
412
  entities?: MessageEntity[];
413
  animation?: Animation;
414
  audio?: Audio;
415
  document?: Document;
416
  photo?: PhotoSize[];
417
  sticker?: Sticker;
418
  story?: Story;
419
  video?: Video;
420
  video_note?: VideoNote;
421
  voice?: Voice;
422
  caption?: string;
423
  caption_entities?: MessageEntity[];
424
  has_media_spoiler?: boolean;
425
  contact?: Contact;
426
  dice?: Dice;
427
  game?: Game;
428
  poll?: Poll;
429
  venue?: Venue;
430
  location?: Location;
431
  new_chat_members?: User[];
432
  left_chat_member?: User;
433
  new_chat_title?: string;
434
  new_chat_photo?: PhotoSize[];
435
  delete_chat_photo?: boolean;
436
  group_chat_created?: boolean;
437
  supergroup_chat_created?: boolean;
438
  channel_chat_created?: boolean;
439
  message_auto_delete_timer_changed?: MessageAutoDeleteTimerChanged;
440
  migrate_to_chat_id?: number;
441
  migrate_from_chat_id?: number;
442
  pinned_message?: MaybeInaccessibleMessage;
443
  invoice?: Invoice;
444
  successful_payment?: SuccessfulPayment;
445
  users_shared?: UsersShared;
446
  chat_shared?: ChatShared;
447
  connected_website?: string;
448
  write_access_allowed?: WriteAccessAllowed;
449
  passport_data?: PassportData;
450
  proximity_alert_triggered?: ProximityAlertTriggered;
451
  boost_added?: ChatBoostAdded;
452
  forum_topic_created?: ForumTopicCreated;
453
  forum_topic_edited?: ForumTopicEdited;
454
  forum_topic_closed?: ForumTopicClosed;
455
  forum_topic_reopened?: ForumTopicReopened;
456
  general_forum_topic_hidden?: GeneralForumTopicHidden;
457
  general_forum_topic_unhidden?: GeneralForumTopicUnhidden;
458
  giveaway_created?: GiveawayCreated;
459
  giveaway?: Giveaway;
460
  giveaway_winners?: GiveawayWinners;
461
  giveaway_completed?: GiveawayCompleted;
462
  video_chat_scheduled?: VideoChatScheduled;
463
  video_chat_started?: VideoChatStarted;
464
  video_chat_ended?: VideoChatEnded;
465
  video_chat_participants_invited?: VideoChatParticipantsInvited;
466
  web_app_data?: WebAppData;
467
  reply_markup?: InlineKeyboardMarkup;
468
}
469

470
interface MessageId {
471
  message_id: number;
472
}
473

474
interface InlineKeyboardMarkup {
475
  inline_keyboard: InlineKeyboardButton[][];
476
}
477

478
interface InlineKeyboardButton {
479
  text: string;
480
  url?: string;
481
  callback_data?: string;
482
  web_app?: WebApp;
483
  login_url?: LoginUrl;
484
  switch_inline_query?: string;
485
  switch_inline_query_current_chat?: string;
486
  switch_inline_query_chosen_chat?: SwitchInlineQueryChosenChat;
487
  callback_game?: CallbackGame;
488
  pay?: boolean;
489
}
490

491
interface ReplyKeyboardMarkup {
492
  keyboard: KeyboardButton[][];
493
  is_persistent?: boolean;
494
  resize_keyboard?: boolean;
495
  one_time_keyboard?: boolean;
496
  input_field_placeholder?: string;
497
  selective?: boolean;
498
}
499

500
interface KeyboardButton {
501
  text: string;
502
  request_users?: KeyboardButtonRequestUsers;
503
  request_chat?: KeyboardButtonRequestChat;
504
  request_contact?: boolean;
505
  request_location?: boolean;
506
  request_poll?: KeyboardButtonPollType;
507
  web_app?: WebApp;
508
}
509

510
interface SendMessageOptions {
511
  business_connection_id?: string;
512
  message_thread_id?: number;
513
  parse_mode?: 'HTML' | 'Markdown' | 'MarkdownV2';
514
  entities?: MessageEntity[];
515
  link_preview_options?: LinkPreviewOptions;
516
  disable_notification?: boolean;
517
  protect_content?: boolean;
518
  reply_parameters?: ReplyParameters;
519
  reply_markup?: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply;
520
}
521
```