telebot_py.routing¶

Routing: handlers that direct incoming updates to callbacks.

telebot_py.routing.async_conversation.conversation¶

Async conversation controller handed to registered flows (T031).

class telebot_py.routing.async_conversation.conversation.AsyncConversation(name: str, context: t.Any, session_key: SessionKey, manager: AsyncConversationManager, *, user_id: int | None = None, chat_id: int | str | None = None, default_timeout: float | None = None)¶

Bases: object

Controller suspending and resuming a linear async/await flow.

Every wait*/ask call registers a pending wait with the manager, suspends the flow, and resumes it when the next routed update arrives — mirrors the node AsyncConversation controller.

Example

>>> async def flow(conversation, context):
...     name = await conversation.ask("What is your name?")
...     await context.bot.send_message(100, f"Hi {name}!")

Variables:

name – The registered conversation name this session runs.
context – The callback context that started the session.
user_id – The user this session is scoped to, when known.
chat_id – The chat this session is scoped to, when known.

async ask(text: str, filter: MessageFilter | None = None, timeout: float | None = None) → str¶

Send a prompt and suspend until the user’s text answer arrives.

Parameters:

text – The prompt message to send.
filter – Optional message filter the answer must satisfy.
timeout – Seconds to wait before raising.

Returns:

The text of the answering message (possibly empty).

Raises:

ConversationTimeoutError – When the wait exceeds the timeout.

exit() → NoReturn¶

End the conversation flow immediately.

Raises:: ConversationExitSignal – Always; the runner catches it to close the session cleanly.

async wait(filter: Callable[[Update], bool] | None = None, timeout: float | None = None) → Update¶

Suspend until the next update satisfying filter arrives.

Parameters:

filter – Optional predicate the incoming update must satisfy.
timeout – Seconds to wait before raising; falls back to the handler-level default timeout.

Returns:

The update that resumed the conversation.

Raises:

ConversationTimeoutError – When the wait exceeds the timeout.

async wait_for_callback_query(pattern: str | Pattern[str] | None = None, timeout: float | None = None) → CallbackQuery¶

Suspend until the next callback query (optionally matching pattern).

Parameters:

pattern – Optional exact-match string or compiled regex applied to callback_query.data.
timeout – Seconds to wait before raising.

Returns:

The callback query that resumed the conversation.

Raises:

ConversationTimeoutError – When the wait exceeds the timeout.

async wait_for_message(filter: MessageFilter | None = None, timeout: float | None = None) → Message¶

Suspend until the next message (optionally matching filter).

Parameters:

filter – Optional message filter the response must satisfy.
timeout – Seconds to wait before raising.

Returns:

The message that resumed the conversation.

Raises:

ConversationTimeoutError – When the wait exceeds the timeout.

telebot_py.routing.async_conversation.conversation.SessionKey¶

(chat_id, user_id) tuple; components may be None.

Type:: Session key

alias of tuple[Any, Any]

telebot_py.routing.async_conversation.handler¶

Handler adapter exposing async conversations to the dispatcher (T031).

class telebot_py.routing.async_conversation.handler.AsyncConversationHandler(fn: AsyncConversationFn, *, entry_points: Sequence[BaseHandler] | None = None, entry_command: str | None = None, entry_filter: MessageFilter | None = None, name: str = 'main', timeout: float | None = None)¶

Bases: BaseHandler

Handler running a registered async conversation flow.

Combines the node manager architecture with the dispatcher: entry triggers (entry_points, entry_command, or entry_filter) start the flow; while the flow suspends at a wait/ask, matching updates resume it instead of hitting the entry triggers again.

Example

>>> async def quiz(conversation, context):
...     name = await conversation.ask("What is your name?")
...     await context.bot.send_message(100, f"Hi {name}!")
>>> handler = AsyncConversationHandler(quiz, entry_command="quiz")

Variables:

manager – The session manager owning this handler’s flows.
name – The registered flow name this handler enters.
entry_points – Handlers whose match starts the flow.
entry_command – Command name (without slash) starting the flow.
entry_filter – Message filter whose match starts the flow.
timeout – Default wait timeout in seconds for the flow.

check_update(update: object) → bool¶

Return True when a pending session or an entry trigger matches.

Parameters:: update – The incoming update.
Returns:: True when this handler will process the update.

