Bot¶
- class bale.Bot(token, updater=None, **kwargs)¶
Bases:
object
This object represents a Bale Bot.
- Parameters:
token (str) – Bot’s unique authentication token. obtained via @BotFather.
All wrapped methods of Bale web services at a glance:
sending animation
sending audio
sending contact
sending document
sending an invoice
sending location
sending media grouped together
sending normal message
sending photo
sending sticker
sending video
copying the contents of an arbitrary message
deleting message
editing message
editing captions
forwarding message
getting information about a chat
getting information about bot
getting information about a message
getting information about a user
removing webhook integration
setting a webhook to receive updates
getting pending updates
getting current webhook status
banning a member from chat
getting the list of admins in a chat
leaving from a chat
getting information about a chat member
getting the number of members in a chat
inviting a user to chat
unbanning a user from chat
Examples
- add_event(event_name, wrapper)¶
Set wrapper or listener for an event.
Hint
... async def ready_event_wrapper() -> None: print(bot.user) bot.add_event('on_ready', ready_event_wrapper)
- Parameters:
event_name (
str
) – Name of the eventwrapper (Callable) – Function to add as wrapper for event
- add_handler(handler, wrapper)¶
Set wrapper or listener for a handler.
Hint
from bale.handlers import MessageHandler ... async def message_handler_wrapper(message: bale.Message) -> None: await message.reply("Cool!") bot.add_handler(MessageHandler(), message_handler_wrapper)
- Parameters:
handler (
bale.BaseHandler
) – abale.BaseHandler
instancewrapper (Callable) – Function to add as wrapper for handler.
- 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.
await bot.ban_chat_member(1234, 1234)
- 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.
- property cached_chats¶
Represents the chats that the bot has ever encountered.
- Type:
weakref.WeakValueDictionary`[:obj:`str
,bale.Chat
]
- property cached_users¶
Represents the users that the bot has ever encountered.
- Type:
weakref.WeakValueDictionary`[:obj:`str
,bale.User
]
- async close()¶
Close http Events and bot
- async copy_message(chat_id, from_chat_id, message_id, *, reply_to_message_id=MissingValue, delete_after=None)¶
You can use this service to copy a message and send it in another chat.
await bot.copy_message(1234, 1234, 1234)
- 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
) – Unique identifier for the chat where the original message was sent (or channel username in the format @channelusername).message_id (
str
|int
) – Message identifier in the chat specified in from_chat_id.reply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.
- Raises:
NotFound – Invalid Message or Chat ID.
Forbidden – You do not have permission to Copy or Send Message.
APIError – Copy Message Failed.
- async delete_message(chat_id, message_id, *, delay=None)¶
You can use this service to delete a message that you have already sent through the arm.
await bot.delete_message(1234, 1234)
Warning
In channels or groups, only when the admin can delete other people’s messages. Otherwise, It’s no limit to delete his own message.
- 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 delete.delay (
int
|float
, optional) – If used, the message will be deleted after that number of seconds delay.
- 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.
await bot.delete_webhook()
- 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=MissingValue)¶
You can use this service to edit text messages that you have already sent through the arm.
await bot.edit_message(1234, 1234, "the message edited!", components=None)
- 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 (
bale.InlineKeyboardMarkup
, optional) – 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.
You can use this service to edit captions of messages that you have already sent through the arm.
await bot.edit_message_caption(1234, 1234, "the message edited!", components=None)
- 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.caption (
str
) – New caption of the message, 1-1024 characters after entities parsing.components (
bale.InlineKeyboardMarkup
, optional) – 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.
- async forward_message(chat_id, from_chat_id, message_id)¶
This service is used to send text messages.
await bot.forward_message(1234, 1234, 1234)
- 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 (
str
|int
) – 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_chat(chat_id, *, use_cache=True)¶
Use this method to get cashed or 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 bot.get_chat(1234) ... await bot.get_chat("1234")
- Parameters:
- Returns:
The chat or
None
if not found.- Return type:
bale.Chat
| None- 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.
await bot.get_chat_administrators(1234)
- 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.
await bot.get_chat_member(1234, 1234)
Warning
Just only when the admin can ban member(s).
- Parameters:
- Returns:
The chat member of
None
if not found.- Return type:
bale.ChatMember
, optional- 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.
await bot.get_chat_members_count(1234)
- 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.await bot.get_file("FILE_ID")
- async get_me()¶
Get bot information
- Returns:
Bot User information.
- Return type:
- Raises:
APIError – Get bot Failed.
- async get_message(chat_id, message_id)¶
Use this method to get cashed information about the message.
await bot.get_message(1234)
- Parameters:
- Returns:
The message or
None
if not found.- Return type:
bale.Message
| None
- async get_updates(offset=MissingValue, limit=MissingValue)¶
Use this method to get pending updates.
updates = await bot.get_updates()
- Parameters:
- Raises:
Forbidden – You do not have permission to get updates.
APIError – Get updates Failed.
- async get_user(user_id, *, use_cache=True)¶
This Method almost like
bale.Bot.get_chat()
, but this a filter that only get user.await bot.get_user(1234) ... await bot.get_user("1234")
- Parameters:
- Returns:
The user or
None
if not found.- Return type:
bale.User
| None- Raises:
Forbidden – You do not have permission to get User.
APIError – Get user Failed.
- async get_webhook_info()¶
Use this method to get current webhook status.
await bot.get_webhook_info()
- Returns:
The webhook info.
- Return type:
- Raises:
APIError – Get Webhook Info Failed.
- handle(handler)¶
A decorator to set callback for a handler.
See also
What is handler?
Important
The parameters of your wrapper function will vary depending on your handler.
Hint
from bale.handlers import MessageHandler ... @bot.handle(MessageHandler(...)) async def message_handler_wrapper(message: bale.Message) -> None: await message.reply("Cool!")
- Parameters:
handler (
bale.BaseHandler
) – abale.BaseHandler
instance
- async invite_user(chat_id, user_id)¶
Invite user to the chat
await bot.get_chat(1234, 1234)
- 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.
await bot.leave_chat(1234)
- listen(event_name)¶
A decorator to set wrapper for an event.
See also
What is event?
Hint
@bot.listen("on_ready") async def ready_event_wrapper(): print(bot.user)
- Parameters:
event_name (
str
) – Name of the event to set.
- async promote_chat_member(chat_id, user_id, can_be_edited=MissingValue, can_change_info=MissingValue, can_post_messages=MissingValue, can_edit_messages=MissingValue, can_delete_messages=MissingValue, can_invite_users=MissingValue, can_restrict_members=MissingValue, can_pin_messages=MissingValue, can_promote_members=MissingValue, can_send_messages=MissingValue, can_send_media_messages=MissingValue, can_reply_to_story=MissingValue, can_send_link_message=MissingValue, can_send_forwarded_message=MissingValue, can_see_members=MissingValue, can_add_story=MissingValue)¶
an administrator in the chat for this to work and must have the appropriate admin rights. Pass
False
for all boolean parameters to demote a user.await bot.promote_chat_member(1234, 1234, can_change_info = True)
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).can_be_edited (
bool
, optional) – PassTrue
, if the bot is allowed to edit administrator privileges of that user.can_change_info (
bool
, optional) – PassTrue
, if the user can change the chat title, photo and other settings.can_post_messages (
bool
, optional) – PassTrue
, if the administrator can post messages in the channel, or access channel statistics; channels only.can_edit_messages (
bool
, optional) – PassTrue
, if the administrator can edit messages of other users and can pin messages; channels only.can_delete_messages (
bool
, optional) – PassTrue
, if the administrator can delete messages of other users.can_invite_users (
bool
, optional) – PassTrue
, if the user can invite new users to the chat.can_restrict_members (
bool
, optional) – PassTrue
, if the administrator can restrict, ban or unban chat members.can_pin_messages (
bool
, optional) – PassTrue
, if the user is allowed to pin messages, groups, channels only.can_promote_members (
bool
, optional) – PassTrue
, if the administrator can add new administrators with a subset of his own privileges or demote administrators that he has promoted, directly or indirectly (promoted by administrators that were appointed by the user).can_send_messages (
bool
, optional) – PassTrue
, if the user is allowed to send messages.can_send_media_messages (
bool
, optional) – PassTrue
, if the user is allowed to send a media message.can_reply_to_story (
bool
, optional) – PassTrue
, if the user is allowed to reply to a story.can_send_link_message (
bool
, optional) – PassTrue
, if the user is allowed to send a link message.can_send_forwarded_message (
bool
, optional) – PassTrue
, if the user is allowed to forward a message to chat.can_see_members (
bool
, optional) – PassTrue
, if the user is allowed to see the list of chat members.can_add_story (
bool
, optional) – PassTrue
, if the user is allowed to post a story from chat.
- Returns:
On success,
True
is returned.- Return type:
- Raises:
NotFound – Invalid Chat or User ID.
Forbidden – You do not have permission to promote Chat Member.
APIError – Promote chat member Failed.
- run(log_handler=None, log_level=20, log_format=None, startup_functions=None, stop_functions=None)¶
This method is used to run the bot, updater, and update fetcher process.
Hint
... bot = Bot(token="YOUR_TOKEN") bot.run() # to run the bot
- Parameters:
log_handler (
logging.Handler
, optional) – A logging handler to use for logging. If provided, the class will use this handler for logging operations. Defaults tologging.StreamHandler
.log_level (
int
, optional) – The logging level to be used for logging. If provided, the class will use this level for logging operations. Defaults tologging.INFO
.log_format (
str
, optional) – The format string to use for formatting log messages. If provided, the class will use this for logging messages. Defaults to%Y-%m-%d %H:%M:%S
.startup_functions (a
list
of functions (including async funcs), optional) – A tuple of functions to be executed (for async functions usingasyncio.run_until_complete()
method for execute) when the class is starting to run. Defaults toNone
.stop_functions (a
list
of functions (including async funcs), optional) – A tuple of functions to be executed (for async functions usingasyncio.run_until_complete()
method for execute) when the class is Terminating work. Defaults toNone
.
- async send_animation(chat_id, animation, *, duration=MissingValue, width=MissingValue, height=MissingValue, caption=MissingValue, components=MissingValue, reply_to_message_id=MissingValue, delete_after=None, file_name=None)¶
This service is used to send Animation.
await bot.send_animation(1234, bale.InputFile("FILE_ID"), caption = "this is a caption", ...)
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).animation (
bale.Animation
|bale.InputFile
|str
|bytes
) – File to send.duration (
int
, optional) – Duration of sent animation in seconds.width (
int
, optional) – Animation width.height (
int
, optional) – Animation height.caption (
str
, optional) – Animation caption.components (
bale.InlineKeyboardMarkup
|bale.MenuKeyboardMarkup
, optional) – Message Componentsreply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.file_name (
str
, optional) – Custom file name for the file, when uploading a that.
- Returns:
The Message.
- Return type:
- Raises:
NotFound – Invalid Chat ID.
Forbidden – You do not have permission to Send Animation to chat.
APIError – Send Animation Failed.
- async send_audio(chat_id, audio, *, caption=MissingValue, components=MissingValue, reply_to_message_id=MissingValue, delete_after=None, file_name=None)¶
This service is used to send Audio.
await bot.send_audio(1234, bale.InputFile("FILE_ID"), caption = "this is a caption", ...)
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).audio (
bale.Audio
|bale.InputFile
|str
|bytes
) – File to send.caption (
str
, optional) – Audio caption.components (
bale.InlineKeyboardMarkup
|bale.MenuKeyboardMarkup
, optional) – Message Componentsreply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.file_name (
str
, optional) – Custom file name for the file, when uploading a that.
- 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, components=MissingValue, reply_to_message_id=MissingValue, delete_after=None)¶
This service is used to send contact.
await bot.send_cantact(1234, bale.Contact('09****', 'first name', 'last name'))
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).contact (
bale.Contact
) – The Contact.components (
bale.InlineKeyboardMarkup
|bale.MenuKeyboardMarkup
, optional) – Message Componentsreply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.
- 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=MissingValue, components=MissingValue, reply_to_message_id=MissingValue, delete_after=None, file_name=None)¶
This service is used to send document.
await bot.send_document(1234, bale.InputFile("FILE_ID"), caption = "this is a caption", ...)
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).document (
bale.Document
|bale.InputFile
|str
|bytes
) – File to send.caption (
str
, optional) – Document caption.components (
bale.InlineKeyboardMarkup
|bale.MenuKeyboardMarkup
, optional) – Message Componentsreply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.file_name (
str
, optional) – Custom file name for the file, when uploading a that.
- 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, *, invoice_payload=MissingValue, photo_url=MissingValue, need_name=False, need_phone_number=False, need_email=False, need_shipping_address=False, is_flexible=True, delete_after=None)¶
You can use this service to send money request messages.
Important
When paying the amount, a fee will be charged from the sender.
Hint
The on_successful_payment event is called when the sent transaction is done.
await bot.send_invoice( 1234, "invoice title", "invoice description", "6037************", [bale.LabeledPrice("label", 2000)], invoice_payload = "unique invoice payload", ... )
Examples
- 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:
Card number
Port number and acceptor number
Wallet number “Bale”
prices (List[
bale.LabeledPrice
]) – A list of prices.invoice_payload (
str
, optional) – Bot-defined invoice payload. This will not be displayed to the user, use for your internal processes.photo_url (
str
, optional) – 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 (
bool
, optional) – Pass True, if you require the user’s full name to complete the order.need_phone_number (
bool
, optional) – Pass True, if you require the user’s phone number to complete the order.need_email (
bool
, optional) – Pass True, if you require the user’s email to complete the order.need_shipping_address (
bool
, optional) – Pass True, if you require the user’s shipping address to complete the order.is_flexible (
bool
, optional) – Pass True, if the final price depends on the shipping method.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.
- 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, components=MissingValue, reply_to_message_id=MissingValue, delete_after=None)¶
Use this method to send point on the map.
await bot.send_location(1234, bale.Location(35.71470468031143, 51.8568519168293))
- 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.components (
bale.InlineKeyboardMarkup
|bale.MenuKeyboardMarkup
, optional) – Message Componentsreply_to_message_id (
str
|int
) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.
- 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_media_group(chat_id, media, *, components=MissingValue, reply_to_message_id=MissingValue)¶
This service is used to send a group of photos, videos, documents or audios as an album. Documents and audio files can be only grouped on an album with messages of the same type.
await bot.send_media_group(1234, [ InputMediaPhoto("File ID", caption="example caption"), InputMediaPhoto("File ID"), InputMediaPhoto("File ID") ], ...)
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).media (
bale.InputMediaPhoto
|bale.InputMediaVideo
|bale.InputMediaAnimation
|bale.InputMediaAudio
|bale.InputMediaDocument
) – Files to send.components (
bale.InlineKeyboardMarkup
|bale.MenuKeyboardMarkup
, optional) – Message Componentsreply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.
- Raises:
NotFound – Invalid media.
Forbidden – You do not have permission to Send media group to chat.
APIError – Send media group Failed.
- async send_message(chat_id, text, *, components=MissingValue, reply_to_message_id=MissingValue, delete_after=None)¶
This service is used to send text messages.
await bot.send_message(1234, "hi, python-bale-bot!", ...)
- 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 (
bale.InlineKeyboardMarkup
|bale.MenuKeyboardMarkup
, optional) – Message Componentsreply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.
- 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=MissingValue, components=MissingValue, reply_to_message_id=MissingValue, delete_after=None, file_name=None)¶
This service is used to send photo.
await bot.send_photo(1234, bale.InputFile("FILE_ID"), caption = "this is a caption", ...)
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).photo (
bale.PhotoSize
|bale.InputFile
|str
|bytes
) – File to send.caption (
str
, optional) – Photo caption.components (
bale.InlineKeyboardMarkup
|bale.MenuKeyboardMarkup
, optional) – Message Componentsreply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.file_name (
str
, optional) – Custom file name for the file, when uploading a that.
- 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_sticker(chat_id, sticker, *, reply_to_message_id=MissingValue, delete_after=None)¶
This service is used to send sticker.
await bot.send_sticker(1234, "FILE ID", ...)
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).sticker (
bale.Sticker
|bale.InputFile
|str
|bytes
) – Sticker file to send.reply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.
- Returns:
The Message.
- Return type:
- Raises:
NotFound – Invalid Chat ID.
Forbidden – You do not have permission to Send Sticker to chat.
APIError – Send sticker Failed.
- async send_video(chat_id, video, *, caption=MissingValue, components=MissingValue, reply_to_message_id=MissingValue, delete_after=None, file_name=None)¶
This service is used to send Video.
await bot.send_video(1234, bale.InputFile("FILE_ID"), caption = "this is a caption", ...)
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).video (
bale.Video
|bale.InputFile
|str
|bytes
) – File to send.caption (
str
, optional) – Video caption.components (
bale.InlineKeyboardMarkup
|bale.MenuKeyboardMarkup
, optional) – Message Componentsreply_to_message_id (
str
|int
, optional) – If the message is a reply, ID of the original message.delete_after (
float
|int
, optional) – If used, the sent message will be deleted after the specified number of seconds.file_name (
str
, optional) – Custom file name for the file, when uploading a that.
- 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_chat_photo(chat_id, photo)¶
Use this method to set a new profile photo for the chat.
await bot.set_chat_photo(1234, bale.InputFile("FILE_ID"))
- Parameters:
chat_id (
str
|int
) – Unique identifier for the target chat or username of the target channel (in the format@channelusername
).photo (
bale.PhotoSize
|bale.InputFile
|str
|bytes
) – New chat photo. visitbale.InputFile
to see more info.
- Returns:
On success, True is returned.
- Return type:
- Raises:
NotFound – Invalid Chat ID.
Forbidden – You do not have permission to Set Chat Photo to chat.
APIError – Set chat photo 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.
await bot.set_webhook("https://example.com")
- property state¶
Represents the state class for cache data.
None
if bot not logged in- Type:
bale.State
, optional
- async unban_chat_member(chat_id, user_id, *, only_if_banned=MissingValue)¶
Use this method to unban a previously kicked user in a group or channel. The user will not return to the group or channel automatically, but will be able to join via link, etc. The bot must be an administrator for this to work. By default, this method guarantees that after the call the user is not a member of the chat, but will be able to join it. So if the user is a member of the chat they will also be removed from the chat. If you don’t want this, use the parameter only_if_banned.
await bot.unban_chat_member(1234, 1234)
- Parameters:
- Returns:
On success,
True
is returned.- Return type:
- Raises:
NotFound – Invalid Chat or User ID.
Forbidden – You do not have permission to unban Chat Member.
APIError – unban chat member Failed.
- wait_for(checks, timeout=None)¶
Waits for a handler 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 nottimeout
. Note that this does propagate theasyncio.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.Important
This function returns the first check that meets the requirements.
Hint
To get better hints in the IDE, you should add a typehint to the result of this method.
from bale import WaitContext ... ctx: WaitContext = await bot.wait_for(...)
Examples
- Parameters:
checks (Dict[
int
|str
,bale.BaseCheck
] |bale.BaseCheck
| List[bale.BaseCheck
]) –The checks must be of the following types:
- an instance of
bale.BaseCheck
object from bale.checks import MessageId ... context = await bot.wait_for(MessageId(...), ...)
- an instance of
- a list that contains the
bale.BaseCheck
object from bale.checks import ATTACHMENT, MessageId, CAPTION ... context = await bot.wait_for([ ATTACHMENT, # message has any attachment (voice, audio, document, ...) MessageId(1234), # The unique identifier of the message must be equal to "1234" CAPTION # message has any caption ], ...)
- a list that contains the
- a dict whose keys is types of
int
orstr
and it’s values is types of instances ofbale.BaseCheck
object from bale.checks import ATTACHMENT, MessageId, CAPTION ... context = await bot.wait_for({ 1: ATTACHMENT, # message has any attachment (voice, audio, document, ...) 2: MessageId(1234), # The unique identifier of the message must be equal to "1234" 3: CAPTION # message has any caption }, ...) if context.key == 1: # is the check key "1"? await context.update.message.reply("you're sent a message with caption")
- a dict whose keys is types of
timeout (
float
, optional) –The number of seconds to wait before timing out and raising
asyncio.TimeoutError
.Hint
An example with use timeout argument:
from bale.checks import MessageCheck ... try: context = await bot.wait_for(MessageCheck(), timeout=20.0) # MessageCheck is a simple check to get a message except asyncio.TimeoutError: # 20s A message with the conditions specified in the `checks` parameter was not found. pass
- Raises:
asyncio.TimeoutError – If a timeout is provided, and it was reached.