Real-Time Push Notifications

Channel-based pub/sub over WebSocket with HTTP polling fallback

Subscribe to gateway channels and receive real-time messages — WebSocket first, polling when blocked.

from praisonaiagents import Agent
from praisonaiagents.push import PushClient

agent = Agent(
    name="alerts-agent",
    instructions="Summarise incoming alert events in one sentence",
)

client = PushClient("ws://localhost:8765/ws", auth_token="my-token")
await client.connect()

@client.on("channel_message")
async def on_msg(msg):
    print(agent.start(f"Summarise: {msg.data}"))

await client.subscribe("alerts")
await client.wait_closed()

The user subscribes to a channel; push events arrive over WebSocket and the agent summarises each message.

PushClient ships in the praisonai wrapper (pip install praisonai). Core praisonaiagents.push exports protocols and ChannelMessage only.

How It Works

Quick Start

1. Simple Usage

   Connect and subscribe:

   from praisonaiagents.push import PushClient
   
   client = PushClient("ws://localhost:8765/ws", auth_token="my-token")
   await client.connect()
   
   @client.on("channel_message")
   async def on_message(msg):
       print(f"{msg.channel}: {msg.data}")
   
   await client.subscribe("alerts")
   await client.wait_closed()
   
2. With Configuration

   Enable push on the gateway:

   from praisonaiagents import GatewayConfig
   from praisonaiagents.gateway import PushConfig
   
   config = GatewayConfig(push=PushConfig(enabled=True))
   

---

How It Works

Component	Purpose
PushClient	Auto-reconnect, transport fallback
WebSocketTransport	Primary real-time transport
PollingTransport	Fallback for restricted networks
Channels	Named pub/sub streams
PushConfig	Opt-in gateway toggle (off by default)

Import paths:

from praisonai.push import PushClient                    # wrapper (recommended)
from praisonaiagents.push import PushClient              # lazy re-export
from praisonaiagents.push import ChannelMessage          # core dataclass

---

Configuration Options

PushConfig

Option	Type	Default	Description
enabled	bool	False	Feature toggle
redis	RedisConfig	None	Cross-server scaling
presence	PresenceConfig	PresenceConfig()	Online/offline tracking
delivery	DeliveryConfig	DeliveryConfig()	ACK and retry settings
polling	PollingConfig	PollingConfig()	Long-poll fallback

DeliveryConfig

Option	Type	Default	Description
enabled	bool	True	Delivery guarantees
ack_timeout	int	30	Seconds to wait for ACK
max_retries	int	3	Retry attempts
store_backend	str	"memory"	"memory" or "redis"

---

Best Practices

Enable Redis for multi-server

Without Redis, channels exist on one gateway instance only.

Keep push opt-in

PushConfig(enabled=False) adds zero overhead — enable only when clients subscribe.

Use polling fallback on corporate networks

Set fallback_to_polling=True on PushClient when WebSocket is blocked.

Separate from A2A webhooks

Real-time channels differ from A2A task webhooks — use the right page for your pattern.

---

Related

Gateway

Host push channels on the gateway

A2A Push Notifications

Webhook-based task updates