async handle_update(update: Update, context: Any, check_result: Any = None) → None¶

Resume the pending session or start the flow for this update.

Parameters:

update – The incoming update.
context – The callback context for this dispatch.
check_result – Ignored; the match was recorded by check_update.

Raises:

Exception – Whatever the conversation flow raises.

telebot_py.routing.async_conversation.manager¶

Async conversation session manager and context helper (T031).

class telebot_py.routing.async_conversation.manager.AsyncConversationManager¶

Bases: object

Registers named flows and routes updates into their active sessions.

Python parity of the node AsyncConversationManager: register a flow under a name, enter it (the runner task suspends at the first wait), and each subsequent update is delivered through handle_update() until the flow finishes.

Example

>>> manager = AsyncConversationManager()
>>> manager.register("survey", survey_flow)
>>> await manager.enter("survey", context)

clear_pending_wait(session_key: tuple[Any, Any]) → None¶

Drop the session’s pending wait (timeout path).

Parameters:: session_key – The session whose wait is cleared.

async enter(name: str, context: Any, user_id: int | None = None, chat_id: int | str | None = None) → None¶

Start a registered flow, resolving once it suspends or finishes.

Parameters:

name – The registered conversation name.
context – The callback context handed to the flow.
user_id – Override the session’s user id (defaults to the context update’s effective user).
chat_id – Override the session’s chat id (defaults to the context update’s effective chat).

Raises:

ValueError – If name is not registered.
Exception – Whatever the flow raises before its first wait.

get_session_key(user_id: int | None = None, chat_id: int | str | None = None) → tuple[Any, Any]¶

Return the (chat_id, user_id) session key for the ids.

Parameters:

user_id – The user id, when known.
chat_id – The chat id, when known.

Returns:

The session key tuple; components may be None.

async handle_update(update: Update) → bool¶

Deliver update to the matching session’s pending wait.

Awaits the flow until it suspends at its next wait or finishes, so sequential updates never overtake an in-progress resume.

Parameters:: update – The incoming update.
Returns:: True when a session consumed the update.
Raises:: Exception – Whatever the resumed flow raises.

has_active_session(user_id: int | None = None, chat_id: int | str | None = None) → bool¶

Return whether a session is active for the given user/chat.

Parameters:

user_id – The user id, when known.
chat_id – The chat id, when known.

Returns:

True when a registered flow session is in flight.

matches_pending(user_id: int | None, chat_id: int | str | None, update: Update) → bool¶

Return whether the session for this user/chat awaits update.

Parameters:

user_id – The user id, when known.
chat_id – The chat id, when known.
update – The incoming update to test against the pending predicate.

Returns:

True when a pending wait exists and its predicate accepts the update.

register(name: str, handler: Callable[[AsyncConversation, Any], Awaitable[None]], *, default_timeout: float | None = None) → None¶

Register a flow under name, replacing any previous entry.

Parameters:

name – Non-empty conversation identifier.
handler – The coroutine function implementing the flow.
default_timeout – Wait timeout applied when flow waits omit one.

Raises:

ValueError – If name is blank.

register_pending_wait(session_key: tuple[Any, Any], predicate: Callable[[Update], bool] | None, future: Future[Update]) → None¶

Record a flow’s pending wait so the next update can resolve it.

Parameters:

session_key – The session registering the wait.
predicate – Optional predicate gating which update resolves it.
future – The future resolved with the matching update.

class telebot_py.routing.async_conversation.manager.ConversationContextHelper(context: Any, manager: AsyncConversationManager)¶

Bases: object

Convenience wrapper entering conversations from within callbacks.

Example

>>> helper = ConversationContextHelper(context, handler.manager)
>>> if not helper.active:
...     await helper.enter("survey")

property active: bool¶: Whether this context’s user/chat currently has an active session.

async enter(name: str) → None¶

Enter the registered conversation name for this context.

Parameters:: name – The registered conversation name.
Raises:: ValueError – If name is not registered.

telebot_py.routing.async_conversation.types¶

Async conversation types, errors, and callback signatures.

telebot_py.routing.async_conversation.types.AsyncConversationFn¶

(conversation, context) -> None awaited as a coroutine; suspends at each controller wait.

Type:: Conversation flow signature

