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 eventwrapper (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:
- Returns:
On success,
True
is returned.- Return type:
- 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:
- 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 infrom_chat_id
.
- Returns:
The Message
- Return type:
- 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:
- 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:
- 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:
- 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.
- async get_user(user_id)¶
This Method almost like
bale.Bot.get_chat
, but this a filter that only get user.
- async invite_user(chat_id, user_id)¶
Invite user to the chat
- Parameters:
- Raises:
NotFound – Invalid Chat or User ID.
Forbidden – You do not have permission to Add user to Chat.
APIError – Invite user Failed.
- async leave_chat(chat_id)¶
Use this method for your bot to leave a group, channel.
- 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. visitbale.InputFile
to see more info.caption (Optional[
str
]) – Audio caption.components (Optional[
bale.Components
|bale.RemoveComponents
]) – Message Componentsreply_to_message_id (Optional[
str
|int
]) – If the message is a reply, ID of the original message.
- Returns:
The Message.
- Return type:
- 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:
- 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. visitbale.InputFile
to see more info.caption (Optional[
str
]) – Document caption.components (Optional[
bale.Components
|bale.RemoveComponents
]) – Message Componentsreply_to_message_id (Optional[
str
|int
]) – If the message is a reply, ID of the original message.
- Returns:
The Message.
- Return type:
- 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:
- 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:
- 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 Componentsreply_to_message_id (Optional[
str
|int
]) – If the message is a reply, ID of the original message.
- Returns:
The Message
- Return type:
- 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. visitbale.InputFile
to see more info.caption (Optional[
str
]) – Photo caption.components (Optional[
bale.Components
|bale.RemoveComponents
]) – Message Componentsreply_to_message_id (Optional[
str
|int
]) – If the message is a reply, ID of the original message.
- Returns:
The Message.
- Return type:
- 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. visitbale.InputFile
to see more info.caption (Optional[
str
]) – Video caption.components (Optional[
bale.Components
|bale.RemoveComponents
]) – Message Componentsreply_to_message_id (Optional[
str
|int
]) – If the message is a reply, ID of the original message.
- Returns:
The Message.
- Return type:
- 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.
- 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:
- Raises:
asyncio.TimeoutError – If a timeout is provided, and it was reached.