Events Reference

Here you will find a quick summary of all the methods and properties that you can access when working with events.

You can access the client that creates this event by doing event.client, and you should view the description of the events to find out what arguments it allows on creation and its attributes (the properties will be shown here).

Important

Remember that all events base ChatGetter! Please see FAQ if you don’t know what this means or the implications of it.

NewMessage

Occurs whenever a new text message or a message with media arrives.

Note

The new message event should be treated as a normal Message, with the following exceptions:

  • pattern_match is the match object returned by pattern=.
  • message is not the message string. It’s the Message object.

Remember, this event is just a proxy over the message, so while you won’t see its attributes and properties, you can still access them. Please see the full documentation for examples.

Full documentation for the NewMessage.

MessageEdited

Occurs whenever a message is edited. Just like NewMessage, you should treat this event as a Message.

Full documentation for the MessageEdited.

MessageDeleted

Occurs whenever a message is deleted. Note that this event isn’t 100% reliable, since Telegram doesn’t always notify the clients that a message was deleted.

It only has the deleted_id and deleted_ids attributes (in addition to the chat if the deletion happened in a channel).

Full documentation for the MessageDeleted.

MessageRead

Occurs whenever one or more messages are read in a chat.

Full documentation for the MessageRead.

inbox True if you have read someone else’s messages.
message_ids The IDs of the messages which contents’ were read.
get_messages Returns the list of Message which contents’ were read.
is_read Returns True if the given message (or its ID) has been read.

ChatAction

Occurs on certain chat actions, such as chat title changes, user join or leaves, pinned messages, photo changes, etc.

Full documentation for the ChatAction.

added_by The user who added users, if applicable (None otherwise).
kicked_by The user who kicked users, if applicable (None otherwise).
user The first user that takes part in this action.
input_user Input version of the self.user property.
user_id Returns the marked signed ID of the first user, if any.
users A list of users that take part in this action.
input_users Input version of the self.users property.
user_ids Returns the marked signed ID of the users, if any.
respond Responds to the chat action message (not as a reply).
reply Replies to the chat action message (as a reply).
delete Deletes the chat action message.
get_pinned_message If new_pin is True, this returns the Message object that was pinned.
get_added_by Returns added_by but will make an API call if necessary.
get_kicked_by Returns kicked_by but will make an API call if necessary.
get_user Returns user but will make an API call if necessary.
get_input_user Returns input_user but will make an API call if necessary.
get_users Returns users but will make an API call if necessary.
get_input_users Returns input_users but will make an API call if necessary.

UserUpdate

Occurs whenever a user goes online, starts typing, etc.

Full documentation for the UserUpdate.

user Alias for sender.
input_user Alias for input_sender.
user_id Alias for sender_id.
get_user Alias for get_sender.
get_input_user Alias for get_input_sender.
typing True if the action is typing a message.
uploading True if the action is uploading something.
recording True if the action is recording something.
playing True if the action is playing a game.
cancel True if the action was cancelling other actions.
geo True if what’s being uploaded is a geo.
audio True if what’s being recorded/uploaded is an audio.
round True if what’s being recorded/uploaded is a round video.
video True if what’s being recorded/uploaded is an video.
contact True if what’s being uploaded (selected) is a contact.
document True if what’s being uploaded is document.
photo True if what’s being uploaded is a photo.
last_seen Exact datetime.datetime when the user was last seen if known.
until The datetime.datetime until when the user should appear online.
online True if the user is currently online,
recently True if the user was seen within a day.
within_weeks True if the user was seen within 7 days.
within_months True if the user was seen within 30 days.

CallbackQuery

Occurs whenever you sign in as a bot and a user clicks one of the inline buttons on your messages.

Full documentation for the CallbackQuery.

id Returns the query ID.
message_id Returns the message ID to which the clicked inline button belongs.
data Returns the data payload from the original inline button.
chat_instance Unique identifier for the chat where the callback occurred.
via_inline Whether this callback was generated from an inline button sent via an inline query or not.
respond Responds to the message (not as a reply).
reply Replies to the message (as a reply).
edit Edits the message.
delete Deletes the message.
answer Answers the callback query (and stops the loading circle).
get_message Returns the message to which the clicked inline button belongs.

InlineQuery

Occurs whenever you sign in as a bot and a user sends an inline query such as @bot query.

Full documentation for the InlineQuery.

id Returns the unique identifier for the query ID.
text Returns the text the user used to make the inline query.
offset The string the user’s client used as an offset for the query.
geo If the user location is requested when using inline mode and the user’s device is able to send it, this will return the GeoPoint with the position of the user.
builder Returns a new InlineBuilder instance.
answer Answers the inline query with the given results.

Album

Occurs whenever you receive an entire album.

Full documentation for the Album.

grouped_id The shared grouped_id between all the messages.
text The message text of the first photo with a caption, formatted using the client’s default parse mode.
raw_text The raw message text of the first photo with a caption, ignoring any formatting.
is_reply True if the album is a reply to some other message.
forward The Forward information for the first message in the album if it was forwarded.
get_reply_message The Message that this album is replying to, or None.
respond Responds to the album (not as a reply).
reply Replies to the first photo in the album (as a reply).
forward_to Forwards the entire album.
edit Edits the first caption or the message, or the first messages’ caption if no caption is set, iff it’s outgoing.
delete Deletes the entire album.
mark_read Marks the entire album as read.
pin Pins the first photo in the album.

Raw

Raw events are not actual events. Instead, they are the raw Update object that Telegram sends. You normally shouldn’t need these.