API Reference¶
Version Info¶
Bot¶
- defadd_event
- asyncban_chat_member
- asyncclose
- asyncdelete_message
- asyncdelete_webhook
- asyncedit_message
- asyncforward_message
- asyncget_bot
- asyncget_chat
- asyncget_chat_administrators
- asyncget_chat_member
- asyncget_chat_members_count
- asyncget_file
- asyncget_user
- asyncinvite_user
- defis_closed
- asyncleave_chat
- deflisten
- asyncon_error
- defremove_event
- defrun
- asyncsend_audio
- asyncsend_contact
- asyncsend_document
- asyncsend_invoice
- asyncsend_location
- asyncsend_message
- asyncsend_photo
- asyncsend_video
- defwait_for
- class bale.Bot¶
This object represents a Bale Bot.
- Parameters:
token (str) – Bot Token
updater (Optional[
bale.Updater
]) –
Note
When you create bot and run for first-step, use
bale.Bot.delete_webhook()
method in on_ready event.- listen(event_name)¶
Register a Event
- add_event(event, function)¶
Register an Event with event name
- remove_event(event, function=None)¶
Register an Event with event name
- wait_for(event_name, *, check=None, timeout=None)¶
Wait for an event
- await close()¶
Close http Events and bot
- await on_error(event_name, error)¶
a Event for get errors when exceptions
- await get_bot()¶
Get bot information
- await delete_webhook()¶
This service is used to remove the webhook set for the bot.
- await 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
]) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
- Returns:
The Message
- Return type:
- Raises:
- await 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:
- await send_document(chat_id, document, *, caption=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 (
bytes
|str
|bale.Document
) – File to send. Pass a file_id as String to send a file that exists on the Bale servers (recommended), pass an HTTP URL as a String for Bale to get a file from the Internet, or upload a new one.caption (Optional[
str
]) – Document caption.reply_to_message_id (Optional[
str
|int
]) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
- Returns:
The Message.
- Return type:
- Raises:
- await send_photo(chat_id, photo, *, caption=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 (
bytes
|str
|bale.Photo
) – Photo to send. Pass a file_id as String to send a file that exists on the Bale servers (recommended), pass an HTTP URL as a String for Bale to get a file from the Internet, or upload a new one.caption (Optional[
str
]) – Photo caption.reply_to_message_id (Optional[
str
|int
]) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
- Returns:
The Message.
- Return type:
- Raises:
- await send_audio(chat_id, audio, *, caption=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 (
bytes
|str
|bale.Audio
) – Audio file to send. Pass a file_id as String to send a file that exists on the Bale servers (recommended), pass an HTTP URL as a String for Bale to get a file from the Internet, or upload a new one.caption (Optional[
str
]) – Audio caption.reply_to_message_id (Optional[
str
|int
]) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
- Returns:
The Message.
- Return type:
- Raises:
- await send_video(chat_id, video, *, caption=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 (
bytes
|str
|bale.Photo
) – Video to send. Pass a file_id as String to send a file that exists on the Bale servers (recommended), pass an HTTP URL as a String for Bale to get a file from the Internet, or upload a new one.caption (Optional[
str
]) – Video caption.reply_to_message_id (Optional[
str
|int
]) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
- Returns:
The Message.
- Return type:
- Raises:
- await 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:
- await 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:
- await send_invoice(chat_id, title, description, provider_token, prices, *, 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.
- 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.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:
- await 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:
- await 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:
- await 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.).
- await get_user(user_id)¶
This Method almost like
bale.Bot.get_chat
, but this a filter that only get user.
- await 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:
- await 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:
- await get_chat_members_count(chat_id)¶
Use this method to get the number of members in a chat.
- await 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:
- await 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.
- await invite_user(chat_id, user_id)¶
Invite user to the chat
- Parameters:
- Raises:
- await leave_chat(chat_id)¶
Use this method for your bot to leave a group, channel.
- run(sleep_after_every_get_updates=None)¶
Run bot and https
Models¶
CallbackQuery¶
- class bale.CallbackQuery¶
This object represents an incoming callback query from a callback button in an inline keyboard.
- message¶
Message with the callback button that originated the query. Note that message content and message date will not be available if the message is too old.
- Type:
- inline_message_id¶
Identifier of the message sent via the bot in inline mode, that originated the query.
- Type:
- data¶
Data associated with the callback button. Be aware that the message, which originated the query, can contain no callback buttons with this data.
- Type:
Chat¶
- asyncadd_user
- asyncban_chat_member
- asyncget_chat_administrators
- asyncget_chat_member
- asyncget_chat_members_count
- asyncleave
- asyncsend
- asyncsend_audio
- asyncsend_contact
- asyncsend_document
- asyncsend_invoice
- asyncsend_location
- asyncsend_photo
- asyncsend_video
- class bale.Chat¶
This object indicates a chat.
- type¶
Type of chat.
- Type:
- pinned_message¶
Pinned messages in chat. Defaults to None.
- Type:
Optional[
bale.Message
]
- invite_link¶
Primary invite link, for groups and channel. Returned only in bale.Bot.get_chat().
- Type:
Optional[
str
]
- all_members_are_administrators¶
Does everyone have admin access?. Defaults to True. (for Group)
- Type:
- await send(text, components=None)¶
For the documentation of the arguments, please see
bale.Bot.send_message()
.
- await send_document(document, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_document()
.
- await send_photo(photo, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_photo()
.
- await send_video(video, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_video()
.
- await send_audio(audio, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_audio()
.
- await send_location(location)¶
For the documentation of the arguments, please see
bale.Bot.send_location()
.
- await send_contact(contact)¶
For the documentation of the arguments, please see
bale.Bot.send_contact()
.
- await send_invoice(title, description, provider_token, prices, *, photo_url=None, need_name=False, need_phone_number=False, need_email=False, need_shipping_address=False, is_flexible=True)¶
For the documentation of the arguments, please see
bale.Bot.send_invoice()
- await leave()¶
For the documentation of the method, please see
bale.Bot.leave_chat()
.
- await add_user(user)¶
For the documentation of the arguments, please see
bale.Bot.invite_user()
.
- await get_chat_member(user)¶
For the documentation of the arguments, please see
bale.Bot.get_chat_member()
.
- await ban_chat_member(user)¶
For the documentation of the arguments, please see
bale.Bot.ban_chat_member()
.
- await get_chat_members_count()¶
For the documentation of the arguments, please see
bale.Bot.get_chat_members_count()
.
- await get_chat_administrators()¶
For the documentation of the arguments, please see
bale.Bot.get_chat_administrators()
.
Chat Type¶
User¶
- asyncsend
- asyncsend_audio
- asyncsend_contact
- asyncsend_document
- asyncsend_invoice
- asyncsend_location
- asyncsend_photo
- asyncsend_video
- class bale.User¶
This object represents a Bale user or bot.
- await send(text, components=None)¶
For the documentation of the arguments, please see
bale.Bot.send_message()
.
- await send_document(document, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_document()
.
- await send_photo(photo, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_photo()
.
- await send_video(video, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_video()
.
- await send_audio(audio, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_audio()
.
- await send_location(location)¶
For the documentation of the arguments, please see
bale.Bot.send_location()
.
- await send_contact(contact)¶
For the documentation of the arguments, please see
bale.Bot.send_contact()
.
- await send_invoice(title, description, provider_token, prices, *, photo_url=None, need_name=False, need_phone_number=False, need_email=False, need_shipping_address=False, is_flexible=True)¶
For the documentation of the arguments, please see
bale.Bot.send_invoice()
Chat Member¶
- asyncban
- class bale.ChatMember¶
This object shows a member in chat
- status¶
The member’s status in the chat.
- Type:
- permissions¶
The member’s permissions in the chat.
- Type:
bale.Permissions
- await ban()¶
For the documentation of the arguments, please see
bale.Bot.ban_chat_member()
.
Chat Member Status¶
Message¶
- asyncdelete
- asyncedit
- asyncforward
- asyncreply
- asyncreply_audio
- asyncreply_document
- asyncreply_photo
- asyncreply_video
- class bale.Message¶
This object shows a message.
- from_user¶
Sender of the message; empty for messages sent to channels. For backward compatibility, this will contain a fake sender user in non-channel chats, if the message was sent on behalf of a chat.
- Type:
Optional[
bale.User
]
- date¶
Date the message was sent in Unix time.
- Type:
Caption for the animation, audio, document, photo, video or voice.
- Type:
Optional[
str
]
- forward_from_chat¶
For messages forwarded from channels or from anonymous administrators, information about the original sender chat.
- Type:
Optional[
bale.Chat
]
- reply_to_message¶
For replies, the original message. Note that the Message object in this field will not contain further reply_to_message fields even if it itself is a reply.
- Type:
Optional[
bale.Message
]
- contact¶
Message is a shared contact, information about the contact.
- Type:
Optional[
bale.ContactMessage
]
- location¶
Message is a shared location, information about the location.
- Type:
Optional[
bale.Location
]
- document¶
Message is a general file, information about the file.
- Type:
Optional[
bale.Document
]
- video¶
Message is a video, information about the video.
- Type:
Optional[
bale.Video
]
- audio¶
Message is an audio, information about the Audio.
- Type:
Optional[
bale.Audio
]
- new_chat_members¶
New members that were added to the group or supergroup and information about them (the bot itself may be one of these members). This list is empty if the message does not contain new chat members.
- Type:
Optional[List[
bale.User
]]
- left_chat_member¶
A member was removed from the group, information about them (this member may be the bot itself).
- Type:
Optional[
bale.User
]
- invoice¶
Message is an invoice for a payment, information about the invoice.
- Type:
Optional[
bale.Invoice
]
- property attachment¶
Represents the message attachment.
None
if the message don’t have any attachments- Type:
Optional[
bale.File
]
- property content¶
Represents the message content.
None
if the message don’t have text or caption- Type:
Optional[
str
]
- property chat_id¶
Represents the Unique identifier of Conversation the message belongs to.
- property reply_to_message_id¶
Represents the Unique identifier of Original message, if the message has been replied.
None
If the message is not replied- Type:
Optional[
str
]
- await reply(text, *, components=None)¶
For the documentation of the arguments, please see
bale.Bot.send_message()
.
- await forward(chat_id)¶
For the documentation of the arguments, please see
bale.Bot.forward_message()
.
- await reply_document(document, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_document()
.
- await reply_photo(photo, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_photo()
.
- await reply_video(video, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_video()
.
- await reply_audio(audio, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_audio()
.
- await edit(text, *, components=None)¶
For the documentation of the arguments, please see
bale.Bot.edit_message()
- await delete()¶
For the documentation of the arguments, please see
bale.Bot.delete_message()
.
Update¶
- class bale.Update¶
This object represents an incoming update.
- update_id¶
The update’s unique identifier. Update identifiers start from a certain positive number and increase sequentially. This ID becomes especially handy if you’re using Webhooks, since it allows you to ignore repeated updates or to restore the correct update sequence, should they get out of order. If there are no new updates for at least a week, then identifier of the next update will be chosen randomly instead of sequentially.
- Type:
- callback_query¶
New incoming callback query.
- Type:
Optional[
bale.CallbackQuery
]
- message¶
New incoming message of any kind - text, photo, sticker, etc.
- Type:
Optional[
bale.Message
]
- edited_message¶
New version of a message that is known to the bot and was edited.
- Type:
Optional[
bale.Message
]
Update Type¶
- class bale.UpdateType¶
This object indicates an Update Type.
- is_message_update()¶
bool: Return
True
if Update Type is Message
- is_callback_update()¶
bool: Return
True
if Update Type is Callback
- is_edited_message()¶
bool: Return
True
if Update Type is Edited Message
- is_unknown_update()¶
bool: Return
True
if Update Type is Unknown
UI¶
Note
You must be use Component Models for design ui of messages.
Components¶
- class bale.Components¶
This object shows a Component.
Represents the MenuKeyboards list.
- Type:
Use this method to add MenuKeyboard component.
- Parameters:
menu_keyboard (
bale.MenuKeyboard
) – The Component you want to addrow (
int
) – The Component row number
Use this method to remove MenuKeyboard component.
- Parameters:
menu_keyboard (
bale.MenuKeyboard
) – The Component you want to removerow (
int
) – The Component row number
- add_inline_keyboard(inline_keyboard, row=1)¶
Use this method to add InlineKeyboard component.
- Parameters:
inline_keyboard (
bale.InlineKeyboard
) – The Component you want to addrow (
int
) – The Component row number
- remove_inline_keyboard(inline_keyboard, row=1)¶
Use this method to remove InlineKeyboard component.
- Parameters:
inline_keyboard (
bale.InlineKeyboard
) – The Component you want to removerow (
int
) – The Component row number
Inline Keyboard¶
- class bale.InlineKeyboard¶
This object shows an inline keyboard (within the message).
- callback_data¶
If set, pressing the button will prompt the user to select one of their chats, open that chat and insert the bot’s username and the specified inline query in the input field. Can be empty, in which case just the bot’s username will be inserted. Defaults to None.
- Type:
- switch_inline_query¶
If set, pressing the button will prompt the user to select one of their chats, open that chat and insert the bot’s username and the specified inline query in the input field. Can be empty, in which case just the bot’s username will be inserted. Defaults to None.
- Type:
Attachment Models¶
File¶
- asyncget
- asyncsave_to_memory
- class bale.File¶
This object shows a Base File Class.
- .. note::
You can get more information in file with :param:`extra`
- property type¶
a Shortcut for use
bale.File.file_type
- Type:
- await get()¶
For the documentation of the arguments, please see
bale.Bot.get_file()
.
- await save_to_memory(out)¶
Download this file into memory. out needs to be supplied with a
io.BufferedIOBase
, the file contents will be saved to that object using theio.BufferedIOBase.write()
method.- Parameters:
out (
io.BinaryIO
) – A file-like object. Must be opened for writing in binary mode.
Audio¶
- class bale.Audio¶
This object shows a Audio.
Contact Message¶
Document¶
- class bale.Document¶
This object shows a Document.
Photo¶
Location¶
Payment Models¶
Invoice¶
Price¶
Event Reference¶
Event Types¶
- class bale.EventType¶
This object represents an Event Type.
- READY¶
-
- Type:
- BEFORE_READY¶
-
- Type:
- UPDATE¶
-
- Type:
- MESSAGE¶
-
- Type:
- EDITED_MESSAGE¶
-
- Type:
- CALLBACK¶
-
- Type:
- MEMBER_CHAT_JOIN¶
-
- Type:
- MEMBER_CHAT_LEAVE¶
-
- Type:
Note
You must be use bale.EventType
for general events
from bale import Bale, EventType
bot = bale.Bot(token="Your Token")
@bot.listen(EventType.Update)
async def when_receive_update(update):
...
Before Ready¶
- bale.on_before_ready()¶
Called Before the
bale.Updater
stars.
Ready¶
- bale.on_ready()¶
Called when a bot is ready.
Update¶
- bale.on_update(update)¶
Called when a Update Sent.
- Parameters:
update (
bale.Update
) – The update
Message¶
- bale.on_message(message)¶
Called when a Message Sent.
- Parameters:
message (
bale.Message
) – The message
Edited Message¶
- bale.on_edited_message(message)¶
Called when a Message Edited.
- Parameters:
message (
bale.Message
) – The message
Callback¶
- bale.on_callback(callback)¶
Called when a Callback Sent.
- Parameters:
callback (
bale.CallbackQuery
) – The callback
Member Chat Join¶
- bale.on_member_chat_join(message, chat, user)¶
When a user joins the chat.
- Parameters:
message (
bale.Message
) – The user joins Messagechat (
bale.Chat
) – The Chatuser (
bale.User
) – The user who entered the chat
Member Chat Leave¶
- bale.on_member_chat_leave(message, chat, user)¶
When a user leaves the chat.
- Parameters:
message (
bale.Message
) – The user leaved Messagechat (
bale.Chat
) – The Chatuser (
bale.User
) – The user who leaved the chat
Exceptions¶
The following exceptions are thrown by the library.
- exception bale.BaleError(message)¶
Base exception class for python-bale-bot
- exception bale.InvalidToken(message)¶
An exception where the server says the Token is Invalid
- exception bale.APIError(error_code, message)¶
Exception that’s raised for when status code 400 occurs and Error is Unknown. Subclass of
BaleError
- exception bale.NetworkError(message)¶
Exception that’s raised when the connection is closed for reasons that could not be handled internally.
- exception bale.TimeOut¶
- exception bale.NotFound(message=None)¶
Exception that’s raised for when status code 404 occurs. Subclass of
BaleError
- exception bale.Forbidden¶
Exception that’s raised for when status code 403 occurs. Subclass of
BaleError
- exception bale.HTTPException(error)¶
Exception that’s raised when an HTTP request operation fails.