Interactive Bot Actions

Wire button and select-menu clicks to your own handlers across Telegram, Discord, and Slack

Bots can wire button clicks and select-menu choices to your own async handlers — across Telegram, Discord, and Slack — through a small registry API.

from praisonaiagents import Agent
from praisonai.bots import Bot

agent = Agent(name="ShopBot", instructions="Help customers order")
bot = Bot("telegram", agent=agent)

The user taps a button or menu in chat; your registered handler runs and the bot replies.

Quick Start

1. Use a built-in slash-command button (zero config)

   Buttons wired to slash commands fire automatically — no handler registration needed.

   import os
   import asyncio
   from praisonaiagents import Agent
   from praisonaiagents.bots import (
       PresentationButton,
       PresentationAction,
       ActionType,
       MessagePresentation,
       PresentationBlock,
   )
   from praisonai.bots import TelegramBot
   
   agent = Agent(
       name="assistant",
       instructions="You are a helpful assistant. When asked for help, show a help button.",
   )
   
   bot = TelegramBot(
       token=os.environ["TELEGRAM_BOT_TOKEN"],
       agent=agent,
   )
   
   help_button = PresentationButton(
       label="📚 Get Help",
       action=PresentationAction(type=ActionType.COMMAND, command="help"),
   )
   
   asyncio.run(bot.start())

   When the user taps Get Help, the existing /help handler fires automatically via the built-in command namespace.

2. Register a custom namespace handler

   For your own button logic, create a registry and register an async handler.

   import os
   import asyncio
   from praisonaiagents import Agent
   from praisonaiagents.bots import (
       InteractiveContext,
       create_registry,
       encode_action,
       PresentationAction,
       PresentationButton,
       ActionType,
   )
   from praisonai.bots import TelegramBot
   
   agent = Agent(
       name="assistant",
       instructions="You are a helpful assistant.",
   )
   
   registry = create_registry()
   
   async def on_approval(ctx: InteractiveContext) -> str | None:
       payload = ctx.platform_data.get("decoded_payload", {})
       choice = payload.get("value")
       if choice == "yes":
           return "approved"
       elif choice == "no":
           return "denied"
       return None
   
   registry.register("approval", on_approval)
   
   approve_button = PresentationButton(
       label="✅ Approve",
       action=PresentationAction(type=ActionType.CALLBACK, value="yes"),
   )
   deny_button = PresentationButton(
       label="❌ Deny",
       action=PresentationAction(type=ActionType.CALLBACK, value="no"),
   )
   
   approve_callback = encode_action("approval", approve_button.action)
   deny_callback = encode_action("approval", deny_button.action)
   
   bot = TelegramBot(
       token=os.environ["TELEGRAM_BOT_TOKEN"],
       agent=agent,
   )
   
   asyncio.run(bot.start())

   encode_action("approval", ...) produces "approval:yes" / "approval:no". When a user taps the button, registry.dispatch() routes the click to on_approval.

How It Works

Decoding Rules

decode_callback(data) maps raw callback_data to a (namespace, payload) tuple:

After dispatch(), the registry also writes decoded_namespace and decoded_payload into ctx.platform_data before calling your handler.

Choosing a Namespace Style

Durable callback payload store

When a reply / select value overflows the channel’s inline-callback byte-cap (Telegram’s 64 UTF-8 bytes), the framework persists it under a short reference so the exact value round-trips back to your handler.

TelegramBot wires this for you — it shares one store between its renderer and the inbound registry. To do it yourself, pass a store to create_registry:

from praisonaiagents.bots import create_registry, InMemoryCallbackPayloadStore

store = InMemoryCallbackPayloadStore()
registry = create_registry(store=store)

Without a store, overflowing values fall back to the lossy reply:#<sha1[:16]> hash and the handler is skipped. See Interactive Callback Payload Store for the full flow, configuration, and custom backends.

Handling poll results

A poll block collects a group vote; its aggregated tally comes back through the same registry under the reserved poll namespace. Register make_poll_result_handler and read the typed PollResult:

from praisonaiagents.bots import (
    create_registry,
    make_poll_result_handler,
    POLL_NAMESPACE,
)

async def on_result(result, context):
    if result.winner() is None:
        return "It's a tie — I'll pick one at random."
    return f"Booking {result.winner()}."

registry = create_registry()
registry.register(POLL_NAMESPACE, make_poll_result_handler(on_result))

The handler reads context.platform_data["poll_result"] (accepting a PollResult or its dict form) and forwards it to on_result. See Poll Blocks for authoring polls and the full PollResult API.