alias of Callable[[AsyncConversation, Any], Awaitable[None]]

exception telebot_py.routing.async_conversation.types.ConversationExitSignal¶

Bases: Exception

Internal control signal raised by AsyncConversation.exit().

Not an error condition: conversation runners catch it to end the flow cleanly. Distinct from ConversationTimeoutError.

exception telebot_py.routing.async_conversation.types.ConversationTimeoutError(message: str = 'Conversation wait timed out.')¶

Bases: Exception

Raised when a conversation wait exceeds its allocated timeout.

Example

>>> try:
...     await conversation.wait(timeout=60)
... except ConversationTimeoutError:
...     print("user never answered")

telebot_py.routing.async_conversation.types.UpdatePredicate¶

Synchronous predicate deciding whether an update satisfies a wait.

alias of Callable[[Update], bool]

telebot_py.routing.conversation¶

Stateful conversation handler: a finite-state machine over updates (T029).

class telebot_py.routing.conversation.ConversationHandler(*, entry_points: Sequence[BaseHandler], states: Mapping[object, Sequence[BaseHandler]], fallbacks: Sequence[BaseHandler] | None = None, per_chat: bool = True, per_user: bool = True, per_message: bool = False, timeout: float | None = None, time_fn: Callable[[], float] | None = None, name: str | None = None, persistent: bool = False, allow_reentry: bool = False, map_to_parent: Mapping[object, object] | None = None)¶

Bases: BaseHandler

Multi-step conversation handler (python-telegram-bot parity).

entry_points start a conversation, states maps each state to the handlers routing the next update, and the state a callback returns moves the conversation; returning END closes it. fallbacks run from any state and reset the conversation. With timeout set, idle conversations are routed to the TIMEOUT pseudo-state handlers when present, or closed otherwise.

Example

>>> handler = ConversationHandler(
...     entry_points=[CommandHandler("start", start)],
...     states={NAME: [MessageHandler(filters.TEXT, name)],
...             AGE: [MessageHandler(filters.TEXT, age)]},
...     fallbacks=[CommandHandler("cancel", cancel)],
... )

Variables:

entry_points – Handlers that start the conversation.
states – Handlers keyed by state (plus optional TIMEOUT entry).
fallbacks – Handlers that reset the conversation from any state.
conversations – In-memory state per conversation key.

END: ClassVar[int] = -1¶

TIMEOUT: ClassVar[int] = -2¶

check_update(update: object) → bool¶

Return True when an entry/state/fallback handler matches for this update.

Parameters:: update – The incoming update.
Returns:: True when this conversation handler will process the update.

conversations: dict[tuple[Any, ...], object]¶

async handle_update(update: Update, context: Any, check_result: Any = None) → Any¶

Dispatch to the matched handler and transition the conversation state.

Parameters:

update – The incoming update.
context – The callback context for this dispatch.
check_result – Ignored; the match was recorded by check_update.

Returns:

The new state, the mapped parent state for nested conversations, END when the conversation closed, or None when nothing matched or the state was unchanged.

states: dict[object, list[BaseHandler]]¶

telebot_py.routing.conversation.ConversationKey¶

(chat_id, user_id[, message_id]) components included per the handler’s per_chat/per_user/per_message flags.

Type:: Conversation storage key

alias of tuple[Any, …]

telebot_py.routing.conversation.END: Final[int] = -1¶: Sentinel state returned by a callback to close the conversation.

telebot_py.routing.conversation.TIMEOUT: Final[int] = -2¶: Sentinel pseudo-state keyed handlers run when a conversation times out.

telebot_py.routing.handlers.base¶

Base handler contract for routing updates to callbacks.

class telebot_py.routing.handlers.base.BaseHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: object

Base class for all update handlers.

Mirrors python-telegram-bot’s BaseHandler with a snake_case contract: check_update() decides whether an update matches (returning a truthy check result), collect_additional_context() enriches the callback context with data derived from that result, and handle_update() runs the callback. Group ordering and blocking across handlers are the dispatcher’s concern.

Variables:

callback – The callable invoked when this handler matches. May be a coroutine function or a plain function.
block – Whether the dispatcher should await the callback before processing subsequent handlers.

check_update(update: object) → Any¶

Determine whether update should be handled by this handler.

