Bot¶

class bale.Bot(token, **kwargs)¶

Bases: object

This object represents a Bale Bot.

Parameters:: token (str) – Bot Token

Attention

When you create bot and run for first-step, use bale.Bot.delete_webhook() method in on_before_ready event.

add_event(event_name, wrapper)¶

Set wrapper or listener for an event.

Parameters:

event_name (str) – Name of the event
wrapper (Callable[]) – Function to add as wrapper for event

async ban_chat_member(chat_id, user_id)¶

Use this method to ban a user from a group, supergroup or a channel. In the case of supergroups and channels, the user will not be able to return to the group on their own using invite links, etc., unless unbanned first.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
user_id (int | str) – Unique identifier of the target user.

Returns:

On success, True is returned.

Return type:

bool

Raises:

NotFound – Invalid Chat or User ID.
Forbidden – You do not have permission to ban Chat Member.
APIError – ban chat member Failed.

async close()¶: Close http Events and bot

async delete_message(chat_id, message_id)¶

You can use this service to delete a message that you have already sent through the arm.

Warning

In Channel or Group:: If it is a group or channel Manager, it can delete a message from (group or channel).
In private message (PV):: If the message was sent by a bot, it can be deleted with this method

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
message_id (bale.Message) – Unique identifier for the message to delete.

Raises:

NotFound – Invalid Message or Chat ID.
Forbidden – You do not have permission to Delete Message.
APIError – Delete Message Failed.

async delete_webhook()¶

This service is used to remove the webhook set for the bot.

Returns:

On success, True is returned.

Return type:

bool

Raises:

Forbidden – You do not have permission to delete Webhook.
APIError – Delete webhook Failed.

async edit_message(chat_id, message_id, text, *, components=None)¶

You can use this service to edit text messages that you have already sent through the arm.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
message_id (str | int) – Unique identifier for the message to edit.
text (str) – New text of the message, 1- 4096 characters after entities parsing.
components (Optional[bale.Components | bale.RemoveComponents]) – An object for an inline keyboard.

Raises:

NotFound – Invalid Message or Chat ID.
Forbidden – You do not have permission to Edit Message.
APIError – Edit Message Failed.

event(coro)¶: Set wrapper or listener for selected event (the name of function).

Hint

The name of the function for which you write the decorator is considered the name of the event.

async forward_message(chat_id, from_chat_id, message_id)¶

This service is used to send text messages.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
from_chat_id (str | int) – the chat where the original message was sent (or channel username in the format @channelusername).
message_id (int | str) – Message in the chat specified in from_chat_id.

Returns:

The Message

Return type:

bale.Message

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to send Message to this chat.
APIError – Forward Message Failed.

async get_bot()¶

Get bot information

Returns:: Bot User information.
Return type:: bale.User
Raises:: APIError – Get bot Failed.

async get_chat(chat_id)¶

Use this method to get up-to-date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.).

Parameters:

chat_id (int | str) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).

Returns:

The chat or None if not found.

Return type:

Optional[bale.Chat]

Raises:

Forbidden – You do not have permission to get Chat.
APIError – Get chat Failed.

async get_chat_administrators(chat_id)¶

Use this method to get a list of administrators in a chat.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).

Returns:

list of chat member.

Return type:

List[bale.ChatMember]

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to get Administrators of the Chat.
APIError – get Administrators of the Chat from chat Failed.

async get_chat_member(chat_id, user_id)¶

Use this method to get information about a member of a chat. The method is only guaranteed to work for other users if the bot is an administrator in the chat.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
user_id (Optional[int | str]) – Unique identifier of the target user.

Returns:

The chat member of None if not found.

Return type:

Optional[bale.ChatMember]

Raises:

NotFound – Invalid Chat or User ID.
Forbidden – You do not have permission to get Chat Member.
APIError – Get chat member Failed.

async get_chat_members_count(chat_id)¶

Use this method to get the number of members in a chat.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to get Members count of the Chat.
APIError – get Members count of the Chat Failed.

Returns:

The members count of the chat

Return type:

int

async get_file(file_id)¶

Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can download files of up to 20 MB in size.

Parameters:

file_id (str) – Either the file identifier to get file information about.

Returns:

The content of the file

Return type:

bytes

Raises:

NotFound – Invalid file ID.
Forbidden – You do not have permission to download File.
APIError – download File Failed.

async get_user(user_id)¶

This Method almost like bale.Bot.get_chat , but this a filter that only get user.

Parameters:

user_id (int) – user id

Returns:

The user or None if not found.

Return type:

Optional[bale.User]

Raises:

Forbidden – You do not have permission to get User.
APIError – Get user Failed.

async invite_user(chat_id, user_id)¶

Invite user to the chat

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
user_id (str | int) – Unique identifier for the target user.

Raises:

NotFound – Invalid Chat or User ID.
Forbidden – You do not have permission to Add user to Chat.
APIError – Invite user Failed.

is_closed()¶: bool: Connection Status

async leave_chat(chat_id)¶

Use this method for your bot to leave a group, channel.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).

Raises:

Forbidden – You do not have permission to Leave from chat.
APIError – Leave from chat Failed.

listen(event_name)¶

Set wrapper or listener for selected event (custom function name).

Parameters:: event_name (str) – Name of the event to set.

async on_error(event_name, error)¶: a Event for get errors when exceptions

run()¶: Starting the bot, updater and HTTPClient.

async send_audio(chat_id, audio, *, caption=None, components=None, reply_to_message_id=None)¶

