Message Presentation & Inline Keyboards

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

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"),
        ]),
    ]
)

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.

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,
            ),
        ]),
    ]
)

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.

Parameter	Type	Default	Description
`prompt`	`str`	required	The question text, rendered as the first text block.
`options`	`List[Any]`	required	Choices as `(label, value)` tuples or plain strings (used as both label and value). Each becomes a `reply`-action button.
`context`	`Optional[str]`	`None`	Optional smaller context line rendered under the prompt via `make_context`.

context= produces a smaller contextual line under the prompt. On channels that don’t render reply natively (e.g. Telegram), the reply degrades to callback:reply:<value>. When the payload would exceed the 64-byte channel cap the framework persists the value under a short reference and emits reply:@<ref>; the registry resolves it back to the exact value on click. Without a store (custom adapters that opt out) it falls back to reply:#<sha1[:16]> — distinct choices stay distinct but the original value cannot be recovered.

Which builder to pick

User interaction flow

Block Types

Block type	Method	Description
`text`	`PresentationBlock.make_text(content)`	Plain or markdown text
`buttons`	`PresentationBlock.make_buttons(items)`	Row of clickable buttons
`quick_replies`	`PresentationBlock.quick_replies(choices)`	Shortcut for reply-action buttons
`select`	`PresentationBlock.make_select(options)`	Dropdown menu (degraded to buttons on Telegram)
`divider`	`PresentationBlock.make_divider()`	Visual separator
`context`	`PresentationBlock.make_context(content)`	Smaller contextual text
`table`	`PresentationBlock.make_table(columns, rows)`	Tabular data — native table or markdown degrade (Table & Chart Blocks)
`chart`	`PresentationBlock.make_chart(chart_kind, series)`	Chart/visualisation — native chart or text-summary degrade (Table & Chart Blocks)

MessagePresentation.question(prompt, options, context=None) is the one-line shortcut for “prompt + optional context + options” — it composes the text, context, and quick_replies blocks above for you.

Action Types

Action	Factory	Description
`callback`	`PresentationAction.callback(value)`	Opaque callback data for your handler
`reply`	`PresentationAction.reply(value)`	Feed value back as next agent input
`command`	`PresentationAction.command("/cmd")`	Trigger a slash command
`url`	`PresentationAction.open_url(url)`	Open a URL
`web_app`	`PresentationAction(type="web_app", web_app_url=url)`	Open a mini-app (Telegram only)

Platform Support & Limits

Platform	Presentation support	Notes
Telegram	✅ Native inline keyboard	Wired in PR #2483
Slack	🔜 Planned	Falls back to plain text
Discord	🔜 Planned	Falls back to plain text
WhatsApp	✅ Native interactive (reply buttons + list messages)	Delivered via Cloud API `interactive` payloads (`button` / `list`) — see Bot Presentations

Telegram Limits

Limit	Value
`max_buttons` per row/message	8
`max_button_rows`	100
`max_button_label`	64 characters
`callback_data`	64 UTF-8 bytes
`max_text_length`	4096 characters
Native select menu	❌ (degraded to buttons)
Web app (`web_app_url`)	✅

Callback data is capped at 64 UTF-8 bytes (Telegram platform limit). callback_data values that exceed this are truncated at the UTF-8 byte boundary. For non-ASCII payloads this means fewer than 64 characters may be kept. Use short, ASCII-safe identifiers as callback values.

WhatsApp Limits

Limit	Value
`max_buttons` (list rows)	10
Reply buttons per message	3
`max_button_rows`	1
`max_button_label` (list row)	24 characters
Reply-button title	20 characters
`max_options` (list rows)	10
`max_option_label`	24 characters
`max_text_length` (text / list body)	4096 characters
Reply-button message body	1024 characters
Reply / list-row `id`	256 characters
Native select menu	✅ (rendered as a list message)
Markdown	❌
Web app (`web_app_url`)	❌ (degraded via `adapt_presentation`)

WhatsApp uses split caps: reply-button titles are capped at 20 chars while list-row titles allow 24. Reply-button message bodies cap at 1024 chars (vs 4096 for text and list bodies). Every reply/list-row id is capped at 256 chars (Cloud API limit).

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

Use reply actions for simple choices

PresentationAction.reply(value) feeds the chosen value back directly as the user’s next message — your agent sees it as normal input without needing any callback handler.

Use MessagePresentation.question(...) for a one-line clarification

Reach for question(...) when you want a prompt, optional context, and options in a single call. Compose blocks manually (make_text + quick_replies + …) only when you also need dividers, extra text blocks, or mixed action types.

Keep callback values short and ASCII

On Telegram this is now a performance / clarity recommendation, not a correctness one — long values still work, they simply take a store round-trip via the callback payload store. Telegram’s 64-byte callback cap is measured in UTF-8 bytes, so compact IDs (e.g. "approve:42") stay inline and skip the extra hop.

Presentations are cleared after each turn

The captured presentation is popped after chat() in both streaming and non-streaming paths, so cancelling or returning never leaves stale buttons visible.

Test with adapt_presentation()

Call adapt_presentation(presentation, PresentationLimits.telegram()) before sending to preview which buttons survive the Telegram limit and how select menus are degraded. Use PresentationLimits.whatsapp(), .slack(), or .discord() to preview the other channels.

Approval Secure Backend

Durable approval buttons with actor authorisation

Bot Presentations

Overview of bot presentation capabilities

Interactive Bot Actions

Handling button taps and callbacks

Channel Capabilities

What each platform can render

Table & Chart Blocks

Portable table and chart blocks with per-channel rendering

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Message Presentation & Inline Keyboards

Quick Start

How It Works

One-Line Question Builder

Which builder to pick

User interaction flow

Block Types

Action Types

Platform Support & Limits

Telegram Limits

WhatsApp Limits

Button Priorities

Best Practices

Approval Secure Backend

Bot Presentations

Interactive Bot Actions

Channel Capabilities

Table & Chart Blocks

​Quick Start

​How It Works

​One-Line Question Builder

​Which builder to pick

​User interaction flow

​Block Types

​Action Types

​Platform Support & Limits

​Telegram Limits

​WhatsApp Limits

​Button Priorities

​Best Practices

​Related

Approval Secure Backend

Bot Presentations

Interactive Bot Actions

Channel Capabilities

Table & Chart Blocks

Quick Start

How It Works

One-Line Question Builder

Which builder to pick

User interaction flow

Block Types

Action Types

Platform Support & Limits

Telegram Limits

WhatsApp Limits

Button Priorities

Best Practices

Related