Callers must test the result with check_result is not None and check_result is not False rather than truthiness: a matched command without arguments yields an empty list, which is falsy but still a match (parity with python-telegram-bot).

Parameters:: update – The incoming update (typed object so handlers can reject any non-update value, parity with python-telegram-bot).
Returns:: A check result on a match (True, an args list, or a data-filter dict), None/False otherwise.

collect_additional_context(context: Any, update: Update, check_result: Any) → None¶

Enrich context with data derived from check_result.

The base implementation merges dict-valued check results (produced by data filters) onto the context as attributes.

Parameters:

context – The callback context being populated.
update – The update being processed.
check_result – The value check_update() returned.

async handle_update(update: Update, context: Any, check_result: Any = None) → Any¶

Collect context data and invoke callback.

Parameters:

update – The update being processed.
context – The callback context for this dispatch.
check_result – The value check_update() returned.

Returns:

Whatever the callback returns.

telebot_py.routing.handlers.base.HandlerCallback¶

Handler callback signature. The second argument is the kernel’s CallbackContext once built by dispatch; it is duck-typed here (a plain object accepting attribute assignment) so handlers do not depend on the kernel module existing yet.

alias of Callable[[Update, Any], Awaitable[Any] | Any]

telebot_py.routing.handlers.business¶

Handlers for Telegram Business connection and business message updates.

class telebot_py.routing.handlers.business.BusinessConnectionHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: BaseHandler

Handler for Telegram Business account connection changes.

Matches business_connection updates, mirroring the node BusinessConnectionHandler.

check_update(update: object) → bool¶

Return whether the update carries a business connection change.

Parameters:: update – The incoming update.
Returns:: True when the update carries a business_connection payload.

class telebot_py.routing.handlers.business.BusinessMessagesHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: BaseHandler

Handler for messages in connected Telegram Business accounts.

Matches business_message, edited_business_message, and deleted_business_messages updates, mirroring the node BusinessMessagesHandler.

check_update(update: object) → bool¶

Return whether the update is a business message event.

Parameters:: update – The incoming update.
Returns:: True when the update carries any business message payload.

telebot_py.routing.handlers.callback_query¶

Handler for callback queries from inline keyboards.

class telebot_py.routing.handlers.callback_query.CallbackQueryHandler(pattern: str | Pattern[str] | Callable[[str], bool] | None, callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: BaseHandler

Handler for incoming callback queries.

With no pattern every callback query matches. Otherwise the query’s data must satisfy the pattern: re.fullmatch semantics for string and compiled patterns, a plain call for callable patterns. A regex match is exposed on the callback context as context.matches.

Variables:: pattern – The pattern constraining which callback queries match.

check_update(update: object) → bool¶

Return whether the update carries a matching callback query.

Parameters:: update – The incoming update.
Returns:: True when the callback query satisfies the pattern.

collect_additional_context(context: Any, update: Update, check_result: Any) → None¶

Store the regex match on context.matches when applicable.

Parameters:

context – The callback context being populated.
update – The update being processed.
check_result – The value check_update() returned.

telebot_py.routing.handlers.callback_query.CallbackQueryPattern = str | re.Pattern[str] | collections.abc.Callable[[str], bool]¶

a string or compiled regular expression (matched with fullmatch), or a predicate callable.

Type:: A pattern tested against callback_query.data

telebot_py.routing.handlers.chat_member¶

Handlers for chat membership changes and poll answers.

class telebot_py.routing.handlers.chat_member.ChatMemberHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], chat_member_types: int = 3, *, block: bool = True)¶

Bases: BaseHandler

Handler for chat membership changes.

Matches chat_member and/or my_chat_member updates depending on the chat_member_types filter mask, mirroring the node ChatMemberHandler constants.

Variables:: chat_member_types – Filter mask selecting which chat member updates to handle (CHAT_MEMBER, MY_CHAT_MEMBER, or ANY).

ANY = 3¶: Target any chat member update.

CHAT_MEMBER = 1¶: Target only member updates of other users (chat_member).

MY_CHAT_MEMBER = 2¶: Target only updates for the bot itself (my_chat_member).

check_update(update: object) → bool¶

Return whether the update matches the requested member types.

Parameters:: update – The incoming update.
Returns:: True when the update carries a chat member update allowed by the configured mask, False otherwise.

