Message Presentation & Inline Keyboards

Attach buttons, menus, and web-app links to agent replies; each platform renders them as native interactive widgets

Agents can return a MessagePresentation alongside their reply text — Telegram renders it as a native inline keyboard; other platforms fall back to plain text until their renderer is wired.

from praisonaiagents import Agent

agent = Agent(
    name="Survey Bot",
    instructions="Ask one multiple-choice question and attach button choices.",
)
agent.start("Which topic should we cover next: memory, tools, or workflows?")

The user receives a reply with inline buttons; their tap sends the choice back as the next message.

Quick Start

1. Quick-Reply Buttons

   The simplest way to add buttons — each tapped choice feeds the value back to the agent as the next user message:

   from praisonaiagents import Agent
   from praisonaiagents.bots import MessagePresentation, PresentationBlock
   
   agent = Agent(
       name="Survey Bot",
       instructions="""
       Ask a single multiple-choice question.
       Return your reply as text, then attach a presentation with buttons
       for the choices using PresentationBlock.quick_replies().
       """,
   )
   
   presentation = MessagePresentation(
       blocks=[
           PresentationBlock.make_text("How would you rate your experience?"),
           PresentationBlock.quick_replies([
               ("⭐ Excellent", "excellent"),
               ("👍 Good", "good"),
               ("👎 Poor", "poor"),
           ]),
       ]
   )

2. One-line question builder

   MessagePresentation.question(...) is the shortest way to ask a multi-choice question — prompt, optional context, and option buttons in a single call:

   from praisonaiagents import Agent
   from praisonaiagents.bots import MessagePresentation
   
   presentation = MessagePresentation.question(
       "Which environment should I deploy to?",
       options=[("🧪 Staging", "staging"), ("🚀 Production", "production"), "cancel"],
       context="Deployments run immediately.",
   )

   Each option becomes a reply-action button — a tap sends the chosen value back as the user’s next message, so no callback handler is needed.

3. Inline Keyboard with Callbacks

   Full control over button appearance and callback data:

   from praisonaiagents.bots import (
       MessagePresentation,
       PresentationBlock,
       PresentationButton,
       PresentationAction,
       ButtonStyle,
   )
   
   presentation = MessagePresentation(
       blocks=[
           PresentationBlock.make_text("Choose an action:"),
           PresentationBlock.make_buttons([
               PresentationButton(
                   label="✅ Approve",
                   action=PresentationAction.callback("approve:req-42"),
                   style=ButtonStyle.PRIMARY,
                   priority=10,
               ),
               PresentationButton(
                   label="❌ Deny",
                   action=PresentationAction.callback("deny:req-42"),
                   style=ButtonStyle.DANGER,
                   priority=9,
               ),
               PresentationButton(
                   label="🔗 Open Details",
                   action=PresentationAction.open_url("https://example.com/req/42"),
                   priority=8,
               ),
           ]),
       ]
   )

4. Use with an Agent and Telegram Bot

   import asyncio
   from praisonaiagents import Agent
   from praisonaiagents.bots import (
       MessagePresentation, PresentationBlock, PresentationButton,
       PresentationAction, ButtonStyle,
   )
   from praisonai.bots import TelegramBot
   
   agent = Agent(
       name="Action Bot",
       instructions="Help users take actions.",
   )
   
   bot = TelegramBot(token="YOUR_TOKEN", agent=agent)
   
   presentation = MessagePresentation(
       blocks=[
           PresentationBlock.make_text("What would you like to do?"),
           PresentationBlock.quick_replies([("Start", "start"), ("Help", "help")]),
       ]
   )
   
   async def main():
       await bot.start()
   
   asyncio.run(main())

How It Works

The adapt_presentation() function runs a channel-agnostic adaptation pass before rendering: it truncates buttons to platform limits, degrades select menus to button rows when unsupported, and degrades web_app actions to URLs on channels without mini-app support.

One-Line Question Builder

MessagePresentation.question(prompt, options, context=None) builds a prompt-plus-options presentation in a single call — the symmetric counterpart to MessagePresentation.approval(...) for non-binary “which of these?” clarifications.

from praisonaiagents import Agent
from praisonaiagents.bots import MessagePresentation

presentation = MessagePresentation.question(
    "Which environment should I deploy to?",
    options=[("🧪 Staging", "staging"), ("🚀 Production", "production"), "cancel"],
    context="Deployments run immediately.",
)

It composes a text prompt → optional context → a quick_replies button row. Every option carries PresentationAction.reply(value), so a tap feeds the chosen value straight into the next agent turn — no callback handler required.

Which builder to pick

User interaction flow

Block Types

Action Types

Platform Support & Limits

Telegram Limits

WhatsApp Limits

Button Priorities

When more buttons are defined than the platform limit allows, the adaptation pass keeps the highest-priority buttons and drops the rest:

PresentationButton(label="Critical", action=..., priority=10)  # kept first
PresentationButton(label="Secondary", action=..., priority=5)   # dropped if cap hit
PresentationButton(label="Optional", action=..., priority=1)    # dropped first

Best Practices

Related