Feature: Support Telegram Guest Bots (Bot API 10.0)

[Rustam-Z]

Summary

Bot API 10.0 (April 28, 2025) introduced Guest Bots — bots can now receive messages from chats they're not members of. This is directly relevant to Luna/pyclaudir: it would allow deployment into new groups without requiring full membership, reducing friction for new users.

What are Guest Bots?

A user can invoke a bot from any chat (even one the bot hasn't joined) via a guest query. The bot receives the message, processes it, and replies — without ever being added as a member.

New API surface to support

Element	Type	Description
guest_query_id	string	Unique ID of the guest query; used to respond via answerGuestQuery()
guest_bot_caller_user	User	The user who initiated the guest interaction
guest_bot_caller_chat	Chat	The chat from which the guest query came
supports_guest_queries	bool	Field on User — whether a bot supports guest queries
answerGuestQuery()	Method	Send a reply back into the originating chat
SentGuestMessage	Class	Represents the message sent back via answerGuestQuery()

What pyclaudir needs

1. Dispatcher changes — detect incoming updates with guest_query_id present and route them as a new message type (e.g. GuestMessage)
2. Context injection — populate guest_bot_caller_user and guest_bot_caller_chat into the <msg> envelope Luna receives, so she knows who asked and from where
3. Reply routing — when Luna calls send_message / reply_to_message in response to a guest query, the harness should use answerGuestQuery() instead of the normal send path
4. supports_guest_queries flag — set this to true in bot settings once the above is implemented

UX benefit

Luna could be invoked in groups without needing to be added as a member first. Lower barrier to entry for new communities trying Luna out.

References

• Bot API 10.0 Changelog — April 28, 2025
• Suggested by @Bayramov_S

[Rustam-Z]

Note: Guest Bots is opt-in via a toggle in BotFather bot settings. It's off by default, so no action needed on the Telegram side until the harness support described above is implemented and ready to ship.

[Rustam-Z]

Access control requirement

Guest queries must be gated through the existing /access policy before the bot processes them. Without this, enabling Guest Bots means anyone can invoke Luna from any chat — burning the operator's API tokens with no restriction.

Proposed behaviour:

• On incoming guest query, check guest_bot_caller_user against the current allowlist policy (owner_only / allowlist / open)
• If the user is not permitted → silently ignore or send a brief "not available" reply via answerGuestQuery()
• Only proceed to Claude if the user passes the gate

This makes guest mode safe to enable selectively — the operator controls who can reach the bot regardless of which chat they're writing from.