Telegram

SDK reference for telegram operations

Overview

Telegram messaging and chat management

• Category: social
• Auth Required: Yes
• Supported Modes: standard, delegated

Operations

sendMessage

Send 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 send

Returns:

AdapterOperationResult - Normalized result with messageId, chatId, text, and sentAt timestamp

Response Fields:

Example:

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

searchChats

Powerful unified chat search with filtering, sorting, and activity tracking. Replaces getChats, findChatByName, and getRecentContacts. Use with no filters to list all chats.

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")
• 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 read
• archived (boolean, optional): Filter by archived status
• pinned (boolean, optional): Filter by pinned status
• sortBy (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 data

Returns:

AdapterOperationResult - Paginated results with chat details including lastMessageDate, unreadCount, memberCount, and relevanceScore (when query provided)

Response Fields:

| pagination | TelegramPaginationInfo | Pagination metadata |

Example:

const result = await mirra.telegram.searchChats({});

searchMessages

Search 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 messages
• chatIds (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"
• fromDate (string, optional): ISO date string for start of date range
• toDate (string, optional): ISO date string for end of date range
• limit (number, optional): Maximum number of messages to return (default: 100, max: 100)
• senderId (string, optional): Filter messages by sender ID

Returns:

AdapterOperationResult - Normalized messages array with flat structure: id, text, caption, date (ISO), chatId, senderId, senderName, hasMedia, mediaType, isOutgoing, replyToMessageId

Response Fields:

| count | number | Number of messages returned |

Example:

const result = await mirra.telegram.searchMessages({
  query: "example"
});

getChatMessages

Get message history from a specific Telegram chat with pagination and date filtering.

Arguments:

• chatId (string, required): Chat ID to retrieve messages from
• limit (number, optional): Maximum number of messages to return (default: 50, max: 100)
• offsetId (number, optional): Message ID to use as pagination offset
• minDate (string, optional): ISO date string for minimum message date
• maxDate (string, optional): ISO date string for maximum message date

Returns:

AdapterOperationResult - Normalized messages array with flat structure including chatId

Response Fields:

| count | number | Number of messages returned | | chatId | string | Chat ID the messages are from (optional) |

Example:

const result = await mirra.telegram.getChatMessages({
  chatId: "abc123"
});

getUnreadSummary

Get 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 messages
• groupBy (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)

Response Fields:

| totalUnread | number | Total unread messages across all chats | | chatsWithUnread | number | Number of chats with unread messages |

Example:

const result = await mirra.telegram.getUnreadSummary({});

markAsRead

Mark messages as read in a Telegram chat up to a specific message ID.

Arguments:

• chatId (string, required): Chat ID to mark messages as read in
• maxMessageId (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

Response Fields:

Example:

const result = await mirra.telegram.markAsRead({
  chatId: "abc123"
});

getMentions

Get messages where the user is mentioned in Telegram chats.

Arguments:

• chatIds (array, optional): Array of chat IDs to filter mentions by
• sinceDate (string, optional): ISO date string - only return mentions since this date
• onlyUnread (boolean, optional): If true, only return unread mentions

Returns:

AdapterOperationResult - Normalized mentions array with flat message structure: id, text, caption, date (ISO), chatId, senderId, senderName, hasMedia, mediaType, isOutgoing, replyToMessageId

Response Fields:

| count | number | Number of mentions returned |

Example:

const result = await mirra.telegram.getMentions({});

leaveGroup

Leave 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

Response Fields:

Example:

const result = await mirra.telegram.leaveGroup({
  chatId: "abc123"
});