Telegram Bot

SDK reference for telegram bot operations

Overview

Send and receive messages through Telegram bots. NOTE: Bot setup (creating a bot via BotFather and adding the token) must be done by the user in the Resources tab — you cannot configure or register bots on their behalf.

• Category: communication
• Auth Required: Yes
• Supported Modes: standard, delegated, service

Operations

sendMessage

Send a text message to a Telegram chat via bot

Arguments:

• botUsername (string, required): Username of the bot to send from (without @)
• chatId (string, required): Telegram chat ID to send the message to
• text (string, required): Message text to send (supports Markdown)
• parseMode (string, optional): Parse mode: Markdown, MarkdownV2, or HTML
• disableNotification (boolean, optional): Send silently without notification sound

Returns:

AdapterOperationResult - Sent message details including messageId and chatId

Response Fields:

Example:

const result = await mirra.telegramBot.sendMessage({
  botUsername: "example",
  chatId: "abc123",
  text: "example"
});

replyToMessage

Reply to a specific message in a Telegram chat

Arguments:

• botUsername (string, required): Username of the bot to reply from (without @)
• chatId (string, required): Telegram chat ID
• text (string, required): Reply text (supports Markdown)
• replyToMessageId (number, required): Message ID to reply to
• parseMode (string, optional): Parse mode: Markdown, MarkdownV2, or HTML

Returns:

AdapterOperationResult - Sent reply details including messageId

Response Fields:

Example:

const result = await mirra.telegramBot.replyToMessage({
  botUsername: "example",
  chatId: "abc123",
  text: "example",
  replyToMessageId: 10
});

editMessageText

Replace the text of a previously sent bot message. Use this for the "placeholder + edit" pattern: send an immediate placeholder (e.g. "🤔 Thinking…"), run a slow operation like mirra.ai.agent(...), then edit the placeholder with the final answer. The bot can only edit its own messages.

Arguments:

• botUsername (string, required): Username of the bot (without @). Must be the same bot that sent the original message.
• chatId (string, required): Telegram chat ID of the message to edit
• messageId (number, required): ID of the message to edit (returned by sendMessage / replyToMessage / sendMessageWithButtons)
• text (string, required): New message text (supports Markdown)
• parseMode (string, optional): Parse mode: Markdown, MarkdownV2, or HTML

Returns:

AdapterOperationResult - Edited message details including messageId and new text

Response Fields:

Example:

const result = await mirra.telegramBot.editMessageText({
  botUsername: "example",
  chatId: "abc123",
  messageId: 10,
  text: "example"
});

answerCallbackQuery

Respond to an inline keyboard button press (callback query)

Arguments:

• botUsername (string, required): Username of the bot
• callbackQueryId (string, required): Callback query ID from the button press event
• text (string, optional): Optional text to show as a notification to the user
• showAlert (boolean, optional): If true, show an alert instead of a toast notification

Returns:

AdapterOperationResult - Confirmation of callback query answer

Response Fields:

Example:

const result = await mirra.telegramBot.answerCallbackQuery({
  botUsername: "example",
  callbackQueryId: "abc123"
});

sendMessageWithButtons

Send a message with inline keyboard buttons for user interaction

Arguments:

• botUsername (string, required): Username of the bot to send from (without @)
• chatId (string, required): Telegram chat ID
• text (string, required): Message text (supports Markdown)
• buttons (array, required): Array of button rows. Each row is an array of { text, callbackData } objects
• parseMode (string, optional): Parse mode: Markdown, MarkdownV2, or HTML

Returns:

AdapterOperationResult - Sent message details with button layout

Response Fields:

Example:

const result = await mirra.telegramBot.sendMessageWithButtons({
  botUsername: "example",
  chatId: "abc123",
  text: "example",
  buttons: []
});

setBotCommands

Set the list of commands shown in the bot menu

Arguments:

• botUsername (string, required): Username of the bot
• commands (array, required): Array of { command, description } objects

Returns:

AdapterOperationResult - Confirmation of commands being set

Response Fields:

Example:

const result = await mirra.telegramBot.setBotCommands({
  botUsername: "example",
  commands: []
});

getBotInfo

Get information about the bot (username, name, can_join_groups, etc.)

Arguments:

• botUsername (string, required): Username of the bot

Returns:

AdapterOperationResult - Bot information including id, username, name, and capabilities

Response Fields:

Example:

const result = await mirra.telegramBot.getBotInfo({
  botUsername: "example"
});

listBots

List all Telegram bots registered by the user

Returns:

AdapterOperationResult - Array of registered bots with their usernames and status

Response Fields:

| count | number | Number of registered bots |

Example:

const result = await mirra.telegramBot.listBots();

banChatMember

Ban or kick a user from a group chat. The bot must be an admin with "Ban Users" permission. Accepts a numeric user ID or @username. To kick (remove without permanent ban), set untilDate to ~30 seconds in the future — e.g. Math.floor(Date.now()/1000) + 30.

Arguments:

