API Reference¶

Client¶

class telegrampy.Client(token: str)¶

Represents a client connection to Telegram.

Parameters: token (str) – The API token.

add_listener(func, name: str = None)¶

Registers a function as a listener.

Parameters

func – The function to register.
name (Optional[str]) – The name of the event to register the function as.

event(func)¶

Turns a function into an event handler.

Parameters: func – The function to make an event handler.

await get_chat(chat_id: int)¶

This function is a coroutine.

Fetches a chat by ID.

Parameters: chat_id (int) – The ID of the chat to fetch.
Returns: The chat that was fetched.
Return type: telegrampy.Chat
Raises: telegrampy.HTTPException – Fetching the chat failed.

listen(name=None)¶

A decorator that registers a function as a listener.

Parameters: name (Optional[str]) – The name of the event to register the function as.

await on_error(error)¶

This function is a coroutine.

Default error handler.

remove_listener(func)¶

Removes a listener.

Parameters: func – The function that is registered as a listener.

run()¶: Runs the bot

await stop()¶

This function is a coroutine.

Stops the bot

await user()¶

This function is a coroutine.

The user of the bot.

await wait_for(event: str, check=None, timeout=None)¶

This function is a coroutine.

Waits for an event.

Parameters: event (str) – The name of the event to wait for.

Events¶

telegrampy.on_message(message: telegrampy.Message)¶: Called when a message is sent.

telegrampy.on_edit(before: telegrampy.Message, after: telegrampy.Message)¶: Called when a message is edited.

telegrampy.on_poll(poll: telegrampy.Poll)¶: Called when poll is created or updated.

telegrampy.on_error(error)¶: Called when an error occurs.

Utilities¶

telegrampy.utils.escape_markdown(text: str, *, version: int = 2)¶

Tool that escapes markdown from a given string.

Parameters

text (str) – The text to escape markdown from.
version (Optional[int]) – The Telegram markdown version to use. Only 1 and 2 are supported.

Returns

The escaped text.

Return type

str

Raises

ValueError – An unsupported version was provided.

Telegram Models¶

Message¶

class telegrampy.Message(http, data: dict)¶

Represents a message in Telegram.

x == y: Checks if two messages are equal.

x != y: Checks if two messages are not equal.

id¶

The ID of the message.

Type: int

created_at¶

The time the message was created.

Type: datetime.datetime

edited_at¶

The time the message was edited.

Type: Optional[datetime.datetime]

content¶

The content of the message.

Type: str

chat¶

The chat the message is in.

Type: telegrampy.Chat

author¶

The author of the message.

Type: telegrampy.User

await delete()¶

This function is a coroutine.

Deletes the message.

Raises: telegrampy.HTTPException – Deleting the message failed.

await edit(content: str, parse_mode: str = None)¶

This function is a coroutine.

Edits the message.

Parameters

content (str) – The content of the new message.
parse_mode (str) – The parse mode of the new message.

Raises

telegrampy.HTTException – Editing the message failed.

await forward(destination)¶

This function is a coroutine.

Forwards the message to a destination.

