Skip to main content
The gateway now ships in the praisonai-bot package. praisonai serve gateway still works exactly as documented here; for a standalone install see praisonai-bot Migration.
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
# Relay transport carries user messages to the gateway-backed agent
agent.start("Hello via relay")
Relay transport lets a Bot connect to messaging platforms through an outbound WebSocket relay — no public webhook URL required. The user connects through a relay; messages traverse the relay transport to reach the gateway and agent.

​
Quick Start

1

Start the relay server

Run the gateway relay CLI to bridge between the platform and your bot:
praisonai gateway relay --platform telegram --to wss://gw.internal/relay
2

Connect your bot via relay

Pass a transport= argument when creating a Bot:
import os
from praisonaiagents import Agent
from praisonai.bots import TelegramBot
from praisonai.bots.relay import RelayAdapter

agent = Agent(
    name="MyBot",
    instructions="Help users with their questions.",
)

relay = RelayAdapter(url="wss://gw.internal/relay")

bot = TelegramBot(
    token=os.getenv("TELEGRAM_BOT_TOKEN"),
    agent=agent,
    transport=relay,
)

bot.run()
3

Scale to zero with go_dormant()

When idle, call go_dormant() to release the relay connection and stop consuming resources:
import asyncio
from praisonaiagents import Agent
from praisonai.bots import TelegramBot
from praisonai.bots.relay import RelayAdapter

agent = Agent(name="DormantBot", instructions="Respond to messages.")
relay = RelayAdapter(url="wss://gw.internal/relay")
bot = TelegramBot(token=os.getenv("TELEGRAM_BOT_TOKEN"), agent=agent, transport=relay)

async def main():
    await bot.start()
    # After a period of inactivity:
    await bot.go_dormant()

asyncio.run(main())

​
How It Works

The RelayAdapter maintains a persistent outbound WebSocket connection to the relay gateway. Platform messages arrive through that channel instead of requiring an inbound webhook. Because the connection is outbound-only, the bot runs behind NAT or in a private network with no firewall rules.

​
When to Use Relay Transport

ScenarioRecommended approach
Public cloud with static IPStandard webhook
Private network / NATRelayAdapter
Ephemeral compute (Fly.io, serverless)RelayAdapter + go_dormant()
Multi-region bot fleetRelayAdapter (one relay per region)

​
Configuration

​
RelayAdapter

ParameterTypeDefaultDescription
urlstr(required)WebSocket URL of the relay gateway
reconnect_intervalfloat5.0Seconds between reconnect attempts
max_reconnectsint0Max reconnect attempts (0 = unlimited)

​
Bot(transport=...)

from praisonai.bots.relay import RelayAdapter

relay = RelayAdapter(
    url="wss://gw.internal/relay",
    reconnect_interval=3.0,
)

bot = TelegramBot(token=token, agent=agent, transport=relay)

​
CLI

praisonai gateway relay --platform <platform> --to <relay-url>
FlagDescription
--platformPlatform adapter to use (telegram, slack, discord, …)
--toWebSocket URL of the relay gateway

​
go_dormant()

go_dormant() disconnects the relay transport cleanly when the bot is idle, enabling scale-to-zero hosting. The bot wakes up automatically when a new message arrives and the transport reconnects. 
async def on_idle():
    await bot.go_dormant()
    # Bot releases WebSocket connection; reconnects on next inbound
See Gateway Scale-to-Zero for configuring the full idle policy.

​
Best Practices

The relay URL is an internal control plane endpoint. Do not expose it publicly — it should only be reachable from your bot’s network.
The default 5-second reconnect is suitable for most bots. Reduce it if you need sub-second reconnection; increase it on flaky networks to avoid reconnect storms.
On reconnect the relay may miss messages. Enable Durable Delivery so the outbound outbox survives relay disconnections.
Call go_dormant() only after all in-flight agent turns complete. The relay closes the WebSocket, so any in-progress sends will fail if the turn is still running.

Gateway Scale-to-Zero

Full idle policy and wake URL configuration

Bot Gateway

Core bot gateway concepts

Durable Delivery

Crash-safe outbound message delivery

Gateway CLI

All praisonai gateway subcommands