0
# Message Operations
1

2
Comprehensive message handling including sending, forwarding, copying, deleting, and editing messages with support for all message types and formatting options.
3

4
## Capabilities
5

6
### Text Message Sending
7

8
Send text messages with rich formatting, custom keyboards, and reply options.
9

10
```python { .api }
11
def send_message(self, chat_id: Union[int, str], text: str, 
12
                disable_web_page_preview: Optional[bool] = None,
13
                reply_to_message_id: Optional[int] = None,
14
                reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
15
                parse_mode: Optional[str] = None,
16
                disable_notification: Optional[bool] = None,
17
                timeout: Optional[int] = None,
18
                entities: Optional[List[types.MessageEntity]] = None,
19
                allow_sending_without_reply: Optional[bool] = None) -> types.Message:
20
    """
21
    Send text messages with formatting and interactive elements.
22

23
    Parameters:
24
    - chat_id (Union[int, str]): Target chat ID or username
25
    - text (str): Message text (max ~4000 characters)
26
    - disable_web_page_preview (bool, optional): Disable link previews
27
    - reply_to_message_id (int, optional): ID of message to reply to
28
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
29
    - parse_mode (str, optional): 'HTML', 'Markdown', or 'MarkdownV2'
30
    - disable_notification (bool, optional): Send silently
31
    - timeout (int, optional): Request timeout in seconds
32
    - entities (List[MessageEntity], optional): Message entities for formatting
33
    - allow_sending_without_reply (bool, optional): Send even if reply target not found
34

35
    Returns:
36
    Message: Sent message object
37
    """
38

39
def reply_to(self, message: types.Message, text: str, **kwargs) -> types.Message:
40
    """
41
    Convenience method to reply to a message.
42

43
    Parameters:
44
    - message (Message): Message to reply to
45
    - text (str): Reply text
46
    - **kwargs: Additional parameters for send_message
47

48
    Returns:
49
    Message: Sent reply message
50
    """
51
```
52

53
### Message Forwarding and Copying
54

55
Forward or copy messages between chats while preserving or modifying content.
56

57
```python { .api }
58
def forward_message(self, chat_id: Union[int, str], from_chat_id: Union[int, str],
59
                   message_id: int, disable_notification: Optional[bool] = None,
60
                   timeout: Optional[int] = None) -> types.Message:
61
    """
62
    Forward messages of any kind between chats.
63

64
    Parameters:
65
    - chat_id (Union[int, str]): Destination chat
66
    - from_chat_id (Union[int, str]): Source chat
67
    - message_id (int): Message ID to forward
68
    - disable_notification (bool, optional): Send silently
69
    - timeout (int, optional): Request timeout
70

71
    Returns:
72
    Message: Forwarded message
73
    """
74

75
def copy_message(self, chat_id: Union[int, str], from_chat_id: Union[int, str],
76
                message_id: int, caption: Optional[str] = None,
77
                parse_mode: Optional[str] = None,
78
                caption_entities: Optional[List[types.MessageEntity]] = None,
79
                disable_notification: Optional[bool] = None,
80
                reply_to_message_id: Optional[int] = None,
81
                allow_sending_without_reply: Optional[bool] = None,
82
                reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
83
                timeout: Optional[int] = None) -> int:
84
    """
85
    Copy messages with optional caption modification.
86

87
    Parameters:
88
    - chat_id (Union[int, str]): Destination chat
89
    - from_chat_id (Union[int, str]): Source chat  
90
    - message_id (int): Message ID to copy
91
    - caption (str, optional): New caption for media messages
92
    - parse_mode (str, optional): Caption parsing mode
93
    - caption_entities (List[MessageEntity], optional): Caption entities
94
    - disable_notification (bool, optional): Send silently
95
    - reply_to_message_id (int, optional): Message to reply to
96
    - allow_sending_without_reply (bool, optional): Send if reply target missing
97
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
98
    - timeout (int, optional): Request timeout
99

100
    Returns:
101
    int: ID of the copied message
102
    """
103
```
104