class telebot_py.routing.handlers.chat_member.PollAnswerHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: BaseHandler

Handler for user responses to non-anonymous polls.

Matches poll_answer updates, mirroring the node PollAnswerHandler.

check_update(update: object) → bool¶

Return whether the update carries a poll answer.

Parameters:: update – The incoming update.
Returns:: True when the update carries a poll_answer payload.

telebot_py.routing.handlers.chat_request¶

Handlers for chat join requests and chat boost updates.

class telebot_py.routing.handlers.chat_request.ChatBoostHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], boost_types: int = 3, *, block: bool = True)¶

Bases: BaseHandler

Handler for chat boost additions and removals.

Matches chat_boost and/or removed_chat_boost updates depending on the boost_types filter mask, mirroring the node ChatBoostHandler constants.

Variables:: boost_types – Filter mask selecting which boost events to handle (ADDED, REMOVED, or ANY).

ADDED = 1¶: Target only added or updated boosts (chat_boost).

ANY = 3¶: Target any boost event.

REMOVED = 2¶: Target only removed boosts (removed_chat_boost).

check_update(update: object) → bool¶

Return whether the update matches the configured boost filter.

Parameters:: update – The incoming update.
Returns:: True when the update carries a boost event allowed by the configured mask, False otherwise.

class telebot_py.routing.handlers.chat_request.ChatJoinRequestHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: BaseHandler

Handler for requests to join private chats or channels.

Matches chat_join_request updates, mirroring the node ChatJoinRequestHandler.

check_update(update: object) → bool¶

Return whether the update carries a chat join request.

Parameters:: update – The incoming update.
Returns:: True when the update carries a chat_join_request payload.

telebot_py.routing.handlers.command¶

Handler for Telegram bot commands such as /start.

class telebot_py.routing.handlers.command.CommandHandler(command: str | Sequence[str], callback: Callable[[Update, Any], Awaitable[Any] | Any], *, filters: MessageFilter | None = None)¶

Bases: BaseHandler

Handler for bot commands like /start.

Command names are compared against the message text with the leading / and any @BotName mention suffix stripped, case-insensitively. The words following the command are exposed on the callback context as context.args.

Variables:

commands – Normalized (lower-cased, slash-less) command names.
filters – Optional message filter gating the match after the command name matched.

check_update(update: object) → list[str] | None¶

Return the command’s argument list when the update matches.

Parameters:: update – The incoming update.
Returns:: The argument words following the command (possibly empty) on a match, None otherwise.

collect_additional_context(context: Any, update: Update, check_result: Any) → None¶

Store the parsed command arguments on context.args.

Parameters:

context – The callback context being populated.
update – The update being processed.
check_result – The argument list check_update() returned.

telebot_py.routing.handlers.inline_query¶

Handlers for inline queries and chosen inline results.

class telebot_py.routing.handlers.inline_query.ChosenInlineResultHandler(pattern: str | Pattern[str] | Callable[[str], bool] | None, callback: Callable[[Update, Any], Awaitable[Any] | Any], *, block: bool = True)¶

Bases: BaseHandler

Handler for results chosen by users from inline queries.

With no pattern every chosen result matches. Otherwise the target — the chosen result’s query when non-empty, else its result_id — must satisfy the pattern: string patterns match either result_id or query exactly, compiled regular expressions use search semantics on the target, callable patterns receive the target — mirroring the node ChosenInlineResultHandler. A regex match is exposed on the callback context as context.matches.

Variables:: pattern – The pattern constraining which chosen results match.

check_update(update: object) → bool¶

Return whether the update carries a matching chosen result.

Parameters:: update – The incoming update.
Returns:: True when the chosen inline result satisfies the pattern.

collect_additional_context(context: Any, update: Update, check_result: Any) → None¶

Store the regex match on context.matches when applicable.

Parameters:

context – The callback context being populated.
update – The update being processed.
check_result – The value check_update() returned.

class telebot_py.routing.handlers.inline_query.InlineQueryHandler(pattern: str | Pattern[str] | Callable[[str], bool] | None, callback: Callable[[Update, Any], Awaitable[Any] | Any], *, block: bool = True)¶

Bases: BaseHandler

Handler for inline queries triggered by typing @bot query.

