Merge pull request chigwell#283 from alexey-igrychev/feat/vote-poll

feat(messages): add voting in existing polls

Author: chigwell

README.md

@@ -60,6 +60,14 @@ The server currently includes 80+ MCP tools grouped into these areas:
 - **Messages:** send, schedule, edit, delete, forward, pin, unpin, mark read, reply, search, inspect context, create polls, manage reactions, inspect inline buttons, and press inline callbacks. `send_message`, `reply_to_message`, and `edit_message` support classic formatting (`parse_mode='md'`/`'html'`) and server-side rich formatting (`parse_mode='rich'`/`'rich_markdown'`/`'rich_html'` — full Markdown/HTML with tables, headings, formulas, and collapsible sections). Rich modes require Telegram Premium on the account; Premium is re-checked on every call, and without it nothing is sent — the tool returns a structured `telegram_premium_required` result so the agent can reformat with classic modes and retry. `send_message`, `reply_to_message`, and `edit_message` also accept `format_date` to render a date as a tappable chip.
 
 `get_message_reactions` returns an empty list for a message with no reactions. To reuse a custom reaction, pass the returned `custom:<document_id>` value to `send_reaction`.
+
+`vote_poll(chat_id, message_id, option_indices, account=None)` votes in an existing poll.
+Read the poll with `get_messages` first, then select zero-based answer indices: `[0]`
+for the first answer, or `[0, 2]` for the first and third in a multiple-choice poll.
+This may replace an existing vote; empty selections, duplicate or out-of-range
+indices, closed polls, and multiple answers in single-choice polls are rejected.
+Telegram enforces voting permissions and restrictions on changing quiz votes.
+
 - **Contacts:** list, search, add, delete, block, unblock, import, export, inspect direct chats, find recent contact interactions, and remember contacts by the names you actually use (see below).
 
 ### Remembered contacts

telegram_mcp/tools/messages.py

@@ -2,6 +2,7 @@
 
 from telegram_mcp.runtime import *
 from telegram_mcp import transcription
+from pydantic import StrictInt
 
 # Domain used to build message permalinks. Overridable because the default is a
 # single point of failure: on 2026-07-13 the .me registry put t.me on serverHold
@@ -2285,6 +2286,63 @@ async def create_poll(
         )
 
 
