telethon.events package

exception telethon.events.StopPropagation

Bases: Exception

If this exception is raised in any of the handlers for a given event, it will stop the execution of all other registered event handlers. It can be seen as the StopIteration in a for loop but for events.

Example usage:
>>> from telethon import TelegramClient, events
>>> client = TelegramClient(...)
>>>
>>> @client.on(events.NewMessage)
... def delete(event):
...     event.delete()
...     # No other event handler will have a chance to handle this event
...     raise StopPropagation
...
>>> @client.on(events.NewMessage)
... def _(event):
...     # Will never be reached, because it is the second handler
...     pass

Every event (builder) subclasses telethon.events.common.EventBuilder, so all the methods in it can be used from any event builder/event instance.

class telethon.events.common.EventBuilder(chats=None, blacklist_chats=False)

Bases: abc.ABC

The common event builder, with builtin support to filter per chat.

Args:
chats (entity, optional):
May be one or more entities (username/peer/etc.). By default, only matching chats will be handled.
blacklist_chats (bool, optional):
Whether to treat the chats as a blacklist instead of as a whitelist (default). This means that every chat will be handled except those specified in chats which will be ignored if blacklist_chats=True.
build(update)

Builds an event for the given update if possible, or returns None

resolve(client)

Helper method to allow event builders to be resolved before usage

class telethon.events.common.EventCommon(chat_peer=None, msg_id=None, broadcast=False)

Bases: abc.ABC

Intermediate class with common things to all events

chat

The (User | Chat | Channel, optional) on which the event occurred. This property may make an API call the first time to get the most up to date version of the chat (mostly when the event doesn’t belong to a channel), so keep that in mind.

client
input_chat

The (InputPeer) (group, megagroup or channel) on which the event occurred. This doesn’t have the title or anything, but is useful if you don’t need those to avoid further requests.

Note that this might be None if the library can’t find it.

stringify()
to_dict()
class telethon.events.common.Raw(chats=None, blacklist_chats=False)

Bases: telethon.events.common.EventBuilder

Represents a raw event. The event is the update itself.

build(update)
resolve(client)
telethon.events.common.name_inner_event(cls)

Decorator to rename cls.Event ‘Event’ as ‘cls.Event’

Below all the event types are listed:

class telethon.events.newmessage.NewMessage(incoming=None, outgoing=None, chats=None, blacklist_chats=False, pattern=None)

Bases: telethon.events.common.EventBuilder

Represents a new message event builder.

Args:
incoming (bool, optional):
If set to True, only incoming messages will be handled. Mutually exclusive with outgoing (can only set one of either).
outgoing (bool, optional):
If set to True, only outgoing messages will be handled. Mutually exclusive with incoming (can only set one of either).
pattern (str, callable, Pattern, optional):
If set, only messages matching this pattern will be handled. You can specify a regex-like string which will be matched against the message, a callable function that returns True if a message is acceptable, or a compiled regex pattern.
class Event(message)

Bases: telethon.events.common.EventCommon

Represents the event of a new message.

Members:
message (Message):
This is the original Message object.
is_private (bool):
True if the message was sent as a private message.
is_group (bool):
True if the message was sent on a group or megagroup.
is_channel (bool):
True if the message was sent on a megagroup or channel.
is_reply (str):
Whether the message is a reply to some other or not.
audio

If the message media is a document with an Audio attribute, this returns the Document object.

delete(*args, **kwargs)

Deletes the message. You’re responsible for checking whether you have the permission to do so, or to except the error otherwise. This is a shorthand for client.delete_messages(event.chat, event.message, ...).

document

If the message media is a document, this returns the Document object.

edit(*args, **kwargs)

Edits the message iff it’s outgoing. This is a shorthand for client.edit_message(event.chat, event.message, ...).

Returns None if the message was incoming, or the edited message otherwise.

forward

The unmodified MessageFwdHeader, if present..

forward_to(*args, **kwargs)

Forwards the message. This is a shorthand for client.forward_messages(entity, event.message, event.chat).

gif

If the message media is a document with an Animated attribute, this returns the Document object.

input_sender

This (InputPeer) is the input version of the user who sent the message. Similarly to input_chat, this doesn’t have things like username or similar, but still useful in some cases.

Note that this might not be available if the library can’t find the input chat, or if the message a broadcast on a channel.

media

The unmodified MessageMedia, if present.

out

Whether the message is outgoing (i.e. you sent it from another session) or incoming (i.e. someone else sent it).

photo

If the message media is a photo, this returns the Photo object.

raw_text

The raw message text, ignoring any formatting.

reply(*args, **kwargs)

Replies to the message (as a reply). This is a shorthand for client.send_message(event.chat, ..., reply_to=event.message.id).

reply_message

This optional Message will make an API call the first time to get the full Message object that one was replying to, so use with care as there is no caching besides local caching yet.

respond(*args, **kwargs)

Responds to the message (not as a reply). This is a shorthand for client.send_message(event.chat, ...).

sender

This (User) may make an API call the first time to get the most up to date version of the sender (mostly when the event doesn’t belong to a channel), so keep that in mind.

input_sender needs to be available (often the case).

sticker

If the message media is a document with a Sticker attribute, this returns the Document object.

text

The message text, markdown-formatted.

video

If the message media is a document with a Video attribute, this returns the Document object.

video_note

If the message media is a document with a Video attribute, this returns the Document object.

voice

If the message media is a document with a Voice attribute, this returns the Document object.