With no pattern every inline query matches. Otherwise the query text must satisfy the pattern: exact equality for strings, search semantics for compiled regular expressions, a plain call for callable patterns — mirroring the node InlineQueryHandler. A regex match is exposed on the callback context as context.matches.

Variables:: pattern – The pattern constraining which inline queries match.

check_update(update: object) → bool¶

Return whether the update carries a matching inline query.

Parameters:: update – The incoming update.
Returns:: True when the inline query satisfies the pattern.

collect_additional_context(context: Any, update: Update, check_result: Any) → None¶

Store the regex match on context.matches when applicable.

Parameters:

context – The callback context being populated.
update – The update being processed.
check_result – The value check_update() returned.

telebot_py.routing.handlers.inline_query.InlineQueryPattern = str | re.Pattern[str] | collections.abc.Callable[[str], bool]¶: A pattern tested against the inline query text (or chosen-result target): a string (exact equality), a compiled regular expression (search semantics), or a predicate callable. Mirrors the node pattern option.

telebot_py.routing.handlers.message¶

Handler routing updates whose message passes a filter.

class telebot_py.routing.handlers.message.MessageHandler(filters: MessageFilter, callback: Callable[[Update, Any], Awaitable[Any] | Any])¶

Bases: BaseHandler

Handler for updates whose message satisfies a message filter.

check_update returns the filter’s result: True/False for plain filters, or the extracted-data dict for data filters (e.g. Regex), which is then merged onto the callback context.

Variables:: filters – The filter gating this handler.

check_update(update: object) → Any¶

Return the filter result for the update’s effective message.

Parameters:: update – The incoming update.
Returns:: The filter result (bool or data-filter dict); falsy when the update carries no message or the filter rejects it.

telebot_py.routing.handlers.payment¶

Handlers for payments, invoicing, and paid media updates.

class telebot_py.routing.handlers.payment.PreCheckoutQueryHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: BaseHandler

Handler for incoming pre-checkout queries.

Matches pre_checkout_query updates, allowing validation of shipping information and confirmation of the final order before payment processing. Mirrors the node PreCheckoutQueryHandler.

check_update(update: object) → bool¶

Return whether the update carries a pre-checkout query.

Parameters:: update – The incoming update.
Returns:: True when the update carries a pre_checkout_query payload.

class telebot_py.routing.handlers.payment.PurchasedPaidMediaHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: BaseHandler

Handler for purchased paid media events.

Matches purchased_paid_media updates, triggered when a user buys paid media with Telegram Stars. Mirrors the node PurchasedPaidMediaHandler.

check_update(update: object) → bool¶

Return whether the update carries a purchased paid media event.

Parameters:: update – The incoming update.
Returns:: True when the update carries a purchased_paid_media payload.

class telebot_py.routing.handlers.payment.ShippingQueryHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: BaseHandler

Handler for incoming shipping queries.

Matches shipping_query updates (flexible-price invoices), allowing the bot to provide available shipping options for the delivery address. Mirrors the node ShippingQueryHandler.

check_update(update: object) → bool¶

Return whether the update carries a shipping query.

Parameters:: update – The incoming update.
Returns:: True when the update carries a shipping_query payload.

telebot_py.routing.handlers.reaction¶

Handlers for message reaction updates.

class telebot_py.routing.handlers.reaction.MessageReactionCountHandler(callback: Callable[[Update, Any], Awaitable[Any] | Any], block: bool = True)¶

Bases: BaseHandler

Handler for anonymous reaction count updates on messages.

Matches message_reaction_count updates, mirroring the node MessageReactionCountHandler.

check_update(update: object) → bool¶

Return whether the update carries a reaction count update.

Parameters:: update – The incoming update.
Returns:: True when the update carries a message_reaction_count payload.

Bases: BaseHandler

Handler for user message reaction changes.

Matches message_reaction updates. Without a filter every reaction change matches; otherwise the reaction must satisfy the filter, which is tested against the update’s new_reaction list — mirroring the node MessageReactionHandler filter semantics.

Variables:: filter – Optional filter matching specific emojis, custom emoji IDs, paid reactions, or an arbitrary predicate.

check_update(update: object) → bool¶

Return whether the update carries a matching reaction change.

Parameters:: update – The incoming update.
Returns:: True when the update carries a message_reaction payload that satisfies the configured filter, False otherwise.