+@mcp.tool(annotations=ToolAnnotations(title="Vote Poll", openWorldHint=True, destructiveHint=True))
+@with_account(readonly=False)
+@validate_id("chat_id")
+async def vote_poll(
+    chat_id: Union[int, str],
+    message_id: StrictInt,
+    option_indices: List[StrictInt],
+    account: Optional[str] = None,
+) -> str:
+    """Vote in an existing Telegram poll, replacing the current vote if allowed.
+
+    Args:
+        chat_id: The ID or username of the chat containing the poll.
+        message_id: The message ID of the poll.
+        option_indices: Non-empty list of zero-based answer indices, in the order
+            shown by get_messages. Multiple indices require a multiple-choice poll.
+            This submits a vote; it does not press an inline keyboard button.
+        account: Account name to use (required in multi-account mode).
+
+    Telegram enforces voting permissions and restrictions on changing quiz votes.
+    """
+    try:
+        if type(message_id) is not int or message_id <= 0:
+            return "Error: message_id must be a positive integer."
+        if not option_indices or any(type(i) is not int for i in option_indices):
+            return "Error: option_indices must be a non-empty list of integers."
+        if len(set(option_indices)) != len(option_indices):
+            return "Error: option_indices must not contain duplicates."
+
+        cl = get_client(account)
+        entity = await resolve_entity(chat_id, cl)
+        if is_chat_allowlist_enabled() and not is_chat_allowed(chat_id, entity):
+            raise ChatAccessDeniedError(check_chat_access(chat_id, entity))
+
+        message = await cl.get_messages(entity, ids=message_id)
+        if message is None or not isinstance(message.media, types.MessageMediaPoll):
+            return "Error: Message not found or does not contain a poll."
+        poll = message.media.poll
+        if poll.closed:
+            return "Error: Poll is closed."
+        if len(option_indices) > 1 and not poll.multiple_choice:
+            return "Error: This poll only allows one answer."
+        if any(i < 0 or i >= len(poll.answers) for i in option_indices):
+            return "Error: Answer index out of range (indices are zero-based)."
+
+        await cl(
+            functions.messages.SendVoteRequest(
+                peer=entity,
+                msg_id=message_id,
+                options=[poll.answers[i].option for i in option_indices],
+            )
+        )
+        return f"Vote submitted for poll {message_id} in chat {chat_id}."
+    except Exception as e:
+        return log_and_format_error("vote_poll", e, chat_id=chat_id, message_id=message_id)
+
+
 @mcp.tool(
     annotations=ToolAnnotations(
         title="Send Reaction", openWorldHint=True, destructiveHint=False, idempotentHint=True
@@ -2774,6 +2832,7 @@ async def export_unread_messages(
     "get_history",
     "get_pinned_messages",
     "create_poll",
+    "vote_poll",
     "send_reaction",
     "remove_reaction",
     "get_message_reactions",

tests/test_vote_poll.py

@@ -0,0 +1,165 @@
+"""Exercise poll voting through the registered tool and real Telethon TL objects."""
+
+from datetime import datetime, timezone
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from mcp.server.fastmcp.exceptions import ToolError
+from telethon import errors, types
+from telethon.tl.functions.messages import SendVoteRequest
+
+from telegram_mcp import runtime
+from telegram_mcp.tools import messages
+
+
+@pytest.fixture
+def voting(monkeypatch):
+    poll = types.Poll(
+        id=77,
+        hash=0,
+        question=types.TextWithEntities("Pick a drink", []),
+        answers=[
+            types.PollAnswer(types.TextWithEntities(text, []), option)
+            for text, option in [
+                ("Tea", b"tea-id"),
+                ("Water", b"\xff\x10"),
+                ("Juice", b"juice-id"),
+            ]
+        ],
+        closed=False,
+        multiple_choice=False,
+    )
+    message = types.Message(
+        id=42,
+        peer_id=types.PeerChat(123),
+        date=datetime.now(timezone.utc),
+        message="",
+        media=types.MessageMediaPoll(poll, types.PollResults()),
+    )
+    client = AsyncMock()
+    client.get_messages.return_value = message
+    entity = types.InputPeerChat(123)
+    get_client = Mock(return_value=client)
+    monkeypatch.setattr(messages, "get_client", get_client)
+    monkeypatch.setattr(messages, "resolve_entity", AsyncMock(return_value=entity))
+    monkeypatch.setattr(runtime, "is_multi_mode", lambda: False)
+    monkeypatch.setattr(runtime, "ALLOWED_CHAT_IDS", None)
+    monkeypatch.delenv("TELEGRAM_ALLOWED_CHAT_IDS", raising=False)
+    return SimpleNamespace(
+        poll=poll, message=message, client=client, entity=entity, get_client=get_client
+    )
+
+
+async def call_vote(**kwargs):
+    args = {"chat_id": -123, "message_id": 42, "option_indices": [1], **kwargs}
+    return await messages.vote_poll(**args)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("indices", [[1], [2, 0]])
+async def test_vote_sends_real_option_bytes(voting, indices):
+    voting.poll.multiple_choice = len(indices) > 1
+    result = await call_vote(option_indices=indices, account="personal")
+    assert result == "Vote submitted for poll 42 in chat -123."
+    voting.get_client.assert_called_once_with("personal")
+    voting.client.get_messages.assert_awaited_once_with(voting.entity, ids=42)
+    request = voting.client.call_args.args[0]
+    assert isinstance(request, SendVoteRequest)
+    assert request.peer == voting.entity
+    assert request.msg_id == 42
+    assert request.options == ([b"\xff\x10"] if indices == [1] else [b"juice-id", b"tea-id"])
+    assert bytes(request)  # Request is serializable by Telethon, not just a mock.
+    voting.client.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "args, expected",
+    [
+        ({"message_id": 0}, "positive integer"),
+        ({"message_id": -1}, "positive integer"),
+        ({"option_indices": []}, "non-empty list"),
+        ({"option_indices": [True]}, "list of integers"),
+        ({"option_indices": [1.0]}, "list of integers"),
+        ({"option_indices": [1, 1]}, "duplicates"),
+        ({"option_indices": [-1]}, "out of range"),
+        ({"option_indices": [3]}, "out of range"),
+        ({"option_indices": [0, 1]}, "only allows one answer"),
+    ],
+)
+async def test_invalid_votes_never_send(voting, args, expected):
+    assert expected in await call_vote(**args)
+    voting.client.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("kind", ["missing", "plain", "closed"])
+async def test_non_poll_and_closed_poll_never_send(voting, kind):
+    if kind == "missing":
+        voting.client.get_messages.return_value = None
+    elif kind == "plain":
+        voting.message.media = None
+    else:
+        voting.poll.closed = True
+    result = await call_vote()
+    assert ("Poll is closed" if kind == "closed" else "does not contain a poll") in result
+    voting.client.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_rpc_error_is_not_reported_as_success(voting):
+    voting.client.side_effect = errors.MessagePollClosedError(request=None)
+    result = await call_vote()
+    assert "Vote submitted" not in result
+    assert "Error" in result or "error" in result
+
+
+@pytest.mark.asyncio
+async def test_multi_account_requires_explicit_account(voting, monkeypatch):
+    monkeypatch.setattr(runtime, "is_multi_mode", lambda: True)
+    monkeypatch.setattr(runtime, "clients", {"personal": voting.client, "work": AsyncMock()})
+    assert "'account' is required" in await call_vote()
+    voting.client.get_messages.assert_not_awaited()
+    voting.client.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_chat_allowlist_blocks_vote(voting, monkeypatch):
+    monkeypatch.setenv("TELEGRAM_ALLOWED_CHAT_IDS", "-456")
+    assert "restricted by privacy policy" in await call_vote()
+    voting.client.get_messages.assert_not_awaited()
+    voting.client.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_resolved_chat_is_checked_before_reading(voting, monkeypatch):
+    monkeypatch.setattr(messages, "is_chat_allowlist_enabled", lambda: True)
+    monkeypatch.setattr(messages, "is_chat_allowed", lambda *args: False)
+    monkeypatch.setattr(
+        messages, "check_chat_access", lambda *args: "restricted by privacy policy"
+    )
+    result = await call_vote()
+    assert "Vote submitted" not in result
+    voting.client.get_messages.assert_not_awaited()
+    voting.client.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_registered_tool_accepts_username_and_rejects_coercion(voting):
+    tool = next(t for t in messages.mcp._tool_manager.list_tools() if t.name == "vote_poll")
+    assert not tool.annotations.readOnlyHint
+    assert tool.annotations.destructiveHint
+    result = await tool.run({"chat_id": "@example_chat", "message_id": 42, "option_indices": [1]})
+    assert "Vote submitted" in result
+    for invalid in [True, 1.0, "1"]:
+        voting.client.reset_mock()
+        with pytest.raises(ToolError):
+            await tool.run({"chat_id": -123, "message_id": 42, "option_indices": [invalid]})
+        voting.client.assert_not_awaited()
+
+
+def test_vote_exported_for_compatibility_entrypoint():
+    from telegram_mcp.tools import vote_poll
+
+    assert vote_poll is messages.vote_poll