Inbound Platform Events

Receive reactions, edits, deletions, member changes, and thread creations from bot platforms

Inbound platform events let your agent hear more than text — reactions, edits, deletions, member changes, and thread creations from Discord, Telegram, Slack, and other supported platforms.

Quick Start

Register a hook on the agent, then opt the channel in from the gateway config.

from praisonaiagents import Agent
from praisonaiagents.hooks import add_hook, HookEvent

@add_hook(HookEvent.REACTION_RECEIVED)
def on_reaction(evt):
    if evt.emoji == "✅" and evt.kind == "reaction_added":
        print(f"{evt.user_id} approved message {evt.message_id}")

agent = Agent(name="ApprovalBot", instructions="Approve requests reacted to with ✅.")
agent.start("Approve incoming requests when a teammate reacts with ✅.")

# gateway.yaml — opt in per channel
channels:
  my-discord-bot:
    platform: discord
    token: "${DISCORD_BOT_TOKEN}"
    events: [reactions]      # NEW — opt in to inbound reactions

Opt-In Classes

1. reactions

   Hear when a user adds or removes a reaction. Branch on evt.kind to tell add from remove.

   channels:
     my-discord-bot:
       platform: discord
       token: "${DISCORD_BOT_TOKEN}"
       events: [reactions]

   from praisonaiagents.hooks import add_hook, HookEvent
   
   @add_hook(HookEvent.REACTION_RECEIVED)
   def on_reaction(evt):
       if evt.kind == "reaction_added":
           print(f"{evt.user_id} added {evt.emoji} to {evt.message_id}")
       else:
           print(f"{evt.user_id} removed {evt.emoji} from {evt.message_id}")

2. edits

   Hear message edits and deletions.

   channels:
     my-discord-bot:
       platform: discord
       token: "${DISCORD_BOT_TOKEN}"
       events: [edits]

   from praisonaiagents.hooks import add_hook, HookEvent
   
   @add_hook(HookEvent.MESSAGE_EDITED)
   def on_edit(evt):
       print(f"{evt.message_id} is now: {evt.new_text}")
   
   @add_hook(HookEvent.MESSAGE_DELETED)
   def on_delete(evt):
       print(f"{evt.user_id} deleted {evt.message_id}")

3. members

   Hear when a user joins or leaves. Requires the privileged members gateway intent, which the adapter enables only when you request this class.

   channels:
     my-discord-bot:
       platform: discord
       token: "${DISCORD_BOT_TOKEN}"
       events: [members]

   from praisonaiagents.hooks import add_hook, HookEvent
   
   @add_hook(HookEvent.MEMBER_JOINED)
   def on_join(evt):
       print(f"Welcome {evt.user_id} to {evt.chat_id}")
   
   @add_hook(HookEvent.MEMBER_LEFT)
   def on_leave(evt):
       print(f"{evt.user_id} left {evt.chat_id}")

4. threads

   Hear when a new thread is created. thread_id and the parent chat_id are populated.

   channels:
     my-discord-bot:
       platform: discord
       token: "${DISCORD_BOT_TOKEN}"
       events: [threads]

   from praisonaiagents.hooks import add_hook, HookEvent
   
   @add_hook(HookEvent.THREAD_CREATED)
   def on_thread(evt):
       print(f"New thread {evt.thread_id} in {evt.chat_id}")

How It Works

A native platform event is normalised into a portable PlatformEvent, which fires the matching HookEvent.

Every adapter emits through one DRY seam, fire_platform_event, which maps PlatformEvent.kind onto the matching HookEvent. Reaction add and remove both fire REACTION_RECEIVED — the kind field disambiguates.

Which Event Fires When?

Pick the class that matches what you want to hear.

Configuration Options

Each class token subscribes the adapter to a set of native handlers.

Hook Payload (PlatformEventInput)

Every inbound event carries a PlatformEventInput.

Import it directly when you need the type:

from praisonaiagents.hooks import PlatformEventInput
from praisonaiagents.bots import PlatformEvent, PlatformEventKind

Platform Coverage

Only Discord is wired today. Other adapters translate their native events into the same PlatformEvent in follow-up releases.

Common Patterns

Reaction-as-approval — react ✅ to approve, no typing required.

from praisonaiagents.hooks import add_hook, HookEvent

@add_hook(HookEvent.REACTION_RECEIVED)
def approve(evt):
    if evt.emoji == "✅" and evt.kind == "reaction_added":
        print(f"Approved {evt.message_id} by {evt.user_id}")

Undo-on-delete — retract a stored plan when the source message disappears.

from praisonaiagents.hooks import add_hook, HookEvent

@add_hook(HookEvent.MESSAGE_DELETED)
def undo(evt):
    print(f"Clearing follow-ups tied to {evt.message_id}")

Welcome-on-join — greet new members.

from praisonaiagents.hooks import add_hook, HookEvent

@add_hook(HookEvent.MEMBER_JOINED)
def welcome(evt):
    print(f"Sending welcome to {evt.user_id} in {evt.chat_id}")

Thread-scoped session — open a new agent session tied to a thread.

from praisonaiagents.hooks import add_hook, HookEvent

@add_hook(HookEvent.THREAD_CREATED)
def open_session(evt):
    print(f"Starting a session for thread {evt.thread_id}")

Best Practices

Related