Send a text message to a Telegram chat, group, channel, or user via the bot.

This is the primary tool for pushing notifications, alerts, or updates into Telegram — e.g. from a scheduled routine or automation.

Args:

• chat_id (string | number): Target chat ID or '@channel_username'

• text (string): Message body, 1-4096 characters

• parse_mode ('Markdown' | 'MarkdownV2' | 'HTML' | 'none'): Text formatting (default: 'none')

• disable_notification (boolean): Send silently (default: false)

• reply_to_message_id (number, optional): Reply to a specific earlier message

Returns: Confirmation text including the chat and the new message_id (needed later to edit/delete/pin it).

Error Handling:

• "chat not found" -> the chat_id is wrong, or the user has never started a chat with the bot. Ask the user to send /start to the bot first, or use telegram_get_updates to find the right chat_id.

• 403 Forbidden -> the bot was blocked by the user or removed from the group/channel.

Edit the text of a previously sent bot message.

Only messages sent by this bot can be edited, and only if they were sent less than 48 hours ago.

Args:

• chat_id (string | number): Chat containing the message

• message_id (number): ID of the message to edit

• text (string): Replacement text, 1-4096 characters

• parse_mode ('Markdown' | 'MarkdownV2' | 'HTML' | 'none'): Text formatting (default: 'none')

Returns: Confirmation that the message was updated.

Error Handling:

• "message to edit not found" -> wrong chat_id/message_id, or the message is older than 48 hours.

• "message is not modified" -> the new text is identical to the current text.

Permanently delete a message from a chat. This cannot be undone.

Bots can always delete their own messages. Deleting other users' messages requires the bot to have admin/delete rights in a group or channel.

Args:

• chat_id (string | number): Chat containing the message

• message_id (number): ID of the message to delete

Returns: Confirmation of deletion.

Error Handling:

• "message to delete not found" -> already deleted or too old (regular messages older than 48h generally can't be deleted by bots without admin rights).

• "not enough rights" -> the bot needs admin permissions in this chat to delete others' messages.

Pin a message at the top of a chat. Requires the bot to have pin permissions in groups/channels (not required for private chats with the bot).

Args:

• chat_id (string | number): Target chat

• message_id (number): ID of the message to pin

• disable_notification (boolean): Pin silently (default: false)

Returns: Confirmation of pinning.

Error Handling:

• "not enough rights" -> the bot needs the 'can_pin_messages' admin permission in this chat.

Unpin a message (or the most recent pin) in a chat.

Args:

• chat_id (string | number): Target chat

• message_id (number, optional): Specific pinned message to unpin. If omitted, unpins the most recently pinned message.

Returns: Confirmation of unpinning.

Send an image to a Telegram chat by URL, with an optional caption.

Args:

• chat_id (string | number): Target chat

• photo (string): Public HTTPS URL of the image. Telegram fetches it server-side.

• caption (string, optional): Caption text, up to 1024 characters

Returns: Confirmation with the new message_id.

Error Handling:

• "wrong file identifier/HTTP URL specified" -> the URL is not publicly reachable or not a supported image format (jpg, png, gif, webp).

• "IMAGE_PROCESS_FAILED" -> the file is too large (Telegram limit: 10 MB for photos sent by URL).

Send a file (PDF, CSV, ZIP, etc.) to a Telegram chat by URL, with an optional caption.

Args:

• chat_id (string | number): Target chat

• document (string): Public HTTPS URL of the file. Telegram fetches it server-side.

• caption (string, optional): Caption text, up to 1024 characters

Returns: Confirmation with the new message_id.

Error Handling:

• "wrong file identifier/HTTP URL specified" -> the URL is not publicly reachable.

• Telegram limit for files sent by URL is 20 MB.

Return basic info about the bot itself (username, ID, display name).

Useful to verify the configured TELEGRAM_BOT_TOKEN is valid and to get the bot's @username so a user can start a chat with it.

Args: none

Returns: JSON with id, username, first_name, is_bot.

Look up details about a chat: title/name, type (private/group/supergroup/channel), description, and invite link if available.

Args:

• chat_id (string | number): Numeric chat ID or '@channel_username'

Returns: JSON with id, type, title/name, description.

Error Handling:

• "chat not found" -> the bot has never interacted with this chat. For private chats, the user must message the bot first; for groups/channels, the bot must be a member.

Fetch recent incoming updates the bot has received (messages sent to it, chats it was added to, etc.). This is the primary way to discover a chat_id: ask the user to send any message to the bot (or add it to a group), then call this tool to read the resulting update and find the chat.id to use with telegram_send_message.

Note: calling this tool consumes the updates (Telegram's long-polling semantics), so previously fetched updates won't reappear on the next call once acknowledged.

Args:

• limit (number): Max updates to return, 1-100 (default: 20)

• offset (number, optional): Only return updates at/after this update_id

Returns: JSON list of updates with chat_id, chat type/title, sender, and message text for each.