• botUsername (string, required): Username of the bot (without @)
• chatId (string, required): Group chat ID
• userId (string, required): Telegram user ID or @username to ban. Examples: "123456", "@johndoe"
• untilDate (number, optional): Unix timestamp for temporary ban. Set to ~30s in the future for a "kick" (remove without permanent ban). Omit for permanent ban.
• revokeMessages (boolean, optional): If true, delete all messages from this user in the group

Returns:

AdapterOperationResult - Confirmation of the ban action

Response Fields:

Example:

const result = await mirra.telegramBot.banChatMember({
  botUsername: "example",
  chatId: "abc123",
  userId: "abc123"
});

unbanChatMember

Unban a previously banned user in a group chat. The bot must be an admin with "Ban Users" permission. Accepts a numeric user ID or @username.

Arguments:

• botUsername (string, required): Username of the bot (without @)
• chatId (string, required): Group chat ID
• userId (string, required): Telegram user ID or @username to unban. Examples: "123456", "@johndoe"
• onlyIfBanned (boolean, optional): If true, only unban if the user is actually banned (will not re-add a user who left voluntarily)

Returns:

AdapterOperationResult - Confirmation of the unban action

Response Fields:

Example:

const result = await mirra.telegramBot.unbanChatMember({
  botUsername: "example",
  chatId: "abc123",
  userId: "abc123"
});

restrictChatMember

Restrict a user's permissions in a group chat (mute, block media, etc.). The bot must be an admin with "Ban Users" permission. Accepts a numeric user ID or @username. Pass a permissions object to control what the user can do.

Arguments:

• botUsername (string, required): Username of the bot (without @)
• chatId (string, required): Group chat ID
• userId (string, required): Telegram user ID or @username to restrict. Examples: "123456", "@johndoe"
• permissions (object, required): ChatPermissions object with boolean fields: canSendMessages, canSendPhotos, canSendVideos, canSendAudios, canSendDocuments, canSendVoiceNotes, canSendVideoNotes, canSendPolls, canSendOtherMessages, canAddWebPagePreviews, canChangeInfo, canInviteUsers, canPinMessages, canManageTopics. Set to false to restrict.
• untilDate (number, optional): Unix timestamp for temporary restriction. Omit for permanent restriction.

Returns:

AdapterOperationResult - Confirmation of the restriction

Response Fields:

Example:

const result = await mirra.telegramBot.restrictChatMember({
  botUsername: "example",
  chatId: "abc123",
  userId: "abc123",
  permissions: {}
});

getChatMember

Look up a user in a group chat by their user ID or @username. Returns their membership status (creator, administrator, member, restricted, left, kicked) and permissions.

Arguments:

• botUsername (string, required): Username of the bot (without @)
• chatId (string, required): Group chat ID
• userId (string, required): Telegram user ID or @username to look up. Examples: "123456", "@johndoe"

Returns:

AdapterOperationResult - User membership info including status, name, and permissions

Response Fields:

Example:

const result = await mirra.telegramBot.getChatMember({
  botUsername: "example",
  chatId: "abc123",
  userId: "abc123"
});

deleteMessage

Delete a message in a group chat. The bot must be an admin with "Delete Messages" permission, or the message must have been sent by the bot itself.

Arguments:

• botUsername (string, required): Username of the bot (without @)
• chatId (string, required): Group chat ID
• messageId (number, required): ID of the message to delete

Returns:

AdapterOperationResult - Confirmation of message deletion

Response Fields:

Example:

const result = await mirra.telegramBot.deleteMessage({
  botUsername: "example",
  chatId: "abc123",
  messageId: 10
});

downloadFile

Download a file from Telegram (photo, document, video, audio, voice, sticker) as base64. Use this to feed user-uploaded media into mirra.ai.chat for vision/OCR/document understanding.

USAGE PATTERN (vision): // 1. Read fileId from the incoming bot event const fileId = event.data.bot.fileId; const { base64, mimeType } = await mirra.telegramBot.downloadFile({ botUsername, fileId });

// 2. Pipe into ai.chat as a multimodal content block await mirra.ai.chat({ messages: [{ role: 'user', content: [ { type: 'text', text: 'Extract the invoice details' }, { type: 'image', source: { type: 'base64', media_type: mimeType, data: base64 } } ] }] });

LIMITS:

• Telegram caps file downloads at 20 MB via the Bot API. Larger files (sent by users to bots) will fail with a Telegram error.
• Base64 inflates payload size by ~33%; for very large files prefer document IDs over inline base64.

Arguments:

• botUsername (string, required): Username of the bot that received the file (without @). Must be the bot that the file_id was issued to — file_ids are bot-scoped.
• fileId (string, required): Telegram file_id from an incoming media event (event.data.bot.fileId). For photos with multiple sizes, the event already contains the largest size.

Returns:

AdapterOperationResult - Downloaded file with base64 data, MIME type, file size, and Telegram-provided filename when available

Response Fields:

Example:

const result = await mirra.telegramBot.downloadFile({
  botUsername: "example",
  fileId: "abc123"
});