Bots creation API¶

botogram is a microframework aimed to help you creating bots. It’s obvious it has something to create them! Here is the reference of all the needed components.

botogram.create(api_key)¶

Create a new bot. This is a shortcut of directly creating the botogram.Bot instance, because it automatically creates the API connection instance. Be sure to provide a valid API key.

Parameters:	api_key (str) – The API key you received from Telegram
Returns:	The bot instance
Return type:	botogram.Bot

class botogram.Bot(api_connection)¶

This class represents a single bot, and contains all of its logic. You can customize this class either extending it or with the decorators it provides. It requires a valid connection to the Telegram API.

If you don’t want to create the connection manually, it’s better you use the botogram.create() utility function.

Parameters:	api_connection (botogram.TelegramAPI) – The connection to the API

about¶: About message of the bot, which should describe what the bot does. It will be displayed in the /help and /start builtin commands.

owner¶: The username of the bot’s owner, which will be displayed in the /help command. This attribute will be sent directly to the user, so if you want to insert a username be sure to prefix it with @, so the Telegram client will make that text clickable.

before_help¶: A list of strings to be inserted in the /help messages. These ones will be inserted before the commands list.

after_help¶: A list of strings to be inserted in the /help messages. These ones will be inserted after the commands list.

link_preview_in_help¶: Disable link preview in the /help messages.

New in version 0.4.

validate_callback_signatures¶

Enable or disable signature verification for callbacks. Disabling them can cause security issues for your bot, and it’s advised to do so only if you changed the bot token recently. See the security section for callbacks for more details.

The default value is True.

New in version 0.4.

process_backlog¶: A boolean representing if the backlog should be processed. Backlog is intended as all the messages sent to the bot before its startup. If this attribute is set to False, as by default, the backlog is not processed by the bot.

itself¶: The botogram.User representation of the bot’s user account. From this you can access its id, username and more.

lang¶: The ISO 639-1 code assigned the language used by the bot.

override_i18n¶: A dictionary that allows to override default i18n messages by associating the default msgid string of a message with its alternative.

New in version 0.5.

@before_processing¶

Functions decorated with this decorator will be called before an update is processed. This allows you, for example, to set up a filter on who can send messages to the bot. Decorated functions will be called with two parameters:

A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
A message parameter with the representation of the received message (an instance of botogram.Message)

If the function returns True, then the message processing is stopped, and no more functions will be called for this update.

@process_message¶

Functions decorated with this decorator will be called while processing an update. You can then do everything you want in it. Decorated functions will be called with two parameters:

A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
A message parameter with the representation of the received message (an instance of botogram.Message)

If the function returns True, then the message processing is stopped, and no more functions will be called for this update.

Note

This decorator is a low-level one: you might want to use the more friendly ones, like botogram.Bot.message_contains(), botogram.Bot.message_matches() and botogram.Bot.command().

@message_equals(string[, ignore_case=True])¶

Functions decorated with this decorator will be called only if the processed message is equal to the string you provided. You may also define if you want to ignore the casing. Decorated functions will be called with two parameters:

A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
A message parameter with the representation of the received message (an instance of botogram.Message).

If the function returns True, then the message processing is stopped, and no more functions will be called for this update.

Parameters:	string (str) – The string you want equals to the message ignore_case (bool) – If the check should be ignore-case

@message_contains(string[, ignore_case=True, multiple=False])¶

Functions decorated with this decorator will be called only if the processed message matches the string you provided. You may also define if you want to ignore the casing, and if the function should be called multiple times when multiple matches are found in the same message. Decorated functions will be called with two parameters:

A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
A message parameter with the representation of the received message (an instance of botogram.Message)

If the function returns True, then the message processing is stopped, and no more functions will be called for this update.

Parameters:	string (str) – The string you want contained in the message ignore_case (bool) – If the match should be ignore-case multiple (bool) – If the function should be called multiple times on multiple matches.

@message_matches(regex[, flags=0, multiple=False])¶

Functions decorated with this decorator will be called only if the processed message matches the regex you provided. You may also pass the re module’s flags, and if the function should be called when multiple matches are found in the same message. Decorated functions will be called with two parameters:

A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
A message parameter with the representation of the received message (an instance of botogram.Message)
A matches parameter with a tuple containing the matched groups

