get_unread_messages
Retrieve all unread messages from a specific entity ID using the Telegram MCP Server. Simplify message management by accessing unread conversations in one step.
Instructions
get all unread messages from a given entity id
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No |
Implementation Reference
- mcp-server/mcp-server.py:20-25 (handler)The MCP tool handler for 'get_unread_messages'. It is registered with @mcp.tool and implements the tool logic by making an HTTP GET request to the backend API endpoint to retrieve unread messages for the given entity ID.@mcp.tool( name="get_unread_messages", description="get all unread messages from a given entity id", ) async def get_unread_messages(id: int = None) -> list[dict]: return get(f"{api_endpoint}get_unread_messages/{id}").json()
- http-server/http-api.py:46-56 (helper)HTTP FastAPI endpoint handler for /get_unread_messages/{chat_id}. Fetches the unread count from dialogs and retrieves that many recent messages using the get_messages helper, which is called by the MCP tool.@app.get("/get_unread_messages/{chat_id}") async def get_unread_messages(chat_id: int): dialogs = await get_chats() if chat_id not in dialogs: raise HTTPException(status_code=404, detail=f"Entity {chat_id} not found") dialog = dialogs[chat_id] unread_count = dialog["unread_count"] return await get_messages(chat_id=chat_id, count=unread_count)
- http-server/http-api.py:58-95 (helper)The core message fetching logic using Telethon client. Iterates over recent messages, formats sender entities, handles binary text, collects message data, and marks messages as read. This is invoked by the get_unread_messages HTTP endpoint.@app.get("/get_messages/{chat_id}") async def get_messages(chat_id: int, count: int = 0): entities = {} messages = [] e: Entity = await get_entity(entity=chat_id, raw=True) async for message in client.iter_messages(entity=e, reverse=False, limit=count): e_id: int = None if message.from_id is not None: e_id = message.from_id.user_id elif message.peer_id is not None: e_id = message.peer_id.user_id if e_id not in entities: entity = await client.get_entity(e_id) entities[e_id] = entity # Handle message text that might be binary message_text = message.message if isinstance(message_text, bytes): try: message_text = message_text.decode('utf-8', errors='replace') except Exception: message_text = '[Binary content]' messages += [ { "text": message_text, "date": message.date, "id": message.id, "from": await format_entity(entity=entities[e_id]), } ] await client.send_read_acknowledge(entity=chat_id, message=message) return messages