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

Attributes
Methods
class bale.Bot

This object represents a Bale Bot.

Parameters

token (str) – Bot Token

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

Bale.Error –

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

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

This service is used to send text messages.

Parameters
Raises

bale.Error –

Returns

The Message

Return type

bale.Message

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

This service is used to send document.

Parameters
Raises

bale.Error –

Returns

The Message.

Return type

bale.Message

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

This service is used to send photo.

Parameters
Raises

bale.Error –

Returns

The Message.

Return type

bale.Message

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 a 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

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

bale.Error –

Return type

dict

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
Returns

True if done else False

Return type

bool

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

Raises

bale.Error –

Returns

The chat or None if not found.

Return type

Optional[bale.Chat]

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

Raises

bale.Error –

Returns

The user or None if not found.

Return type

Optional[bale.User]

await get_chat_member(chat, user_id)
Parameters
Raises

bale.Error –

Returns

The chat member or None if not found.

Return type

Optional[bale.ChatMember]

await invite_to_chat(chat, user)

Invite user to the chat

Parameters
Raises

bale.Error –

Returns

True when user added to chat else False

Return type

bool

await leave_chat(chat)

Leave bot from a Chat

Parameters

chat (bale.Chat) – chat

Raises

bale.Error –

Returns

True when bot leaved from chat else False

Return type

bool

await get_chat_members_count(chat)
Parameters

chat (bale.Chat) –

Raises

bale.Error – Group ID

Returns

int or None if chat not found.

Return type

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

Raises

bale.Error –

Returns

list of chat member or None if chat not found.

Return type

Optional[List[bale.ChatMember]]

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.

Parameters

  • callback_id (int) – Callback Query ID

  • data (str) – Callback Data

  • message (bale.Message) – Callback Message

  • inline_message_id (str) – Callback inline message id

  • from_user (bale.User) – Callback The user who gave the callback.

  • bot (Optional[bale.Bot]) – Bot object.

property user

Aliases for from_user

Chat

Attributes
Methods
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

await send_photo(photo, caption=None)

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

Parameters
Raises

bale.Error –

Returns

On success, the sent Message is returned.

Return type

Optional[bale.Message]

await leave()

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

Returns

bool:

On success, True.

await add_user(user)

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

Parameters

user (bale.User) – user

Returns

One success, True.

Return type

bool

await get_chat_member(user)

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

Parameters

user (bale.User) – User

Returns

On success, The chat member is retuened.

Return type

Optional[bale.ChatMember]

await get_chat_members_count()

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

Returns

On success, The count of chat members is returned.

Return type

Optional[int]

await get_chat_administrators()

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

Raises

bale.Error –

Returns

On success, The chat members is returned.

Return type

Optional[List[bale.ChatMember]]

User

Attributes
Methods
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

await send_document(document, caption=None)

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

Parameters
Raises

bale.Error –

Returns

On success, the sent Message is returned.

Return type

bale.Message

await send_photo(photo, caption=None)

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

Parameters
Raises

bale.Error –

Returns

On success, the sent Message is returned.

Return type

bale.Message

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

Message

Attributes
Methods
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]

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]

await reply(text, *, components=None)

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

Parameters
Raises

bale.Error –

Returns

On success, the sent Message is returned.

Return type

bale.Message

await reply_photo(photo, caption=None)

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

Parameters

  • photo (bytes | str) – Photo

  • caption (Optional[str]) – Message caption

Raises

bale.Error –

Returns

On success, the sent Message is returned.

Return type

bale.Message

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

await edit(text=None, components=None)

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

Parameters
Raises

bale.Error –

Return type

dict

await delete()

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

Returns

True when user added to chat else False

Return type

bool

Update

Attributes
class bale.Update

This object shows an update.

update_id

Update ID

Type

int

type

Chat type

Type

str

callback_query

Callback Query

Type

Optional[bale.CallbackQuery]

message

Message

Type

Optional[bale.Message]

edited_message

Edited Message

Type

Optional[bale.Message]

Components

class bale.Components
Parameters

Inline Keyboard

Attributes
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

Attributes
class bale.Audio

This object shows a waist.

file_id

Audio ID

Type

str

duration

Audio duration

Type

int

file_size

Audio Size.

Type

unt

mime_type

Audio Mime type.

Type

Optional[str]

title

Audio Title.

Type

Optional[str]

Contact Message

Attributes
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

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

Raises

bale.Error –

Return type

bytes

await save(file_name)

Save the Document.

Parameters

file_name (str) –

Raises

bale.Error –

Photo

Attributes
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

Attributes
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