If the function returns True, then the message processing is stopped, and no more functions will be called for this update.

Parameters:	string (str) – The string you want contained in the message flags (int) – `re` module’s flags multiple (bool) – If the function should be called multiple times on multiple matches.

@message_edited¶

All the functions decorated with this method will be called when an user edits a message the bot knows about. This allows you, for example, to update the preview of a message if the user edits the request, or to enforce a no-edits policy on groups by banning whoever edits a message.

You can request the following arguments in the decorated functions:

chat: the chat in which the message was originally sent (instance of Chat)
message: the edited message (instance of Message)

@bot.message_edited
def no_edits(chat, message):
    message.reply("You can't edit messages! Bye.")
    chat.ban(message.sender)

New in version 0.3.

@channel_post¶

Functions decorated with this decorator will receive all the messages posted to channels the bot is a member of. This allows you to act when certain messages are received, as an example.

You can request the following arguments in the decorated functions:

chat: the chat in which the channel post was originally sent (instance of Chat)
message: the message (instance of Message)

@bot.channel_post
def channel_post(chat, message):
    message.reply("I read this post!")

New in version 0.4.

@channel_post_edited¶

Functions decorated with this decorator will receive all the messages edited in channels the bot is a member of. This allows you to act when certain messages are changed, as an example.

You can request the following arguments in the decorated functions:

chat: the chat in which the channel post was originally sent (instance of Chat)
message: the (new) edited message (instance of Message)

@bot.channel_post_edited
def channel_post_edited(chat, message):
    message.reply("This post is changed!")

New in version 0.4.

@poll_update¶

Functions decorated with this decorator will receive all the updates about new poll states. This allows you to act when a poll sent by the bot is changed (i.e. new votes) or when a poll seen by the bot is closed.

You can request the following arguments in the decorated functions:

poll: the poll that has just changed state (instance of Poll)

@bot.poll_update
def poll_update(poll):
    chat_id = mydb.retrieve_chat_by_poll_id(poll.id)  # Dummy method
    if poll.is_closed:
        bot.chat(chat_id).send('Poll final results!\n%s' %
                               '\n'.join(['%s: %s' % (o.text, str(o.voter_count)) for o in poll.options]))

New in version 0.7.

@command(name[, hidden=False, order=0])¶

This decorator register a new command, and calls the decorated function when someone issues the command in a chat. The command will also be added to the /help message. The decorated function will be called with three parameters:

A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
A message parameter with the representation of the received message (an instance of botogram.Message)
An args parameter with the list of parsed arguments

If you put a docstring on the decorated function, that will be used as extended description of the command in the /help command. Also, if you don’t want this command to appear in the /help, you can set the hidden argument to True.

Parameters:	name (str) – The name of the command. hidden (bool) – If the command should be hidden from `/help` order (int) – The order in which the commands are shown in `/help`

Changed in version 0.4: Added the order argument.

Changed in version 0.3: Added the hidden argument.

@callback(name)¶

This decorator adds an handler for the callback with the provided name. See the chapter about buttons and callbacks for more information about them.

You can request the following arguments in the decorated function:

query: the received CallbackQuery
chat: the Chat from which the callback query was sent
message: the Message related to the callback query
data: the custom information provided by you along with the call

@bot.command("greeter")
def greeter_command(chat, message):
    """Say hi to the user"""
    btns = botogram.Buttons()
    btns[0].callback("Click me", "say-hi", message.sender.name)

    chat.send("Click the button below", attach=btns)

@bot.callback("say-hi")
def say_hi_callback(query, data):
    query.notify("Hi " + data)

Parameters:	name (str) – the name of the callback

New in version 0.4.

@chat_unavailable¶

The decorated function is called when you try to send a message to a chat you can’t send messages to. There are currently multiple reasons why that can happen, and you can see all of them in the narrative documentation.

The decorated function will be called with the following parameters:

chat_id: the ID of the chat which you can’t contact.
reason: the reason why you can’t contact the chat, as a string.

If you want to learn more about unavailable chats check out their documentation.

@timer(interval)¶

Execute the decorated function periodically, at the provided interval, which must be in seconds. You can learn more in the Repeated execution section of the docs.

USER_ID = 12345

@bot.timer(1)
def spammer(bot):
    bot.chat(USER_ID).send("Hey!")

