Menu
Use Mirra to telegram messaging and chat management. Covers all Telegram SDK operations via REST API.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use Mirra to living dashboards — natively-rendered grids of typed widgets (stat, image_card, list, progress, sparkline) that flows keep current by pushing data into them..... Covers all Dashboards SDK operations via REST API.
Use Mirra to execute user-defined scripts in aws lambda. Covers all Scripts SDK operations via REST API.
Use Mirra to the places a space publishes to — its corporate x, blog, newsletter — and the drafted copy waiting to go out to them. use listchannels to see what this space.... Covers all Space Channels SDK operations via REST API.
Use Mirra to the space's shared work-ledger. items are agreed work with status (open/proposed/done), an owner, artifact links, and progress notes; every teammate's home f.... Covers all Work Items SDK operations via REST API.
The team work-ledger ritual for agents on a Mirra space: track agreed work, propose discoveries (then ask in chat), relay approvals, close what ships, and publish ONE narrated update card per work burst — revise, never stack. Rides the Mirra items adapter / MCP work-ledger tools.
START HERE for anything Mirra. Load this whenever the repo you're working in has a .mirra/ directory (it's linked to a Mirra team space), or your human mentions their Mirra space, teammates' updates, or the team ledger. Directs the ambient team rituals — record work in the shared ledger, publish update cards, ask the space before expanding scope — and indexes every detail-level mirra-* skill.
| name | mirra-telegram |
| description | Use Mirra to telegram messaging and chat management. Covers all Telegram SDK operations via REST API. |
| allowed-tools | Read, Bash(curl:*, jq:*) |
Telegram messaging and chat management
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 requires OAuth authentication. The user must have connected their Telegram account in the Mirra app before these operations will work.
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": "telegram",
"method": "{operation}",
"params": { ...args }
}' | jq .
Replace {operation} with the operation name from the table below.
Legacy alternative:
POST ${API_URL}/api/sdk/v1/telegram/{operation}with args as the request body also works but is not recommended for new integrations.
| Operation | Description |
|---|---|
sendMessage | Send a text message to a Telegram chat or user. Supports both chat IDs and usernames. |
searchChats | Powerful unified chat search with filtering, sorting, and activity tracking. Replaces getChats, f... |
searchMessages | Search for messages across Telegram chats. When chatIds is omitted, performs global search across... |
getChatMessages | Get message history from a specific Telegram chat with pagination and date filtering. |
getUnreadSummary | Get summary of unread messages across Telegram chats, including mentions and flattened last messa... |
markAsRead | Mark messages as read in a Telegram chat up to a specific message ID. |
getMentions | Get messages where the user is mentioned in Telegram chats. |
leaveGroup | Leave a Telegram group, supergroup, or channel. Removes the user from the group and clears it fro... |
sendMessageSend a text message to a Telegram chat or user. Supports both chat IDs and usernames.
Arguments:
chatId (string, required): Chat ID (numeric) or username (e.g., @username) to send the message to. Chat IDs can be obtained from searchChats operation.text (string, required): The text content of the message to sendReturns:
AdapterOperationResult: Normalized result with messageId, chatId, text, and sentAt timestamp
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":"telegram","method":"sendMessage","params":{"chatId":"123456789","text":"Hello from Mirra!"}}' | jq .
Example response:
{
"messageId": 12345,
"chatId": "123456789",
"text": "Hello from Mirra!",
"sentAt": "2024-01-15T10:30:00.000Z"
}
Warning: This is a destructive operation. Confirm with the user before executing.
searchChatsPowerful unified chat search with filtering, sorting, and activity tracking. Replaces getChats, findChatByName, and getRecentContacts. Use with no filters to list all chats. NOTE: Community chats and supergroups are type "group", not "channel" — avoid filtering by type unless you are sure of the exact type.
Arguments:
query (string, optional): Text to search in chat names/usernames. Supports fuzzy matching with relevance scoring.type (string, optional): Filter by chat type: "private", "group", "channel", or "all" (default: "all"). IMPORTANT: Telegram community chats and supergroups are type "group", NOT "channel". Only broadcast-only channels are type "channel". When unsure, omit this filter or use "all".inactiveSince (string, optional): Find chats with no activity since date. Accepts ISO date or relative like "30 days ago", "1 week ago"activeSince (string, optional): Find chats with activity since date. Accepts ISO date or relative like "7 days ago"hasUnread (boolean, optional): Filter by unread status: true = only unread, false = only readarchived (boolean, optional): Filter by archived statuspinned (boolean, optional): Filter by pinned statussortBy (string, optional): Sort results: "relevance" (default with query), "lastActivity" (default without query), "unreadCount", "name"limit (number, optional): Max results (default: 50, max: 100)offset (number, optional): Pagination offset (default: 0)forceRefresh (boolean, optional): Bypass cache and fetch fresh dataReturns:
AdapterOperationResult: Paginated results with chat details including lastMessageDate, unreadCount, memberCount, and relevanceScore (when query provided)
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":"telegram","method":"searchChats","params":{}}' | jq .
Example response:
{
"items": [
{
"id": "123",
"title": "John",
"type": "private",
"lastMessageDate": "2024-01-15T10:30:00Z",
"unreadCount": 2
}
],
"pagination": {
"totalCount": 100,
"limit": 50,
"offset": 0,
"hasMore": true
}
}
searchMessagesSearch for messages across Telegram chats. When chatIds is omitted, performs global search across all chats (replaces globalSearch operation).
Arguments:
query (string, required): Text query to search for in messageschatIds (array, optional): Array of chat IDs to search within. Omit for global search across all chats.chatType (string, optional): Filter by chat type (for global search): "private", "group", or "channel". IMPORTANT: Community chats and supergroups are "group", NOT "channel".fromDate (string, optional): ISO date string for start of date rangetoDate (string, optional): ISO date string for end of date rangelimit (number, optional): Maximum number of messages to return (default: 100, max: 100)senderId (string, optional): Filter messages by sender IDReturns:
AdapterOperationResult: Normalized messages array with flat structure: id, text, caption, date (ISO), chatId, senderId, senderName, hasMedia, mediaType, isOutgoing, replyToMessageId
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":"telegram","method":"searchMessages","params":{"query":"project update"}}' | jq .
Example response:
{
"messages": [
{
"id": "456",
"text": "Project update: Phase 1 complete",
"caption": null,
"date": "2024-01-15T10:30:00.000Z",
"chatId": "123456789",
"senderId": "987654321",
"senderName": "John",
"hasMedia": false,
"mediaType": null,
"isOutgoing": false,
"replyToMessageId": null
}
],
"count": 1
}
getChatMessagesGet message history from a specific Telegram chat with pagination and date filtering.
Arguments:
chatId (string, required): Chat ID to retrieve messages fromlimit (number, optional): Maximum number of messages to return (default: 50, max: 100)offsetId (number, optional): Message ID to use as pagination offsetminDate (string, optional): ISO date string for minimum message datemaxDate (string, optional): ISO date string for maximum message dateReturns:
AdapterOperationResult: Normalized messages array with flat structure including 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":"telegram","method":"getChatMessages","params":{"chatId":"123456789","limit":50}}' | jq .
Example response:
{
"messages": [
{
"id": "789",
"text": "Hello everyone!",
"caption": null,
"date": "2024-01-15T10:30:00.000Z",
"chatId": "123456789",
"senderId": "987654321",
"senderName": "John",
"hasMedia": false,
"mediaType": null,
"isOutgoing": false,
"replyToMessageId": null
}
],
"count": 1,
"chatId": "123456789"
}
getUnreadSummaryGet summary of unread messages across Telegram chats, including mentions and flattened last message info.
Arguments:
chatIds (array, optional): Array of chat IDs to filter by. If not provided, checks all chats.priorityOnly (boolean, optional): If true, only return chats with unread messagesgroupBy (string, optional): Group results by "chat" or "sender"Returns:
AdapterOperationResult: Normalized flat structure with chats array, totalUnread, chatsWithUnread. Each chat has flattened lastMessage fields (lastMessageText, lastMessageSender, lastMessageDate)
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":"telegram","method":"getUnreadSummary","params":{"priorityOnly":true}}' | jq .
Example response:
{
"chats": [
{
"chatId": "123456789",
"chatName": "Project Team",
"chatType": "group",
"unreadCount": 5,
"hasMention": true,
"lastMessageText": "Can someone review this?",
"lastMessageSender": "John",
"lastMessageDate": "2024-01-15T10:30:00.000Z"
}
],
"totalUnread": 5,
"chatsWithUnread": 1
}
markAsReadMark messages as read in a Telegram chat up to a specific message ID.
Arguments:
chatId (string, required): Chat ID to mark messages as read inmaxMessageId (number, optional): Maximum message ID to mark as read. If not provided, marks all messages as read.Returns:
AdapterOperationResult: Normalized result with success, chatId, and markedAt timestamp
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":"telegram","method":"markAsRead","params":{"chatId":"123456789"}}' | jq .
Example response:
{
"success": true,
"chatId": "123456789",
"markedAt": "2024-01-15T10:30:00.000Z"
}
getMentionsGet messages where the user is mentioned in Telegram chats.
Arguments:
chatIds (array, optional): Array of chat IDs to filter mentions bysinceDate (string, optional): ISO date string - only return mentions since this dateonlyUnread (boolean, optional): If true, only return unread mentionsReturns:
AdapterOperationResult: Normalized mentions array with flat message structure: id, text, caption, date (ISO), chatId, senderId, senderName, hasMedia, mediaType, isOutgoing, replyToMessageId
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":"telegram","method":"getMentions","params":{"onlyUnread":true}}' | jq .
Example response:
{
"mentions": [
{
"id": "456",
"text": "@you please check this",
"caption": null,
"date": "2024-01-15T10:30:00.000Z",
"chatId": "123456789",
"senderId": "987654321",
"senderName": "John",
"hasMedia": false,
"mediaType": null,
"isOutgoing": false,
"replyToMessageId": null
}
],
"count": 1
}
leaveGroupLeave a Telegram group, supergroup, or channel. Removes the user from the group and clears it from the local cache.
Arguments:
chatId (string, required): The ID of the group, supergroup, or channel to leave. Can be obtained from searchChats operation.Returns:
AdapterOperationResult: Normalized result with success, chatId, and leftAt timestamp
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":"telegram","method":"leaveGroup","params":{"chatId":"-1001234567890"}}' | jq .
Example response:
{
"success": true,
"chatId": "-1001234567890",
"leftAt": "2024-01-15T10:30:00.000Z"
}
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"
}
}
jq . to pretty-print responses, jq .data to extract just the payloaddata.results or directly in data (check examples)--fail-with-body to curl to see error details on HTTP failuresexport API_KEY="your-key"