Skip to main content
Gateway agents are automatically told where a message came from and which channels they can deliver to — no extra code required.

​
Quick Start

1

Basic Bot (Platform Awareness On by Default)

from praisonai.bots import TelegramBot
from praisonaiagents import Agent

agent = Agent(
    name="gateway",
    instructions="Help users across platforms.",
)

bot = TelegramBot(
    token="your-telegram-token",
    agent=agent,
)

import asyncio
asyncio.run(bot.start())
The agent’s system prompt automatically includes:
  • Which platform the message came from
  • What chat type (DM, group, channel)
  • Which channels it can reach
2

With Channel Directory (Cross-Platform Delivery)

Configure named aliases so the agent can deliver to other platforms by friendly name:
from praisonai.bots import TelegramBot
from praisonai.bots.delivery import ChannelDirectory
from praisonaiagents import Agent

agent = Agent(
    name="gateway",
    instructions="Help users and post summaries to Slack when asked.",
)

directory = ChannelDirectory()
directory.set_home_channel("slack", "C0123456")
directory.add_alias("team", "slack", "C0123456")
directory.add_alias("ops", "discord", "987654321")

bot = TelegramBot(
    token="your-telegram-token",
    agent=agent,
    channel_directory=directory,
)

import asyncio
asyncio.run(bot.start())
The agent now sees in its system prompt:
## Session Context
You are replying on telegram (group "Project Alpha") in thread 123.
Reachable delivery targets: slack:home (slack, home channel), team (slack:C0123456), ops (discord:987654321).

​
How It Works

Each incoming message triggers a per-turn context injection into the agent’s system prompt.
StepWhat Happens
Origin detectiondetect_chat_type(platform, chat_id) classifies the chat as "group", "direct", "channel", or "unknown"
Target listingChannelDirectory.describe_targets() lists home channels and named aliases
Prompt injectionA ## Session Context block is appended to the system prompt for this turn only
Agent respondsThe agent uses the context to make decisions (e.g. reply here vs. post there)
Prompt injection happens after the system prompt is cached. The per-turn ## Session Context block is never stored in the cache — this keeps the cache valid across turns while still giving the agent fresh context every time.

​
Configuration Options

​
Origin

Describes where the incoming message came from. Populated automatically by the bot runtime.
OptionTypeDefaultDescription
platformstr""Platform name ("telegram", "discord", "slack", "whatsapp", …)
chat_typestr"""group", "direct", "channel", or "unknown"
display_namestr""Channel name, group name, or user name
thread_idstr""Thread / topic id

​
ReachableTarget

Represents a channel the agent can deliver to. Built from the ChannelDirectory.
OptionTypeDefaultDescription
namestr—Friendly name or alias
platformstr—Target platform
channel_idstr—Platform channel id
kindstr"alias""home" or "alias"

​
BotSessionManager Parameters

OptionTypeDefaultDescription
channel_directoryOptional[ChannelDirectory]NoneDirectory of reachable channels; if set, describe_targets() populates reachable_targets
inject_session_contextboolTrueWhen False, suppress per-turn prompt injection (origin + targets are still passed to tools)

​
Chat-Type Detection

detect_chat_type(platform, chat_id) returns a string classifying the chat context. Used to fill Origin.chat_type.
PlatformPatternReturned Type
telegramchat_id starts with -100"unknown" (supergroup/channel ambiguous)
telegramchat_id starts with -"group"
telegramotherwise"direct"
discordany"channel"
slackstarts with C"channel"
slackstarts with G"group"
slackstarts with D or U"direct"
whatsappcontains @g.us"group"
whatsappcontains @c.us"direct"
anything else—"unknown"

​
Choosing Your Setup

​
Common Patterns

​
Cross-Platform Delivery via Natural Language

The agent can deliver to another platform when the user says “post this to Slack”: 
from praisonai.bots import TelegramBot
from praisonai.bots.delivery import ChannelDirectory
from praisonaiagents import Agent

directory = ChannelDirectory()
directory.set_home_channel("slack", "C0123456")
directory.add_alias("team", "slack", "C0123456")

agent = Agent(
    name="cross-platform",
    instructions="""
    Help users. When asked to post somewhere, use the delivery targets listed
    in your Session Context. Targets are available by their friendly names.
    """,
)

bot = TelegramBot(
    token="your-telegram-token",
    agent=agent,
    channel_directory=directory,
)

​
Referring to “Here”

The agent knows what “here” means because Origin includes the current platform and chat type: 
agent = Agent(
    name="location-aware",
    instructions="""
    You know which platform you are on and whether you are in a DM or group.
    When users say 'post it here', use the current platform and chat from your
    Session Context.
    """,
)

​
Disabling Injection for Privacy

Keep context away from the agent’s visible system prompt (it still flows to tools via get_session_context()): 
bot = TelegramBot(
    token="your-telegram-token",
    agent=agent,
    inject_session_context=False,
)

​
Best Practices

The ## Session Context block is injected after the system prompt cache boundary. Changing the origin or reachable targets never invalidates the cache for previous turns — each turn gets a fresh block without paying a re-cache penalty.
Prefer short, descriptive names like "team", "ops", or "alerts" over raw channel IDs like "C0123456". The model matches user intent to alias names — the closer the alias is to how users talk, the more reliably it routes.
Set inject_session_context=False when you don’t want the agent to see platform metadata in its system prompt. The context is still available to tools via get_session_context() — only the visible prompt block is suppressed.
set_home_channel(platform, channel_id) designates the default delivery target for a platform. Agents can refer to it as "<platform>:home". Add aliases for any additional channels that need friendly names.

Cross-Platform Sessions

Unified conversation history across platforms — same human, one history.

Channels Gateway

Connect agents to Telegram, Discord, Slack, and WhatsApp.

Bot Message Routing

Route messages from DMs, groups, and channels to different agents.

Messaging Bots

Deploy AI agents to messaging platforms.