Parameters:	interval (int) – The execution interval, in seconds.

@prepare_memory¶

The function decorated with this decorator will be called the first time you access your bot’s shared memory. This allows you to set the initial state of the memory, without having to put initialization code in every function which uses the shared memory. Please don’t use this function as a “when the bot is started” hook, because it’s not guaranteed to be called if you don’t use shared memory.

The decorated function will be called providing as first argument a dict-like object representing your bot’s shared memory. Use it to prepare the things you want in the shared memory.

@bot.prepare_memory
def initialize(shared):
    shared["messages"] = 0

@bot.process_message
def increment(shared, chat, message):
    if message.text is None:
        return
    shared["messages"] += 1

@bot.command("count")
def count(shared, chat, message, args):
    chat.send("This bot received %s messages" % shared["messages"])

Changed in version 0.2: Before it was called init_shared_memory.

@init_shared_memory¶: This decorator was renamed to prepare_memory() in botogram 0.2. Please use that instead of this.

Deprecated since version 0.2: it will be removed in botogram 1.0

use(component)¶

Use the provided component in your bot, so the hooks the component implements will be called while processing the updates. When you use another component, its hooks will be called before the one you provided before.

Parameters:	component (botogram.Component) – The component you want to use.

process(update)¶

Process a single update. This is useful if you want to manually process some updates or you want to create a custom runner.

Parameters:	update (botogram.Update) – The update you want to process

run([workers=2])¶

Run the bot with the multi-process runner botogram ships with. You can define how much update workers you want. Remember: the number of actual processes is the number you provide plus two (the current and the updates fetcher).

Calls to this method are blocking, and the method won’t return until the runner stops, so if you want to add other code to your bot, be sure to put it before the method call.

Parameters:	workers (int) – The number of updates workers you want to use

freeze()¶

Return a frozen instance of the bot. A frozen instance is exactly the same as the normal one, but you can’t change the content of it. Frozen instances are used by the runner and by the botogram.Bot.process() method.

Returns:	A frozen instance of the current bot.

edit_message(chat, message, text[, syntax=None, preview=True, attach=None, extra=None])¶

With this method you can edit the text of a message the user already received. This allows you to do a lot of interesting things, like live-updating information or showing paginated results: you just need to provide the id of the message, the id of the chat in which the message was sent, the new text of the message, and if you want to show the preview. The syntax parameter is for defining how the message text should be processed by Telegram (learn more about rich formatting).

Please remember you can only edit messages your bot sent to the user.

Parameters:

chat (int) – ID of the chat in which the message was sent
message (int) – ID of the message you want to edit
text (str) – The new text of the message
preview (bool) – Whether to show link previews.
syntax (str) – The name of the syntax used for the message.
attach (object) – An extra thing to attach to the message.
extra (object) – An extra reply interface object to attach.

New in version 0.3.

Changed in version 0.6: Added support for attach

edit_caption(caption[, attach=None, extra=None])¶

With this method you can edit the caption of the media attached to a message the user already received. This allows you to do a lot of interesting things, like live-updating information or showing dynamic subtitles: you just need to provide the new caption.

Please remember you can only edit messages your bot sent to the user.

Parameters:	caption (str) – The new caption of the media file. attach (object) – An extra thing to attach to the message. extra (object) – An extra reply interface object to attach.

New in version 0.3.

Changed in version 0.6: Added support for attach

chat(id)¶

Get the Chat object of the chat with the ID you provided to this method. You can use this to get information about a chat you know about, or to send messages to other chats:

BROADCAST_TO = [123, 321, 132]  # List of chat IDs

@bot.command("broadcast")
def broadcast_command(bot, chat, message, args):
    """Broadcast a message to multiple chats"""
    to_send = " ".join(args)

    for chat_id in BROADCAST_TO:
        bot.chat(chat_id).send(to_send)

If your bot can’t access the chat, an exception will be raised. Check out the documentation about unavailable chats to learn more about that.

New in version 0.3.

Changed in version 0.3.3: If your bot can’t access the chat, a ChatUnavailableError will be raised.

send(chat, message[, preview=True, reply_to=None, syntax=None, extra=None, notify=True])¶

This method sends a message to a specific chat. The chat must be identified by its ID, and Telegram applies some restrictions on the chats allowed to receive your message: only users who sent you a message in the past are allowed, and also the group chats your bot is currently in.

