API Reference

Version Info

bale.__version__

A string representation of the version. e.g. '1.0.0rc1'. This is based off of PEP 440.

Bot

class bale.Bot

This object represents a Bale Bot.

Parameters
  • token (str) – Bot Token

  • updater (Optional[bale.Updater]) –

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

property user

Represents the connected client. None if not logged in

await close()

Close http Events and bot

is_closed()

bool: Connection Status

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.

Returns

True else False if not done

Return type

bool

Raises
  • Forbidden – You do not have permission to delete Webhook.

  • APIError – Delete webhook Failed.

await send_message(chat, text, *, components=None, reply_to_message=None)

This service is used to send text messages.

Parameters
Returns

The Message

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Message to this chat.

  • APIError – Send Message Failed.

await send_document(chat, document, *, caption=None, reply_to_message=None)

This service is used to send document.

Parameters
Returns

The Message.

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Document to this chat.

  • APIError – Send Document Failed.

await send_photo(chat, photo, *, caption=None, reply_to_message=None)

This service is used to send photo.

Parameters
Returns

The Message.

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to Send Photo to chat.

  • APIError – Send photo Failed.

await send_invoice(chat, 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 (bale.Chat | bale.User) – Chat

  • title (str) – Invoice Title

  • description (str) – Invoice Description

  • 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 (str) – Photo URL of Invoice. Defaults to None.

  • need_name (bool) – Get a name from “User”?. Defaults to False.

  • need_phone_number (bool) – Get a Phone number from “User”?. Defaults to False.

  • need_email (bool) – Get an Email from “User”?. Defaults to False.

  • need_shipping_address (bool) – Get a Shipping Address from “User”?. Defaults to False.

  • is_flexible (bool) – Is the Invoice Photo Flexible to the Payment button?. Defaults to True.

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Invoice to this chat.

  • APIError – Send Invoice Failed.

await edit_message(chat, message, text, *, components=None)

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

Parameters
Raises
  • NotFound – Invalid Message or Chat ID.

  • Forbidden – You do not have permission to Edit Message.

  • APIError – Edit Message Failed.

await delete_message(chat, message)

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
Raises
  • NotFound – Invalid Message or Chat ID.

  • Forbidden – You do not have permission to Delete Message.

  • APIError – Delete Message Failed.

await get_chat(chat_id)

This service can be used to receive personal information that has previously interacted with the arm.

Parameters

chat_id (int | str) – chat id

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.

await get_user(user_id)

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

Parameters

user_id (int) – user id

Returns

The user or None if not found.

Return type

Optional[bale.User]

Raises
  • Forbidden – You do not have permission to get User.

  • APIError – Get user Failed.

await get_chat_member(chat, user_id)
Parameters
Returns

The chat member or 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.

await invite_to_chat(chat, user)

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.

await leave_chat(chat)

Leave bot from a Chat

Parameters

chat (bale.Chat) – chat

Raises
  • Forbidden – You do not have permission to Leave from chat.

  • APIError – Leave from chat Failed.

await get_chat_members_count(chat)
Parameters

chat (bale.Chat) –

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to get Members count of the Chat.

  • APIError – get Members count of the Chat Failed.

Returns

The members count of the chat

Return type

int

await get_chat_administrators(chat)

This service can be used to display admins of a group or channel.

Parameters

chat (bale.Chat) – Group id

Returns

list of chat member or None if chat not found.

Return type

Optional[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.

run(sleep_after_every_get_updates=None)

Run bot and https

Models

CallbackQuery

Attributes
class bale.CallbackQuery

This object represents an incoming callback query from a callback button in an inline keyboard.

property user

Aliases for from_user

Chat

class bale.Chat

This object indicates a chat.

chat_id

Chat ID.

Type

str

_type

Chat Type.

Type

bale.ChatType

title

Chat Title.

Type

str

username

Chat Username (for DM or PV).

Type

str

first_name

First name Chat (for DM or PV).

Type

str

last_name

Last name Chat (for DM or PV).

Type

str

pinned_message

Pinned messages in chat. Defaults to None.

Type

bale.Message

all_members_are_administrators

Does everyone have admin access?. Defaults to True. (for Group)

Type

bool

bot

Bot Object. Defaults to None.

Type

bale.Bot

property type

Get chat type

property mention

Optional[str]

await send(text, components=None)

For the documentation of the arguments, please see bale.Bot.send_message().

Parameters
Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Message to this chat.

  • APIError – Send Message Failed.

await send_document(document, *, caption=None)

For the documentation of the arguments, please see bale.Bot.send_photo().

Parameters
Returns

On success, the sent Message is returned.

Return type

Optional[bale.Message]

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Document to this chat.

  • APIError – Send Document Failed.

await send_photo(photo, *, caption=None)

For the documentation of the arguments, please see bale.Bot.send_photo().

Parameters
Returns

On success, the sent Message is returned.

Return type

Optional[bale.Message]

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Photo to chat.

  • APIError – Send Photo Failed.

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()

Parameters
  • title (str) – Invoice Title

  • description (str) – Invoice Description

  • provider_token (str) –

    Note

    You can use 3 methods to receive money:
    • Card number

    • Port number and acceptor number

    • Wallet number “Bale”

  • prices (List[bale.Price]) – A list of prices.

  • photo_url (Optional[str]) – Photo URL of Invoice.

  • need_name (Optional[bool]) – Get a name from “User”?

  • need_phone_number (Optional[bool]) – Get a Phone number from “User”?.

  • need_email (Optional[bool]) – Get a Email from “User”?.

  • need_shipping_address (Optional[bool]) – Get a Shipping Address from “User”?.

  • is_flexible (Optional[bool]) – Is the Invoice Photo Flexible to the Payment button?

Returns

On success, the message sent returned.

Return type

Bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Invoice to this chat.

  • APIError – Send Invoice Failed.

await leave()

For the documentation of the arguments, please see bale.Bot.leave_chat().

Raises
  • Forbidden – You do not have permission to Leave from chat.

  • APIError – Leave from chat Failed.

await add_user(user)

For the documentation of the arguments, please see bale.Bot.invite_to_chat().

Parameters

user (bale.User) – user

Raises
await get_chat_member(user)

For the documentation of the arguments, please see bale.Bot.get_chat_member().

Parameters

user (bale.User) – User

Returns

The chat member or None if not found.

Return type

Optional[bale.ChatMember]

Raises
  • NotFound – Invalid User.

  • Forbidden – You do not have permission to get Chat Member.

  • APIError – Get chat member Failed.

await get_chat_members_count()

For the documentation of the arguments, please see bale.Bot.get_chat_members_count().

Returns

The members count of the chat.

Return type

int

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.

await get_chat_administrators()

For the documentation of the arguments, please see bale.Bot.get_chat_administrators().

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.

Returns

On success, The chat members is returned.

Return type

Optional[List[bale.ChatMember]]

Chat Type

class bale.ChatType

This object indicates a Chat Type.

is_private_chat()

bool: Return True if Chat Type is Private

is_group_chat()

bool: Return True if Chat Type is Group

User

class bale.User

This object shows a user.

user_id
Type

int

first_name
Type

str

last_name
Type

str

username
Type

Optional[str]

property mention

Optional[str]

property chat_id

str

await send(text, components=None)

For the documentation of the arguments, please see bale.Bot.send_message().

Parameters
Returns

On success, the sent Message is returned.

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Message to this chat.

  • APIError – Send Message Failed.

await send_document(document, *, caption=None)

For the documentation of the arguments, please see bale.Bot.send_document().

Parameters
Returns

On success, the sent Message is returned.

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Document to this chat.

  • APIError – Send Document Failed.

await send_photo(photo, *, caption=None)

For the documentation of the arguments, please see bale.Bot.send_photo().

Parameters
Returns

On success, the sent Message is returned.

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Photo to chat.

  • APIError – Send Photo Failed.

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()

Parameters
  • title (str) – Invoice Title

  • description (str) – Invoice Description

  • provider_token (str) –

    Note

    You can use 3 methods to receive money:
    • Card number

    • Port number and acceptor number

    • Wallet number “Bale”

  • prices (List[bale.Price]) – A list of prices.

  • photo_url (Optional[str]) – Photo URL of Invoice.

  • need_name (Optional[bool]) – Get a name from “User”?

  • need_phone_number (Optional[bool]) – Get a Phone number from “User”?.

  • need_email (Optional[bool]) – Get a Email from “User”?.

  • need_shipping_address (Optional[bool]) – Get a Shipping Address from “User”?.

  • is_flexible (Optional[bool]) – Is the Invoice Photo Flexible to the Payment button?

Returns

On success, the message sent returned.

Return type

Bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Invoice to this chat.

  • APIError – Send Invoice Failed.

ChatMember

Attributes
class bale.ChatMember

This object shows a member in chat

role

User Role

Type

bale.MemberRole

user

User

Type

bale.User

permissions

User Permissions

Type

bale.AdminPermissions

MemberRole

class bale.MemberRole

This object shows member’s role in chat.

is_owner()

bool: Return True if Member is chat creator

is_admin()

bool: Return True if Member have admin role

Message

class bale.Message

This object shows a message.

message_id

Message ID.

Type

str

date

When the message has been sent.

Type

datetime.datetime

text

Message Content

Type

Optional[str]

caption

Message caption.

Type

Optional[str]

from_user

The user who has sent the message.

Type

Optional[bale.User]

forward_from

The user who has sent the message originally.

Type

Optional[bale.User]

forward_from_chat

The chat from which the message was forwarded.

Type

Optional[bale.Chat]

contact

Contact

Type

Optional[bale.ContactMessage]

chat

The chat where the message is sent.

Type

bale.Chat

reply_to_message

The message Replayed to who message.

Type

Optional[bale.Message]

new_chat_members

User (An) who entered the chat.

Type

Optional[List[bale.User]]

left_chat_member

A user out of chat.

Type

Optional[bale.User]

invoice

Message invoice.

Type

Optional[bale.Invoice]

property author

An alias for from_user

await reply(text, *, components=None)

For the documentation of the arguments, please see bale.Bot.send_message().

Parameters
Returns

On success, the sent Message is returned.

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Message to this chat.

  • APIError – Send Message Failed.

await reply_document(document, *, caption=None)

For the documentation of the arguments, please see bale.Bot.send_document().

Parameters
Returns

The Message.

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Document to this chat.

  • APIError – Send Document Failed.

await reply_photo(photo, *, caption=None)

For the documentation of the arguments, please see bale.Bot.send_photo().

Parameters
Returns

On success, the sent Message is returned.

Return type

bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Photo to chat.

  • APIError – Send Photo Failed.

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()

Parameters
  • title (str) – Invoice Title

  • description (str) – Invoice Description

  • provider_token (str) –

    Note

    You can use 3 methods to receive money:
    • Card number

    • Port number and acceptor number

    • Wallet number “Bale”

  • prices (List[bale.Price]) – A list of prices.

  • photo_url (Optional[str]) – Photo URL of Invoice.

  • need_name (Optional[bool]) – Get a name from “User”?

  • need_phone_number (Optional[bool]) – Get a Phone number from “User”?.

  • need_email (Optional[bool]) – Get an Email from “User”?.

  • need_shipping_address (Optional[bool]) – Get a Shipping Address from “User”?.

  • is_flexible (Optional[bool]) – Is the Invoice Photo Flexible to the Payment button?

Returns

On success, the message sent returned.

Return type

Bale.Message

Raises
  • NotFound – Invalid Chat ID.

  • Forbidden – You do not have permission to send Invoice to this chat.

  • APIError – Send Invoice Failed.

await edit(text, *, components=None)

For the documentation of the arguments, please see bale.Bot.edit_message()

Parameters
Raises
  • NotFound – Invalid Message or Chat ID.

  • Forbidden – You do not have permission to Edit Message.

  • APIError – Edit Message Failed.

await delete()

For the documentation of the arguments, please see bale.Bot.delete_message().

Raises
  • NotFound – Invalid Message or Chat ID.

  • Forbidden – You do not have permission to Delete Message.

  • APIError – Delete Message Failed.

Update

class bale.Update

This object shows an update.

update_id

Update ID

Type

int

callback_query

Callback Query

Type

Optional[bale.CallbackQuery]

message

Message

Type

Optional[bale.Message]

edited_message

Edited Message

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

Components

class bale.Components
Parameters

Inline Keyboard

class bale.InlineKeyboard

This object shows an inline keyboard (within the message).

text

Label text on the button.

Type

str

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

str

url

HTTP url to be opened when the button is pressed. Defaults to None.

Type

str

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

str

switch_inline_query_current_chat

If set, pressing the button will insert the bot’s username and the specified inline query in the current chat’s input field. Can be empty, in which case only the bot’s username will be inserted. Defaults to None.

Type

str

Keyboard

Attributes
class bale.Keyboard

This object shows a keyboard

text

Keyboard Text.

Type

str

Remove Components

class bale.RemoveComponents

This object shows a remove keyboard.

Attachment Models

Audio

class bale.Audio

This object shows a waist.

file_id

Audio ID

Type

str

duration

Audio duration

Type

int

file_size

Audio Size.

Type

int

mime_type

Audio Mime type.

Type

Optional[str]

title

Audio Title.

Type

Optional[str]

Contact Message

class bale.ContactMessage

This object shows a Message Contact.

phone_number
Type

int

first_name
Type

Optional[str]

last_name
Type

Optional[str]

user
Type

Optional[bale.User]

Document

Methods
class bale.Document

This object shows a Document.

file_id
Type

Optional[str]

file_name
Type

Optional[str]

mime_type
Type

Optional[str]

file_size
Type

Optional[int]

await read()

Read the Document.

Returns

Document

Return type

bytes

Raises
  • NotFound – Document not found.

  • Forbidden – You do not have permission to read document.

  • APIError – Read document Failed.

await save(file_name)

Save the Document.

Parameters

file_name (str) –

Raises
  • NotFound – Document not found.

  • Forbidden – You do not have permission to read document.

  • APIError – Read document Failed.

  • OSError – Open or write into file Failed.

Photo

class bale.Photo

This object shows a Photo.

file_id

Audio ID

Type

str

width

Photo width

Type

int

file_size

Audio Size.

Type

int

height

Photo height.

Type

str

Location

Attributes
class bale.Location

This object shows an end

longitude

Location longitude

Type

int

latitude

Location latitude

Type

int

Type

str

Payment Models

Invoice

class bale.Invoice

This object shows Invoice

title

Invoice title.

Type

str

description

Invoice Description.

Type

str

start_parameter

No Description.

Type

str

currency

No Description.

Type

str

total_amount

No Description.

Type

int

Price

Attributes
class bale.Price

This object shows a Price

label

Label Price.

Type

Optional[str]

amount

Amount Price.

Type

Optional[int]

Event Reference

Event Types

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):
    ...

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

Callback

bale.on_callback(callback)

Called when a Callback Sent.

Parameters

callback (bale.CallbackQuery) – The callback

Exceptions

The following exceptions are thrown by the library.

exception bale.BaleError(message)

Base exception class for python-bale-bot

message

The text of the error. Could be an None.

Type

str

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.RateLimited

Exception that’s raised for when Rate Limits. Subclass of BaleError

exception bale.HTTPException(error)

Exception that’s raised when an HTTP request operation fails.