105
### Message Editing
106

107
Edit text content, media, captions, and reply markup of existing messages.
108

109
```python { .api }
110
def edit_message_text(self, text: str, 
111
                     chat_id: Optional[Union[int, str]] = None,
112
                     message_id: Optional[int] = None,
113
                     inline_message_id: Optional[str] = None,
114
                     parse_mode: Optional[str] = None,
115
                     entities: Optional[List[types.MessageEntity]] = None,
116
                     disable_web_page_preview: Optional[bool] = None,
117
                     reply_markup: Optional[REPLY_MARKUP_TYPES] = None) -> Union[types.Message, bool]:
118
    """
119
    Edit text and game messages.
120

121
    Parameters:
122
    - text (str): New message text
123
    - chat_id (Union[int, str], optional): Chat ID (required for non-inline)
124
    - message_id (int, optional): Message ID (required for non-inline)
125
    - inline_message_id (str, optional): Inline message ID
126
    - parse_mode (str, optional): Text parsing mode
127
    - entities (List[MessageEntity], optional): Message entities
128
    - disable_web_page_preview (bool, optional): Disable link previews
129
    - reply_markup (REPLY_MARKUP_TYPES, optional): New keyboard markup
130

131
    Returns:
132
    Union[Message, bool]: Edited message or True for inline messages
133
    """
134

135
def edit_message_caption(self, caption: str, 
136
                        chat_id: Optional[Union[int, str]] = None,
137
                        message_id: Optional[int] = None,
138
                        inline_message_id: Optional[str] = None,
139
                        parse_mode: Optional[str] = None,
140
                        caption_entities: Optional[List[types.MessageEntity]] = None,
141
                        reply_markup: Optional[REPLY_MARKUP_TYPES] = None) -> Union[types.Message, bool]:
142
    """
143
    Edit captions of media messages.
144

145
    Parameters:
146
    - caption (str): New caption text
147
    - chat_id (Union[int, str], optional): Chat ID
148
    - message_id (int, optional): Message ID
149
    - inline_message_id (str, optional): Inline message ID
150
    - parse_mode (str, optional): Caption parsing mode
151
    - caption_entities (List[MessageEntity], optional): Caption entities
152
    - reply_markup (REPLY_MARKUP_TYPES, optional): New keyboard markup
153

154
    Returns:
155
    Union[Message, bool]: Edited message or True for inline messages
156
    """
157

158
def edit_message_reply_markup(self, chat_id: Optional[Union[int, str]] = None,
159
                             message_id: Optional[int] = None,
160
                             inline_message_id: Optional[str] = None,
161
                             reply_markup: Optional[REPLY_MARKUP_TYPES] = None) -> Union[types.Message, bool]:
162
    """
163
    Edit only the reply markup of messages.
164

165
    Parameters:
166
    - chat_id (Union[int, str], optional): Chat ID
167
    - message_id (int, optional): Message ID
168
    - inline_message_id (str, optional): Inline message ID
169
    - reply_markup (REPLY_MARKUP_TYPES, optional): New keyboard markup
170

171
    Returns:
172
    Union[Message, bool]: Edited message or True for inline messages
173
    """
174
```
175

176
### Message Deletion
177

178
Remove messages from chats with proper error handling.
179

180
```python { .api }
181
def delete_message(self, chat_id: Union[int, str], message_id: int,
182
                  timeout: Optional[int] = None) -> bool:
183
    """
184
    Delete messages from chats.
185

186
    Parameters:
187
    - chat_id (Union[int, str]): Chat containing the message
188
    - message_id (int): ID of message to delete
189
    - timeout (int, optional): Request timeout
190

191
    Returns:
192
    bool: True on success
193

194
    Note: Bots can delete outgoing messages in private chats, groups, and supergroups.
195
    Bots granted can_post_messages permissions can delete outgoing messages in channels.
196
    If the bot is an administrator, it can delete any message there.
197
    """
198
```
199