You must provide a message, and you can define if a preview for links should be showed (yes by default), the message ID of the message this one is replying to, and an extra object. One of these objects can be provided as the extra one:

The syntax parameter is for defining how the message text should be processed by Telegram (learn more about rich formatting).

The notify parameter is for defining if your message should trigger a notification on the client side (yes by default).

Parameters:	chat (int) – The ID of the chat which should receive the message. message (str) – The message you want to send. preview (bool) – If you want to show the link preview. reply_to (int) – The ID of the message this one is replying to. syntax (string) – The name of the syntax you used for the message. extra (object) – An extra object you want to attach (see above). notify (bool) – If you want to trigger the client notification.
Returns:	The message you sent
Return type:	Message

Changed in version 0.3: Now the method returns the sent message

Deprecated since version 0.3: it will be removed in botogram 1.0

send_photo(chat, path[, caption="", reply_to=None, extra=None, notify=True])¶

This method sends a photo to a specific chat. The chat must be identified by its ID, and Telegram applies some restrictions on the chats allowed to receive your photo: only users who sent you a message in the past are allowed, and also the group chats your bot is currently in.

You must provide the path to the photo, and you can specify a photo caption, the message ID of the message this one is replying to, and an extra object. One of these objects can be provided as the extra one:

The notify parameter is for defining if your message should trigger a notification on the client side (yes by default).

Parameters:	chat (int) – The ID of the chat which should receive the photo. path (str) – The path to the photo you want to send. caption (str) – An optional caption for the photo. reply_to (int) – The ID of the message this one is replying to. extra (object) – An extra object you want to attach (see above). notify (bool) – If you want to trigger the client notification.
Returns:	The message you sent
Return type:	Message

Changed in version 0.3: Now the method returns the sent message

Deprecated since version 0.3: it will be removed in botogram 1.0

send_audio(chat, path[, duration=None, performer=None, title=None, reply_to=None, extra=None, notify=True])¶

This method sends an audio track to a specific chat. The chat must be identified by its ID, and Telegram applies some restrictions on the chats allowed to receive your photo: only users who sent you a message in the past are allowed, and also the group chats your bot is currently in.

You must provide the path to the audio track, and you may optionally specify the duration, the performer and the title of the audio track. If the audio track you’re sending is in reply to another message, set reply_to to the ID of the other Message. extra is an optional object which specifies additional reply interface options on the recipient’s end, and can be one of the following types:

The notify parameter is for defining if your message should trigger a notification on the client side (yes by default).

Parameters:	chat (int) – The ID of the chat which should receive the photo. path (str) – The path to the audio track duration (int) – The track duration, in seconds performer (str) – The name of the performer title (str) – The title of the track reply_to (int) – The ID of the `Message` this one is replying to extra (object) – An extra reply interface object to attach notify (bool) – If you want to trigger the client notification.
Returns:	The message you sent
Return type:	Message

Changed in version 0.3: Now the method returns the sent message

Deprecated since version 0.3: it will be removed in botogram 1.0

send_voice(chat, path[, duration=None, reply_to=None, extra=None, notify=True])¶

This method sends a voice message to a specific chat. The chat must be identified by its ID, and Telegram applies some restrictions on the chats allowed to receive your photo: only users who sent you a message in the past are allowed, and also the group chats your bot is currently in.

You must provide the path to the voice message, and you may optionally specify the duration of the voice message. If the voice message you’re sending is in reply to another message, set reply_to to the ID of the other Message. extra is an optional object which specifies additional reply interface options on the recipient’s end, and can be one of the following types:

The notify parameter is for defining if your message should trigger a notification on the client side (yes by default).

Parameters:	chat (int) – The ID of the chat which should receive the photo. path (str) – The path to the voice message duration (int) – The message duration, in seconds reply_to (int) – The ID of the `Message` this one is replying to extra (object) – An extra reply interface object to attach notify (bool) – If you want to trigger the client notification.
Returns:	The message you sent
Return type:	Message

Changed in version 0.3: Now the method returns the sent message

Deprecated since version 0.3: it will be removed in botogram 1.0

send_video(chat, path[, duration=None, caption=None, reply_to=None, extra=None, notify=True])¶

