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

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()
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=None, components=None, reply_to_message_id=None)

This service is used to send text messages.

Parameters:
  • chat (bale.Chat) – Chat

  • text (str) – Message Text

  • components (bot.Components`|:class:`bale.RemoveComponents) – Message Components

  • reply_to_message_id (str) – Reply Message ID

Raises:

bale.Error

Returns:

The Message or None if message not sent

Return type:

Optional[bale.Message]

await send_photo(chat, photo, caption=None, reply_to_message_id=None)

This service is used to send photo.

Parameters:
  • chat (bale.Chat) – Chat

  • photo (bytes`|:class:`str`|:class:`bale.Photo) – Photo

  • caption ((str):) – Message caption

  • reply_to_message_id (str) – Reply Message ID

Raises:

bale.Error

Returns:

The Message or None if message not sent

Return type:

Optional[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) – 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_id, 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_id)

You can use this service to delete a message that you have already sent through the arm.

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 (str | int) – 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 users.

Parameters:

user_id (str | 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)
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]]

await get_updates(offset=None, limit=None)

Use this method to receive incoming updates using long polling.

Parameters:
  • offset (Optional[int]) – Offset

  • limit (Optional[int]) – updates limit in list

Raises:

bale.Error

Returns:

The list of Updates or None if updates not found.

Return type:

List[bale.Update]

run()

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

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

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]

await send(text, components=None)

Send a Text Message to User

Parameters:
Returns:

On success, the sent Message is returned.

Return type:

bale.Message

await send_photo(photo, caption=None)

This service is used to 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

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

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

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

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:

unt

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.

Raises:

bale.Error

Return type:

bytes

await save(file_name)

Save the Document.

Parameters:

file_name (str) –

Raises:

bale.Error

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

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