200
### Chat Actions
201

202
Send typing indicators and other chat actions to show bot activity.
203

204
```python { .api }
205
def send_chat_action(self, chat_id: Union[int, str], action: str,
206
                    timeout: Optional[int] = None) -> bool:
207
    """
208
    Send chat action to indicate bot activity.
209

210
    Parameters:
211
    - chat_id (Union[int, str]): Target chat
212
    - action (str): Action type ('typing', 'upload_photo', 'record_video', 
213
                   'upload_video', 'record_audio', 'upload_audio', 
214
                   'upload_document', 'find_location', 'record_video_note', 
215
                   'upload_video_note')
216
    - timeout (int, optional): Request timeout
217

218
    Returns:
219
    bool: True on success
220

221
    Note: Status is shown for 5 seconds or until a message is sent.
222
    """
223
```
224

225
## Usage Examples
226

227
### Basic Text Messaging
228

229
```python
230
# Simple text message
231
bot.send_message(chat_id, "Hello, World!")
232

233
# Formatted message with keyboard
234
from telebot import types
235

236
markup = types.InlineKeyboardMarkup()
237
markup.add(types.InlineKeyboardButton("Click me!", callback_data="button_clicked"))
238

239
bot.send_message(
240
    chat_id=chat_id,
241
    text="<b>Bold text</b> and <i>italic text</i>",
242
    parse_mode='HTML',
243
    reply_markup=markup
244
)
245
```
246

247
### Message Forwarding Example
248

249
```python
250
@bot.message_handler(commands=['forward'])
251
def forward_message_example(message):
252
    # Forward the command message to another chat
253
    target_chat_id = "@your_channel"
254
    forwarded = bot.forward_message(target_chat_id, message.chat.id, message.message_id)
255
    bot.reply_to(message, f"Message forwarded with ID: {forwarded.message_id}")
256
```
257

258
### Message Editing Example
259

260
```python
261
@bot.message_handler(commands=['edit'])
262
def edit_message_example(message):
263
    # Send initial message
264
    sent_msg = bot.reply_to(message, "Initial text")
265
    
266
    # Edit after 2 seconds
267
    import time
268
    time.sleep(2)
269
    
270
    bot.edit_message_text(
271
        text="Edited text!",
272
        chat_id=sent_msg.chat.id,
273
        message_id=sent_msg.message_id
274
    )
275
```
276

277
### Chat Action Example
278

279
```python
280
@bot.message_handler(commands=['typing'])
281
def show_typing(message):
282
    # Show typing indicator
283
    bot.send_chat_action(message.chat.id, 'typing')
284
    
285
    # Simulate processing time
286
    import time
287
    time.sleep(3)
288
    
289
    bot.reply_to(message, "Done processing!")
290
```
291

292
## Types
293

294
```python { .api }
295
class Message:
296
    message_id: int
297
    from_user: Optional[User]
298
    date: int
299
    chat: Chat
300
    content_type: str
301
    text: Optional[str]
302
    entities: Optional[List[MessageEntity]]
303
    caption: Optional[str]
304
    caption_entities: Optional[List[MessageEntity]]
305
    # ... content-specific fields (photo, video, document, etc.)
306

307
class MessageEntity:
308
    type: str  # 'mention', 'hashtag', 'cashtag', 'bot_command', 'url', etc.
309
    offset: int
310
    length: int
311
    url: Optional[str]
312
    user: Optional[User]
313
    language: Optional[str]
314

315
class MessageID:
316
    message_id: int
317

318
REPLY_MARKUP_TYPES = Union[InlineKeyboardMarkup, ReplyKeyboardMarkup, 
319
                          ReplyKeyboardRemove, ForceReply]
320
```