Parameters: destination (:class:telegrampy.Chat`) – The chat forward the message to.
Returns: The message sent.
Return type: telegrampy.Message
Raises: telegrampy.HTTPException – Forwarding the message failed.

await reply(content: str, parse_mode: str = None)¶

This function is a coroutine.

Replys to the message.

Parameters

content (str) – The content of the message to send.
parse_mode (str) – The parse mode of the message to send.

Returns

The message sent.

Return type

telegrampy.Message

Raises

telegrampy.HTTPException – Sending the message failed.

User¶

class telegrampy.User(http, data)¶

Represents a Telegram user.

x == y: Checks if two users are equal.

x != y: Checks if two users are not equal.

str(x): Returns the user’s name.

id¶

The ID of the user.

Type: int

is_bot¶

If the user is a bot.

Type: bool

username¶

The username of the user.

Type: Optional[str]

first_name¶

The first name of the user.

Type: str

last_name¶

The last name of the user.

Type: Optional[str]

full_name¶: str: The user’s full name.

name¶: str: Username if the user has one. Otherwise the full name of the user.

await send(content: str = None, file: telegrampy.file.File = None, parse_mode: str = None)¶

This function is a coroutine.

Sends a message directly to the user.

Parameters

content (str) – The content of the message to send.
file (telegrampy.File) – The file to send
parse_mode (str) – The parse mode of the message to send.

Returns

The message sent.

Return type

telegrampy.Message

Raises

errors.HTTPException – Sending the message failed.

Chat¶

class telegrampy.Chat(http, data: dict)¶

Represents a chat in Telegram.

x == y: Checks if two chats are equal.

x != y: Checks if two chats are not equal.

str(x): Returns the chat’s title.

id¶

The ID of the chat.

Type: int

title¶

The title of the chat.

Type: str

description¶

The description of the chat.

Type: Optional[str]

type¶

The type of the chat.

Type: str

fetch_message(message_id: int)¶

Fetches a message from the cache.

Parameters: message_id (int) – The ID of the message to fetch.
Returns: The message fetched.
Return type: chat.Message

await get_member(user_id: int)¶

This function is a coroutine.

Fetches a member in the chat.

Parameters: user_id (int) – The user ID of the member.
Returns: The member fetched.
Return type: telegrampy.User
Raises: telegrampy.HTTPException – Fetching the member failed.

history¶: list: The cached messages in the chat.

await send(content: str = None, file: telegrampy.file.File = None, parse_mode: str = None)¶

This function is a coroutine.

Sends a message to the chat.

Parameters

content (str) – The content of the message to send.
file (telegrampy.File) – The file to send.
parse_mode (str) – The parse mode of the message to send.

Returns

The message sent.

Return type

telegrampy.Message

Raises

errors.HTTPException – Sending the message failed.

await send_action(action: str)¶

This function is a coroutine.

Sends an action to the chat.

Parameters: action (str) – The action to send.
Raises: telegrampy.HTTPException – Sending the action failed.

await send_poll(question: str, options: list)¶

This function is a coroutine.

Sends a poll to the chat.

Parameters

question (str) – The question of the poll.
options (list) – The options in the poll.

Returns

The poll sent.

Return type

telegrampy.Poll

Raises

telegrampy.HTTPException – Sending the poll failed.

Files¶

class telegrampy.Document(file: _io.BytesIO, filename: str = None)¶

A document to send.

file¶

The document.

Type: io.BytesIO

filename¶

The filename of the document.

Type: Optional[str]

Parameters

file (io.BytesIO) – The document.
filename (str) – The filename of the document.

class telegrampy.Photo(file: _io.BytesIO, filename: str = None, caption: str = None)¶

A photo to send.

file¶

The photo.

Type: io.BytesIO

filename¶

The filename of the photo.

Type: Optional[str]

caption¶

The caption of the photo.

Type: Optional[str]

Parameters

file (io.BytesIO) – The photo.
filename (str) – The filename of the photo.
caption (str) – The caption of the photo.

Poll¶

class telegrampy.Poll(data)¶

A telegram poll.

question¶

The question of the poll.

Type: str

options¶

The options of the poll.

Type: list

total_voter_count¶

The total voter count of the poll.

Type: int

is_closed¶

If the poll is closed.

Type: bool

is_anonymous¶

If the poll is anonymous.

Type: bool

type¶

The type of the poll.

Type: str

allow_multiple_answers¶

If the poll allows multiple answers.

Type: bool

Exceptions¶

class telegrampy.TelegramException¶: Base exception for all errors.

class telegrampy.HTTPException(response, message='')¶

Raised when an HTTP request fails.

response¶

The response for the request that failed.

Type: aiohttp.ClientResponse

messsage¶

The message for the request that failed.

Type: Optional[str]

class telegrampy.InvalidToken(response, message='')¶: Raised when a token is invalid.

class telegrampy.Forbidden(response, message='')¶: Raised when something is forbidden.

class telegrampy.Conflict(response, message='')¶: Raised when another instance of the bot is running.