build(update)
class telethon.events.chataction.ChatAction(chats=None, blacklist_chats=False)

Bases: telethon.events.common.EventBuilder

Represents an action in a chat (such as user joined, left, or new pin).

class Event(where, new_pin=None, new_photo=None, added_by=None, kicked_by=None, created=None, users=None, new_title=None, unpin=None)

Bases: telethon.events.common.EventCommon

Represents the event of a new chat action.

Members:
action_message (MessageAction):
The message invoked by this Chat Action.
new_pin (bool):
True if there is a new pin.
new_photo (bool):
True if there’s a new chat photo (or it was removed).
photo (Photo, optional):
The new photo (or None if it was removed).
user_added (bool):
True if the user was added by some other.
user_joined (bool):
True if the user joined on their own.
user_left (bool):
True if the user left on their own.
user_kicked (bool):
True if the user was kicked by some other.
created (bool, optional):
True if this chat was just created.
new_title (bool, optional):
The new title string for the chat, if applicable.
unpin (bool):
True if the existing pin gets unpinned.
added_by

The user who added users, if applicable (None otherwise).

delete(*args, **kwargs)

Deletes the chat action message. You’re responsible for checking whether you have the permission to do so, or to except the error otherwise. This is a shorthand for client.delete_messages(event.chat, event.message, ...).

Does nothing if no message action triggered this event.

input_user

Input version of the self.user property.

input_users

Input version of the self.users property.

kicked_by

The user who kicked users, if applicable (None otherwise).

pinned_message

If new_pin is True, this returns the (Message) object that was pinned.

reply(*args, **kwargs)

Replies to the chat action message (as a reply). Shorthand for client.send_message(event.chat, ..., reply_to=event.message.id).

Has the same effect as .respond() if there is no message.

respond(*args, **kwargs)

Responds to the chat action message (not as a reply). Shorthand for client.send_message(event.chat, ...).

user

The single user that takes part in this action (e.g. joined).

Might be None if the information can’t be retrieved or there is no user taking part.

users

A list of users that take part in this action (e.g. joined).

Might be empty if the information can’t be retrieved or there are no users taking part.

build(update)
class telethon.events.userupdate.UserUpdate(chats=None, blacklist_chats=False)

Bases: telethon.events.common.EventBuilder

Represents an user update (gone online, offline, joined Telegram).

class Event(user_id, status=None, typing=None)

Bases: telethon.events.common.EventCommon

Represents the event of an user status update (last seen, joined).

Members:
online (bool, optional):
True if the user is currently online, False otherwise. Might be None if this information is not present.
last_seen (datetime, optional):
Exact date when the user was last seen if known.
until (datetime, optional):
Until when will the user remain online.
within_months (bool):
True if the user was seen within 30 days.
within_weeks (bool):
True if the user was seen within 7 days.
recently (bool):
True if the user was seen within a day.
action (SendMessageAction, optional):
The “typing” action if any the user is performing if any.
cancel (bool):
True if the action was cancelling other actions.
typing (bool):
True if the action is typing a message.
recording (bool):
True if the action is recording something.
uploading (bool):
True if the action is uploading something.
playing (bool):
True if the action is playing a game.
audio (bool):
True if what’s being recorded/uploaded is an audio.
round (bool):
True if what’s being recorded/uploaded is a round video.
video (bool):
True if what’s being recorded/uploaded is an video.
document (bool):
True if what’s being uploaded is document.
geo (bool):
True if what’s being uploaded is a geo.
photo (bool):
True if what’s being uploaded is a photo.
contact (bool):
True if what’s being uploaded (selected) is a contact.
user

Alias around the chat (conversation).

build(update)
class telethon.events.messageedited.MessageEdited(incoming=None, outgoing=None, chats=None, blacklist_chats=False, pattern=None)

Bases: telethon.events.newmessage.NewMessage

Event fired when a message has been edited.

class Event(message)

Bases: telethon.events.newmessage.Event

build(update)
class telethon.events.messagedeleted.MessageDeleted(chats=None, blacklist_chats=False)

Bases: telethon.events.common.EventBuilder

Event fired when one or more messages are deleted.

class Event(deleted_ids, peer)

Bases: telethon.events.common.EventCommon

build(update)
class telethon.events.messageread.MessageRead(inbox=False, chats=None, blacklist_chats=None)

Bases: telethon.events.common.EventBuilder

Event fired when one or more messages have been read.

Args:
inbox (bool, optional):
If this argument is True, then when you read someone else’s messages the event will be fired. By default (False) only when messages you sent are read by someone else will fire it.
class Event(peer=None, max_id=None, out=False, contents=False, message_ids=None)

Bases: telethon.events.common.EventCommon

Represents the event of one or more messages being read.

Members:
max_id (int):
Up to which message ID has been read. Every message with an ID equal or lower to it have been read.
outbox (bool):
True if someone else has read your messages.
contents (bool):
True if what was read were the contents of a message. This will be the case when e.g. you play a voice note. It may only be set on inbox events.
inbox

True if you have read someone else’s messages.

is_read(message)

Returns True if the given message (or its ID) has been read.

If a list-like argument is provided, this method will return a list of booleans indicating which messages have been read.

message_ids

The IDs of the messages which contents’ were read.

Use is_read() if you need to check whether a message was read instead checking if it’s in here.

messages

The list of Message which contents’ were read.

Use is_read() if you need to check whether a message was read instead checking if it’s in here.

build(update)