telebot_py.routing.handlers.reaction.ReactionFilter = str | collections.abc.Sequence[str] | telebot_py.types.reactions.ReactionTypeEmoji | telebot_py.types.reactions.ReactionTypeCustomEmoji | telebot_py.types.reactions.ReactionTypePaid | collections.abc.Callable[[telebot_py.types.update.Update], bool]¶

an emoji string, a sequence of emoji strings, a reaction type instance (emoji, custom emoji, or paid), or a predicate receiving the whole update.

Type:: Filter selecting which reaction changes match

telebot_py.routing.handlers.type¶

Handler matching updates via an arbitrary type predicate.

class telebot_py.routing.handlers.type.TypeHandler(type_predicate: Callable[[Update], bool], callback: Callable[[Update, Any], Awaitable[Any] | Any], *, block: bool = True)¶

Bases: BaseHandler

Handler that matches updates based on an arbitrary type predicate.

Any-update pass-through: the predicate receives the full update and its boolean result decides the match, mirroring the node TypeHandler.

Variables:: type_predicate – Function evaluating whether an update matches.

check_update(update: object) → bool¶

Return whether the type predicate is satisfied by the update.

Parameters:: update – The incoming update.
Returns:: True when the predicate returns a truthy value for the update, False otherwise (including for non-Update objects).

telebot_py.routing.handlers.type.TypePredicate¶

Predicate deciding whether an update matches a TypeHandler.

alias of Callable[[Update], bool]

telebot_py.routing.linear_conversation¶

Linear step-by-step conversation handler (T030).

class telebot_py.routing.linear_conversation.LinearConversationHandler(*, entry_points: Sequence[BaseHandler], steps: Sequence[Sequence[BaseHandler]], fallbacks: Sequence[BaseHandler] | None = None, per_chat: bool = True, per_user: bool = True, per_message: bool = False, timeout: float | None = None, time_fn: Callable[[], float] | None = None, name: str | None = None, persistent: bool = False)¶

Bases: BaseHandler

Conversation handler walking a fixed list of ordered steps.

Instead of a state graph, steps is an ordered sequence of handler lists: the entry points open the flow at step 0, each matching update advances exactly one step, and the flow closes after the last step. fallbacks reset the conversation from any step. Callback return values are ignored — order alone drives progress.

Example

>>> handler = LinearConversationHandler(
...     entry_points=[CommandHandler("survey", intro)],
...     steps=[[MessageHandler(filters.TEXT, ask_name)],
...            [MessageHandler(filters.TEXT, ask_age)]],
...     fallbacks=[CommandHandler("cancel", cancel)],
... )

Variables:

entry_points – Handlers that start the linear flow.
steps – Ordered step handler lists; the index is the persisted state.
fallbacks – Handlers that reset the conversation from any step.
conversations – In-memory step index per conversation key.

END: ClassVar[int] = -1¶

check_update(update: object) → bool¶

Return True when the entry, current step, or fallbacks match.

Parameters:: update – The incoming update.
Returns:: True when this conversation handler will process the update.

async handle_update(update: Update, context: Any, check_result: Any = None) → Any¶

Dispatch to the matched handler and advance the step exactly once.

Parameters:

update – The incoming update.
context – The callback context for this dispatch.
check_result – Ignored; the match was recorded by check_update.

Returns:

The new step index, END when the flow finished or was reset, or None when nothing matched.

telebot_py.routing¶

telebot_py.routing.async_conversation.conversation¶

telebot_py.routing.async_conversation.handler¶

telebot_py.routing.async_conversation.manager¶

telebot_py.routing.async_conversation.types¶

telebot_py.routing.conversation¶

telebot_py.routing.handlers.base¶

telebot_py.routing.handlers.business¶

telebot_py.routing.handlers.callback_query¶

telebot_py.routing.handlers.chat_member¶

telebot_py.routing.handlers.chat_request¶

telebot_py.routing.handlers.command¶

telebot_py.routing.handlers.inline_query¶

telebot_py.routing.handlers.message¶

telebot_py.routing.handlers.payment¶

telebot_py.routing.handlers.reaction¶

telebot_py.routing.handlers.type¶

telebot_py.routing.linear_conversation¶

telebot-py

Navigation

Related Topics