Buttons and callbacks API

This page contains the documentation for the APIs related to buttons and callbacks. See the narrative chapter about them for more information about them.

class botogram.Buttons

This class allows you to build buttons to attach to messages. You must use it as a list, accessing the various rows with the square brackets.

Each element of this simulated list is automatically created the first time you access it, and it’s an instance of ButtonsRow: you can use that object to actually populate the buttons. Check out that class’ documentation for all the buttons you can add.

Then, you can send the buttons by attaching them to an outgoing message, as shown in the example below. You can also reuse the same instance for multiple messages.

@bot.command("example")
def example_command(chat, message, args):
    """Show some example sites"""
    btns = botogram.Buttons()
    btns[0].url("Visit example.com", "http://www.example.com")
    btns[1].url("example.net", "http://www.example.net")
    btns[1].url("example.org", "http://www.example.org")

    chat.send("Check out some example sites!", attach=btns)

New in version 0.4.

class botogram.ButtonsRow

This class represents a row in a set of buttons: you can use it to add the individual buttons to it. You should not create an instance of this class directly, but you should get them through the Buttons class.

New in version 0.4.

callback(label, callback[, data=None])

Add a new button to the row, which will call the corresponding callback when pressed by the user. You need to provide the label of the button, the name of the callback and an optional string of data, which will be passed to the callback.

Due to limitations in the Telegram Bot API, you can provide in the data argument a maximum of 32 bytes of text: an exception will be raised if you provide more.

The information contained in the callback will automatically be signed by botogram, to prevent tampering, but the data is not encrypted: an user with a special client might be able to see it, without being able to change it. See the security section for more details.

btns = botogram.Buttons()
btns[0].callback("Commit changes", "commit")
btns[0].callback("Checkout master", "checkout", "master")
Parameters:
  • label (str) – The label of the button shown to the user
  • callback (str) – The internal name of the callback
  • data (str) – Extra data provided to the callback (max 32 bytes)
url(label, url)

Add a new button to the row, which will ask the user if they want to open the URL you provided. If they agree, the url will be opened in the user’s browser. You need to provide the label of the button and the URL.

btns = botogram.Buttons()
btns[0].url("See example.com", "http://www.example.com")
Parameters:
  • label (str) – The label of the button shown to the user
  • url (str) – The URL the user should open when the button is pressed
switch_inline_query(label[, query="", current_chat=False])

Add a new button to the row, which will switch the user to the inline query mode of the bot. You need to provide the label of the button, and optionally the query that should be prefilled in the user’s search field.

If current_chat is False, the user will be asked in which chat the inline query should be opened. If you set it to True, the inline query will be opened in the current chat.

btns = botogram.Buttons()
btns[0].switch_inline_query("Show pictures of cats to your friends!", "cats")
Parameters:
  • label (str) – The label of the button shown to the user
  • query (str) – Default query provided to the user
  • current_chat (bool) – Open in the current chat instead of asking the user to select one
class botogram.CallbackQuery

This class represents a callback query received from Telegram. It contains all the information you need about it, and allows you to respond to it.

New in version 0.4.

id

The unique ID of this callback query. You might need to use it if you interact with the Bot API directly.

sender

The User who sent the query.

message

The Message with the button that originated the callback.

chat_instance

An unique string identifying the chat where the message with the button that called the callback is.

inline_message_id

An unique string identifying the inline message with the button that originated the callback.

This attribute can be None if it’s not provided by Telegram.

game_short_name

The short name of the Telegram Game that the user requested to play.

This attribute can be None if it’s not provided by Telegram.

notify(text[, alert=False, cache=0])

Send a notification to the user that pressed the button originating the callback. You need to provide the text of the notification and, optionally, for how long the action will be cached by the client.

If alert is True, the user will be shown an alert window with the message. Otherwise, the message will be displayed as the client likes, for example as a toast.

@bot.callback("say-hi")
def say_hi_callback(query):
   query.notify("Hi " + query.sender.name + "!")
Parameters:
  • text (str) – The content of the notification
  • alert (bool) – Show the notification as an alert to the user
  • cache (int) – How long the client should cache the response
open_url(url[, cache=0])

Tell the user’s client to open an URL in the browser. This action is currently restricted only to the bots that agreed the Telegram Games Terms of Service: check out the Telegram documentation for more information about games.

You need to provide the URL of the page, and optionally how long you want the client to cache the action.

@bot.callback("open-game")
def open_game(query):
    query.open_url("http://game.example.com")
Parameters:
  • url (str) – The URL you want the user to open
  • cache (int) – How long the client should cache the response
open_private_chat(start_arg[, cache=0])

Tell the user’s client to open a private chat with the bot, and to switch to it. You need to provide a non-empty start argument, which will be appended to the /start command the client will send (but it won’t be displayed to the user). Optionally, you can provide how long you want the client to cache the action.

@bot.open("show-help")
def show_help(query):
    query.open_private_chat("show-help-to-the-user")

@bot.command("start")
def start_command(chat, message, args):
    if len(args) == 1 and args[0] == "show-help-to-the-user":
        chat.send("This is the help message of the bot.")
    else:
        chat.send("Hi! I'm a bot")
Parameters:
  • start_arg (str) – The argument to provide to /start
  • cache (int) – How long the client should cache the response