Platform-Specific Context

Each adapter populates ctx.platform_data with native objects so you can access full platform functionality inside your handler.

async def my_handler(ctx: InteractiveContext) -> str | None:
    query = ctx.platform_data["query"]
    await query.answer("Processing...")
    return "handled"

async def my_handler(ctx: InteractiveContext) -> str | None:
    interaction = ctx.platform_data["interaction"]
    await interaction.edit_original_response(content="Done!")
    return "handled"

async def my_handler(ctx: InteractiveContext) -> str | None:
    body = ctx.platform_data["body"]
    action = ctx.platform_data["action"]
    channel = body.get("channel", {}).get("id")
    return "handled"

Common Patterns

import os
import asyncio
from praisonaiagents import Agent
from praisonaiagents.bots import (
    PresentationButton,
    PresentationAction,
    ActionType,
)
from praisonai.bots import SlackBot

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
)

status_button = PresentationButton(
    label="📊 Check Status",
    action=PresentationAction(type=ActionType.COMMAND, command="status"),
)

bot = SlackBot(
    token=os.environ["SLACK_BOT_TOKEN"],
    app_token=os.environ["SLACK_APP_TOKEN"],
    agent=agent,
)

asyncio.run(bot.start())

import os
import asyncio
from praisonaiagents import Agent
from praisonaiagents.bots import (
    InteractiveContext,
    create_registry,
    encode_action,
    PresentationAction,
    ActionType,
)
from praisonai.bots import DiscordBot

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
)

registry = create_registry()

async def on_vote(ctx: InteractiveContext) -> str | None:
    choice = ctx.platform_data.get("decoded_payload", {}).get("value")
    user = ctx.user_id
    if choice == "yes":
        return f"vote:yes:{user}"
    return f"vote:no:{user}"

registry.register("vote", on_vote)

yes_callback = encode_action("vote", PresentationAction(type=ActionType.CALLBACK, value="yes"))
no_callback = encode_action("vote", PresentationAction(type=ActionType.CALLBACK, value="no"))

bot = DiscordBot(
    token=os.environ["DISCORD_BOT_TOKEN"],
    agent=agent,
)

asyncio.run(bot.start())

import os
import asyncio
from praisonaiagents import Agent
from praisonaiagents.bots import (
    InteractiveContext,
    create_registry,
    encode_action,
    PresentationAction,
    ActionType,
)
from praisonai.bots import TelegramBot

agent = Agent(
    name="assistant",
    instructions="You are a menu-driven assistant.",
)

registry = create_registry()

async def on_menu(ctx: InteractiveContext) -> str | None:
    choice = ctx.platform_data.get("decoded_payload", {}).get("value", "")
    if choice == "report":
        return "menu:report"
    elif choice == "settings":
        return "menu:settings"
    elif choice == "help":
        return "menu:help"
    return None

registry.register("menu", on_menu)

report_cb = encode_action("menu", PresentationAction(type=ActionType.CALLBACK, value="report"))
settings_cb = encode_action("menu", PresentationAction(type=ActionType.CALLBACK, value="settings"))
help_cb = encode_action("menu", PresentationAction(type=ActionType.CALLBACK, value="help"))

bot = TelegramBot(
    token=os.environ["TELEGRAM_BOT_TOKEN"],
    agent=agent,
)

asyncio.run(bot.start())

API Reference

InteractiveContext

Passed to every handler by the registry’s dispatch() method.

After dispatch(), platform_data also contains:

• decoded_namespace — the decoded namespace string
• decoded_payload — the decoded payload dict

InteractiveHandler

InteractiveHandler = Callable[[InteractiveContext], Awaitable[Optional[str]]]

Return a non-None string to mark the click as handled (stops the chain). Return None to fall through to the fallback handler.

InteractiveRegistry

Functions

Built-in Namespaces

Every platform adapter (Telegram, Discord, Slack) registers these automatically:

Best Practices

from praisonaiagents.bots import create_registry

registry = create_registry()
registry.register("approval", on_approval)

export PRAISONAI_CALLBACK_SECRET="$(openssl rand -hex 32)"

async def on_menu(ctx: InteractiveContext) -> str | None:
    choice = ctx.platform_data.get("decoded_payload", {}).get("value", "")
    if choice in ("report", "settings"):
        return f"menu:{choice}"
    return None

async def on_approval(ctx: InteractiveContext) -> str | None:
    try:
        result = await process_approval(ctx)
        return result
    except Exception as e:
        query = ctx.platform_data.get("query")
        if query:
            await query.answer(f"Error: {e}")
        return "error"

Related