This service is used to send Audio.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
audio (bale.InputFile) – File to send. visit bale.InputFile to see more info.
caption (Optional[str]) – Audio caption.
components (Optional[bale.Components | bale.RemoveComponents]) – Message Components
reply_to_message_id (Optional[str | int]) – If the message is a reply, ID of the original message.

Returns:

The Message.

Return type:

bale.Message

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to Send Audio to chat.
APIError – Send Audio Failed.

async send_contact(chat_id, contact)¶

This service is used to send contact.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
contact (bale.ContactMessage) – The Contact.

Returns:

The Message.

Return type:

bale.Message

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to send Contact Message to this chat.
APIError – Send Contact Message Failed.

async send_document(chat_id, document, *, caption=None, components=None, reply_to_message_id=None)¶

This service is used to send document.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
document (bale.InputFile) – File to send. visit bale.InputFile to see more info.
caption (Optional[str]) – Document caption.
components (Optional[bale.Components | bale.RemoveComponents]) – Message Components
reply_to_message_id (Optional[str | int]) – If the message is a reply, ID of the original message.

Returns:

The Message.

Return type:

bale.Message

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to send Document to this chat.
APIError – Send Document Failed.

async send_invoice(chat_id, title, description, provider_token, prices, *, payload=None, photo_url=None, need_name=False, need_phone_number=False, need_email=False, need_shipping_address=False, is_flexible=True)¶

You can use this service to send money request messages.

Important

When paying the amount, a fee will be charged from the sender.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
title (str) – Product name. 1- 32 characters.
description (str) – Product description. 1- 255 characters.
provider_token (str) – You can use 3 methods to receive money: 1.Card number 2. Port number and acceptor number 3. Wallet number “Bale”
prices (List[bale.Price]) – A list of prices.
payload (Optional[str]) – Bot-defined invoice payload. This will not be displayed to the user, use for your internal processes.
photo_url (Optional[str]) – URL of the product photo for the invoice. Can be a photo of the goods or a marketing image for a service. People like it better when they see what they are paying for.
need_name (Optional[bool]) – Pass True, if you require the user’s full name to complete the order.
need_phone_number (Optional[bool]) – Pass True, if you require the user’s phone number to complete the order.
need_email (Optional[bool]) – Pass True, if you require the user’s email to complete the order.
need_shipping_address (Optional[bool]) – Pass True, if you require the user’s shipping address to complete the order.
is_flexible (Optional[bool]) – Pass True, if the final price depends on the shipping method.

Return type:

bale.Message

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to send Invoice to this chat.
APIError – Send Invoice Failed.

async send_location(chat_id, location)¶

Use this method to send point on the map.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
location (bale.Location) – The Location.

Returns:

The Message.

Return type:

bale.Message

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to send Location to this chat.
APIError – Send Location Failed.

async send_message(chat_id, text, *, components=None, reply_to_message_id=None)¶

This service is used to send text messages.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
text (str) – Text of the message to be sent. Max 4096 characters after entities parsing.
components (Optional[bale.Components | bale.RemoveComponents]) – Message Components
reply_to_message_id (Optional[str | int]) – If the message is a reply, ID of the original message.

Returns:

The Message

Return type:

bale.Message

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to send Message to this chat.
APIError – Send Message Failed.

async send_photo(chat_id, photo, *, caption=None, components=None, reply_to_message_id=None)¶

This service is used to send photo.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
photo (bale.InputFile) – File to send. visit bale.InputFile to see more info.
caption (Optional[str]) – Photo caption.
components (Optional[bale.Components | bale.RemoveComponents]) – Message Components
reply_to_message_id (Optional[str | int]) – If the message is a reply, ID of the original message.

Returns:

The Message.

Return type:

bale.Message

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to Send Photo to chat.
APIError – Send photo Failed.

async send_video(chat_id, video, *, caption=None, components=None, reply_to_message_id=None)¶

This service is used to send Video.

Parameters:

chat_id (str | int) – Unique identifier for the target chat or username of the target channel (in the format @channelusername).
video (bale.InputFile) – File to send. visit bale.InputFile to see more info.
caption (Optional[str]) – Video caption.
components (Optional[bale.Components | bale.RemoveComponents]) – Message Components
reply_to_message_id (Optional[str | int]) – If the message is a reply, ID of the original message.

Returns:

The Message.

Return type:

bale.Message

Raises:

NotFound – Invalid Chat ID.
Forbidden – You do not have permission to Send Video to chat.
APIError – Send Video Failed.

async set_webhook(url)¶

Use this method to specify an url and receive incoming updates via an outgoing webhook. Whenever there is an update for the bot, Bale will send an HTTPS POST request to the specified url, containing An Update. In case of an unsuccessful request, Bale will give up after a reasonable amount of attempts.

Parameters:: url (str) – HTTPS url to send updates to. Use an empty string to remove webhook integration.
Returns:: On success, True is returned.
Return type:: bool

property user¶

Represents the connected client. None if not logged in

Type:: Optional[bale.User]

wait_for(event_name, *, check=None, timeout=None)¶

Waits for an event to be dispatched.

This could be used to wait for a user to reply to a message, or send a photo, or to edit a message in a self-contained way. The timeout parameter is passed onto asyncio.wait_for(). By default, it does not timeout. Note that this does propagate the asyncio.TimeoutError for you in case of timeout and is provided for ease of use. In case the event returns multiple arguments, a tuple containing those arguments is returned instead. This function returns the first event that meets the requirements.

Parameters:

event_name (str) – Name of the event
check (Optional[Callable[…, bool]]) – A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for.
timeout (Optional[float]) – The number of seconds to wait before timing out and raising asyncio.TimeoutError.

Raises:

asyncio.TimeoutError – If a timeout is provided, and it was reached.