mirra-telegrambot

name	mirra-telegramBot
description	Use Mirra to 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 resource.... Covers all Telegram Bot SDK operations via REST API.
allowed-tools	Read, Bash(curl:*, jq:*)

Mirra Telegram Bot

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.

Prerequisites

You need the user's API key. Ask for these if not provided:

• API_KEY: Mirra API key (generated in Mirra app > Settings > API Keys)
• API_URL: Defaults to https://api.fxn.world (only ask if they mention a custom server)

Note: Telegram Bot requires OAuth authentication. The user must have connected their Telegram Bot account in the Mirra app before these operations will work.

API Call Pattern

All operations use a single POST endpoint with the resource ID and method in the body:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{
    "resourceId": "telegramBot",
    "method": "{operation}",
    "params": { ...args }
  }' | jq .

Replace {operation} with the operation name from the table below.

Legacy alternative: POST ${API_URL}/api/sdk/v1/telegramBot/{operation} with args as the request body also works but is not recommended for new integrations.

Available Operations

Operation	Description
sendMessage	Send a text message to a Telegram chat via bot
replyToMessage	Reply to a specific message in a Telegram chat
editMessageText	Replace the text of a previously sent bot message. Use this for the "placeholder + edit" pattern:...
answerCallbackQuery	Respond to an inline keyboard button press (callback query)
sendMessageWithButtons	Send a message with inline keyboard buttons for user interaction
setBotCommands	Set the list of commands shown in the bot menu
getBotInfo	Get information about the bot (username, name, can_join_groups, etc.)
listBots	List all Telegram bots registered by the user
banChatMember	Ban or kick a user from a group chat. The bot must be an admin with "Ban Users" permission. Accep...
unbanChatMember	Unban a previously banned user in a group chat. The bot must be an admin with "Ban Users" permiss...
restrictChatMember	Restrict a user's permissions in a group chat (mute, block media, etc.). The bot must be an admin...
getChatMember	Look up a user in a group chat by their user ID or @username. Returns their membership status (cr...
deleteMessage	Delete a message in a group chat. The bot must be an admin with "Delete Messages" permission, or ...
downloadFile	Download a file from Telegram (photo, document, video, audio, voice, sticker) as base64. Use this...

Operation Details

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"sendMessage","params":{"botUsername":"my_bot","chatId":"123456789","text":"Hello from Mirra!"}}' | jq .

Example response:

{
  "messageId": 42,
  "chatId": "123456789",
  "text": "Hello from Mirra!"
}

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"replyToMessage","params":{"botUsername":"my_bot","chatId":"123456789","text":"Got it!","replyToMessageId":41}}' | jq .

Example response:

{
  "messageId": 43,
  "chatId": "123456789",
  "text": "Got it!",
  "replyToMessageId": 41
}

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"editMessageText","params":{"botUsername":"my_bot","chatId":"123456789","messageId":42,"text":"Here is the answer from the AI…"}}' | jq .

Example response:

{
  "messageId": 42,
  "chatId": "123456789",
  "text": "Here is the answer from the AI…",
  "edited": true
}

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"answerCallbackQuery","params":{"botUsername":"<value>","callbackQueryId":"<ID>"}}' | jq .

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"sendMessageWithButtons","params":{"botUsername":"my_bot","chatId":"123456789","text":"Do you approve?","buttons":[[{"text":"Yes","callbackData":"approve_yes"},{"text":"No","callbackData":"approve_no"}]]}}' | jq .

Example response:

{
  "messageId": 44,
  "chatId": "123456789",
  "text": "Do you approve?",
  "hasButtons": true
}

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"setBotCommands","params":{"botUsername":"<value>","commands":[]}}' | jq .

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"getBotInfo","params":{"botUsername":"<value>"}}' | jq .

listBots

List all Telegram bots registered by the user

Returns:

AdapterOperationResult: Array of registered bots with their usernames and status

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"listBots","params":{}}' | jq .

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"banChatMember","params":{"botUsername":"my_bot","chatId":"-1001234567890","userId":123456,"untilDate":1700000030}}' | jq .

Example response:

{
  "userId": 123456,
  "chatId": "-1001234567890",
  "banned": true,
  "untilDate": 1700000030
}

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"unbanChatMember","params":{"botUsername":"my_bot","chatId":"-1001234567890","userId":123456,"onlyIfBanned":true}}' | jq .

Example response:

{
  "userId": 123456,
  "chatId": "-1001234567890",
  "unbanned": true
}

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"restrictChatMember","params":{"botUsername":"my_bot","chatId":"-1001234567890","userId":123456,"permissions":{"canSendMessages":false},"untilDate":1700003600}}' | jq .

Example response:

{
  "userId": 123456,
  "chatId": "-1001234567890",
  "restricted": true,
  "permissions": {
    "canSendMessages": false
  },
  "untilDate": 1700003600
}

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"getChatMember","params":{"botUsername":"my_bot","chatId":"-1001234567890","userId":123456}}' | jq .

Example response:

{
  "userId": 123456,
  "status": "member",
  "firstName": "John",
  "username": "johndoe"
}

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"deleteMessage","params":{"botUsername":"my_bot","chatId":"-1001234567890","messageId":999}}' | jq .

Example response:

{
  "messageId": 999,
  "chatId": "-1001234567890",
  "deleted": true
}

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.

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"telegramBot","method":"downloadFile","params":{"botUsername":"my_bot","fileId":"AgACAgIAAxkBAAI..."}}' | jq .

Example response:

{
  "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mimeType": "image/jpeg",
  "fileSize": 45230,
  "fileName": "photo.jpg"
}

Response Format

All SDK responses return the operation payload wrapped in a standard envelope:

{
  "success": true,
  "data": { ... }
}

The data field contains the operation result. Error responses include:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Tips

• Use jq . to pretty-print responses, jq .data to extract just the payload
• For list operations, results are in data.results or directly in data (check examples)
• Pass --fail-with-body to curl to see error details on HTTP failures
• Store the API key in a variable: export API_KEY="your-key"