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 ofbotogram.Chat
) - A
message
parameter with the representation of the received message (an instance ofbotogram.Message
)
If the function returns
True
, then the message processing is stopped, and no more functions will be called for this update.- A
-
@
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 ofbotogram.Chat
) - A
message
parameter with the representation of the received message (an instance ofbotogram.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()
andbotogram.Bot.command()
.- A
-
@
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 ofbotogram.Chat
) - A
message
parameter with the representation of the received message (an instance ofbotogram.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
- A
-
@
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 ofbotogram.Chat
) - A
message
parameter with the representation of the received message (an instance ofbotogram.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.
- A
-
@
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 there
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 ofbotogram.Chat
) - A
message
parameter with the representation of the received message (an instance ofbotogram.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.
- A
-
@
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.
- chat: the chat in which the message was originally sent (instance
of
-
@
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.
- chat: the chat in which the channel post was originally sent
(instance of
-
@
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.
- chat: the chat in which the channel post was originally sent
(instance of
-
@
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.
- poll: the poll that has just changed state
(instance of
-
@
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 ofbotogram.Chat
) - A
message
parameter with the representation of the received message (an instance ofbotogram.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 thehidden
argument toTrue
.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.- A
-
@
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.
- query: the received
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
.
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: 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: 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: 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: 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.MessageChanged 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: 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: 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: 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 thecommand()
decorator or theadd_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
-