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_contact
- asyncsend_document
- asyncsend_invoice
- asyncsend_location
- asyncsend_message
- asyncsend_photo
- asyncsend_video
- defwait_for
- class bale.Bot¶
This object represents a Bale Bot.
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
- Returns
Bot User information.
- Return type
Bale.User
- Raises
APIError – Get bot Failed.
- 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 in :param:`from_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 Telegram 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 Telegram 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_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 Telegram 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_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_photo()
.
- await send_photo(photo, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_photo()
.
- await send_video(photo, *, caption=None)¶
For the documentation of the arguments, please see
bale.Bot.send_video()
.
- 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_to_chat()
.
- 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_contact
- asyncsend_document
- asyncsend_invoice
- asyncsend_location
- asyncsend_photo
- 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_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()
ChatMember¶
- asyncban
- class bale.ChatMember¶
This object shows a member in chat
- status¶
The member’s status in the chat.
- Type
bale.ChatMemberStatus
- 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()
.
MemberRole¶
Message¶
- asyncdelete
- asyncedit
- asyncforward
- asyncreply
- asyncreply_document
- asyncreply_invoice
- 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
]
- 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
]
- 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_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 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
Components¶
- class bale.Components¶
- Parameters
keyboards (List[
bale.Keyboard
]) – keyboardsinline_keyboards (List[
bale.InlineKeyboard
]) – inline keyboards
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
Keyboard¶
Remove Components¶
- class bale.RemoveComponents¶
This object shows a remove keyboard(s).
Attachment Models¶
Audio¶
Contact Message¶
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 can use bale.EventType
for 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.