This method sends a video to a specific chat. The chat must be identified by its ID, and Telegram applies some restrictions on the chats allowed to receive your photo: only users who sent you a message in the past are allowed, and also the group chats your bot is currently in.

You must provide the path to the video, and you may optionally specify the duration and the caption of the video. If the video you’re sending is in reply to another message, set reply_to to the ID of the other Message. extra is an optional object which specifies additional reply interface options on the recipient’s end, and can be one of the following types:

The notify parameter is for defining if your message should trigger a notification on the client side (yes by default).

Parameters:	chat (int) – The ID of the chat which should receive the video path (str) – The path to the video duration (int) – The video duration, in seconds

:param str caption The caption of the video :param int reply_to: The ID of the Message this one is replying to :param object extra: An extra reply interface object to attach :param bool notify: If you want to trigger the client notification. :returns: The message you sent :rtype: ~botogram.Message

Changed in version 0.3: Now the method returns the sent message

Deprecated since version 0.3: it will be removed in botogram 1.0

send_file(chat, path[, reply_to=None, extra=None, notify=True])¶

This method sends a generic file to a specific chat. The chat must be identified by its ID, and Telegram applies some restrictions on the chats allowed to receive your photo: only users who sent you a message in the past are allowed, and also the group chats your bot is currently in.

You must provide the path to the file. If the file you’re sending is in reply to another message, set reply_to to the ID of the other Message. extra is an optional object which specifies additional reply interface options on the recipient’s end, and can be one of the following types:

The notify parameter is for defining if your message should trigger a notification on the client side (yes by default).

Parameters:	chat (int) – The ID of the chat which should receive the file path (str) – The path to the file reply_to (int) – The ID of the `Message` this one is replying to extra (object) – An extra reply interface object to attach notify (bool) – If you want to trigger the client notification.
Returns:	The message you sent
Return type:	Message

Changed in version 0.3: Now the method returns the sent message

Deprecated since version 0.3: it will be removed in botogram 1.0

send_location(chat, latitude, longitude[, reply_to=None, extra=None, notify=True])¶

This method sends a geographic location to a specific chat. The chat must be identified by its ID, and Telegram applies some restrictions on the chats allowed to receive your locations: only users who sent you a message in the past are allowed, and also the group chats your bot is currently in.

If the location you’re sending is in reply to another message, set reply_to to the ID of the other Message. extra is an optional object which specifies additional reply interface options on the recipient’s end, and can be one of the following types:

The notify parameter is for defining if your message should trigger a notification on the client side (yes by default).

Parameters:	chat (int) – The ID of the chat which should receive the location latitude (float) – The latitude of the location longitude (float) – The longitude of the location reply_to (int) – The ID of the `Message` this one is replying to extra (object) – An extra reply interface object to attach notify (bool) – If you want to trigger the client notification.
Returns:	The message you sent
Return type:	Message

Changed in version 0.3: Now the method returns the sent message

Deprecated since version 0.3: it will be removed in botogram 1.0

send_sticker(sticker[, reply_to=None, extra=None, notify=True])¶

This method sends a sticker to a specific chat chat (in webp format). The chat must be identified by its ID, and Telegram applies some restrictions on the chats allowed to receive your locations: only users who sent you a message in the past are allowed, and also the group chats your bot is currently in.

If the sticker you’re sending is in reply to another message, set reply_to to the ID of the other Message. extra is an optional object which specifies additional reply interface options on the recipient’s end, and can be one of the following types:

The notify parameter is for defining if your message should trigger a notification on the client side (yes by default).

Parameters:	chat (int) – The ID of the chat which should receive the location sticker (str) – The path to the webp-formatted sticker reply_to (int) – The ID of the `Message` this one is replying to extra (object) – An extra reply interface object to attach notify (bool) – If you want to trigger the client notification.
Returns:	The message you sent
Return type:	Message

Changed in version 0.3: Now the method returns the sent message

Deprecated since version 0.3: it will be removed in botogram 1.0

hide_commands¶

This attribute is now deprecated, use the hidden argument of the method you use to register commands (for example the command() decorator or the add_command() method of your component).

A list of all the commands you want to hide from /help. These commands won’t be showed in the general /help, but they will still be available for use or detailed help.

Deprecated since version 0.3: it will be removed in botogram 1.0

Loading...

Bots creation API

Bots creation API¶

Some useful links

Choose version