Cross-Platform Sessions

Cross-platform sessions let one user keep a single conversation across every messaging platform.

Recommended (with pairing)
Explicit links only

from praisonai.bots import BotOS, StoreBackedIdentityResolver
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")

# Reuses ~/.praisonai/identity.json + the gateway pairing store.
resolver = StoreBackedIdentityResolver.from_env()

BotOS(
    agent=agent,
    platforms=["telegram", "whatsapp", "discord", "slack"],
    identity_resolver=resolver,
).run()

from praisonai.bots import BotOS
from praisonaiagents import Agent
from praisonaiagents.session import FileIdentityResolver

agent = Agent(name="assistant", instructions="Be helpful.")

resolver = FileIdentityResolver()                        # ~/.praisonai/identity.json
resolver.link("telegram", "12345",       "alice")
resolver.link("discord",  "snowflake-1", "alice")

BotOS(
    agent=agent,
    platforms=["telegram", "discord"],
    identity_resolver=resolver,
).run()

The user continues the same conversation on Telegram, then Discord; identity linking mirrors session history across platforms.

How It Works

Quick Start

One platform, one user

from praisonai.bots import Bot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
bot = Bot("telegram", agent=agent)
await bot.start()

Two platforms, one user (recommended)

from praisonai.bots import BotOS, StoreBackedIdentityResolver
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")

resolver = StoreBackedIdentityResolver.from_env()

botos = BotOS(
    agent=agent,
    platforms=["telegram", "discord"],
    identity_resolver=resolver,
)
await botos.start()

In-process testing / ephemeral

from praisonai.bots import BotOS
from praisonaiagents import Agent
from praisonaiagents.session import InMemoryIdentityResolver

agent = Agent(name="assistant", instructions="Be helpful.")

resolver = InMemoryIdentityResolver()  # Ephemeral for tests
resolver.link("telegram", "12345", "alice")
resolver.link("discord", "snowflake-1", "alice")

botos = BotOS(
    agent=agent,
    platforms=["telegram", "discord"],
    identity_resolver=resolver,
)

Choosing Your Resolver

StoreBackedIdentityResolver

StoreBackedIdentityResolver extends the core FileIdentityResolver with a read-through to the gateway pairing store, so users who have already paired share a session out of the box. Resolution order:

Explicit link registered via link() (highest priority)
Pairing-store label for (user_id, platform) when the channel is paired and carries a non-empty label
f"{platform}:{user_id}" — safe per-platform fallback (no merging)

from praisonai.bots import StoreBackedIdentityResolver

# Defaults: ~/.praisonai/identity.json + gateway pairing store
resolver = StoreBackedIdentityResolver.from_env()

# Override paths
resolver = StoreBackedIdentityResolver.from_env(
    path="/etc/praisonai/identity.json",
    store_dir="/var/lib/praisonai/gateway",
)

# Direct construction with an existing pairing store
from praisonai.gateway.pairing import PairingStore
resolver = StoreBackedIdentityResolver(
    path="~/.praisonai/identity.json",
    pairing_store=PairingStore(),
    use_pairing_label=True,   # default
)

link_paired() — Promote Paired Users to Explicit Links

# After channels have been paired with non-empty labels via the pairing CLI:
count = resolver.link_paired()
print(f"Materialised {count} paired channels into explicit links.")

Useful when the pairing store is volatile or about to be rotated — this pins the canonical-id mapping into the resolver’s own JSON file.

If you already use praisonai pairing approve <platform> <code> --label <canonical>, switching to StoreBackedIdentityResolver.from_env() is a one-line upgrade: paired users immediately share one session across all their channels, with no separate praisonai identity link calls required. Run praisonai identity import once to pin those mappings into the explicit link map.

In the gateway (`praisonai gateway start`)

The flagship WebSocketGateway daemon accepts the same resolver, so a paired user keeps one continuous session across every channel served by one gateway process. Wire it three ways — YAML block, CLI flag, or Python override.

YAML (recommended for daemons)
CLI (--identity-store)
Python override (always wins)

# gateway.yaml
identity:
  enabled: true                          # default when block is present
  store: ~/.praisonai/identity.json      # optional link-map path (also accepts `path:`)

agents:
  assistant:
    instructions: "Be helpful."

channels:
  telegram:  { token: "${TELEGRAM_BOT_TOKEN}" }
  discord:   { token: "${DISCORD_BOT_TOKEN}" }

A missing block, a non-mapping block, or enabled: false keeps today’s default — per-platform session keys.
enabled accepts true/false/"1"/"true"/"yes"/"on" (strings coerced case-insensitively).
store is ~-expanded; path is accepted as an alias.
Any failure to build the resolver degrades gracefully to per-platform keys and logs a warning — startup never aborts.

praisonai gateway start --config gateway.yaml \
  --identity-store ~/.praisonai/identity.json

The CLI value overrides the YAML identity: block.
The value is ~-expanded.
If StoreBackedIdentityResolver can’t be imported (optional deps missing), a warning is logged and the gateway continues without the resolver.

from praisonai_bot.gateway.server import WebSocketGateway
from praisonai_bot.bots import StoreBackedIdentityResolver

resolver = StoreBackedIdentityResolver.from_env()
gateway = WebSocketGateway(
    host="127.0.0.1",
    port=8765,
    identity_resolver=resolver,   # #3020 — stamped onto every channel bot
)
await gateway.start_with_config("gateway.yaml")

A constructor resolver is marked explicit and is never rebuilt from YAML, even on hot-reload.

Precedence

WebSocketGateway(identity_resolver=…) > --identity-store > identity: YAML block > default (per-platform keys) An explicit constructor or CLI resolver is never clobbered by the YAML block, even on hot-reload. The gateway stamps the resolver onto each channel bot’s session manager at startup and on every hot-reload:

Gateway process: In the praisonai gateway start daemon, the resolver is stamped onto each channel bot’s session manager via WebSocketGateway._stamp_identity_resolver() (mirrors _stamp_admission_gate). Restarted channels during hot-reload keep the resolver too — see Gateway Config Reload.

End-to-end: one session across two platforms

Operator approves both channels for the same label:

praisonai pairing approve telegram <code> --label alice
praisonai pairing approve discord  <code> --label alice

Operator adds identity: { enabled: true } to gateway.yaml (or passes --identity-store).
Alice on Telegram: "my favourite colour is octarine".
Hours later, Alice on Discord: "what's my favourite colour?".
The gateway resolves both to alice, loads the same session history, and replies "Octarine.".

CLI: praisonai identity

Four subcommands manage identity links from the command line.

Command	Purpose
`praisonai identity link <platform> <user_id> <canonical>`	Map a `(platform, user_id)` to a canonical identity
`praisonai identity unlink <platform> <user_id>`	Remove a mapping
`praisonai identity list [canonical]`	Show all links, or links for a single canonical id
`praisonai identity import`	Materialise paired channels as explicit identity links

Each subcommand accepts:

Option	Default	Description
`--path`	`~/.praisonai/identity.json` (or `$PRAISONAI_IDENTITY_PATH`)	Override the link-map JSON path
`--store-dir`	gateway default	Override the pairing store directory

# Link Alice's Telegram + WhatsApp identities to one canonical id
praisonai identity link telegram 12345 alice
praisonai identity link whatsapp "+44123456789" alice

# Inspect
praisonai identity list alice
# Links for alice:
#   telegram:12345
#   whatsapp:+44123456789

# Or list every mapping
praisonai identity list

# Unlink one channel
praisonai identity unlink telegram 12345

# Promote paired channels (labelled via `praisonai pairing approve ... --label`) into explicit links
praisonai identity import
# ✅ Imported 3 identity link(s) from pairing store

SessionContext for Tools

Any tool the agent calls can read who is messaging:

from praisonaiagents import Agent
from praisonaiagents.session import get_session_context

def whoami() -> str:
    ctx = get_session_context()
    return f"You are {ctx.user_name or ctx.user_id} on {ctx.platform}"

agent = Agent(name="assistant", instructions="Use whoami when asked.", tools=[whoami])

SessionContext Fields

Field	Type	Description
`platform`	`str`	`"telegram"`, `"discord"`, `"slack"`, …
`chat_id`	`str`	Platform chat / channel id
`chat_name`	`str`	Human-readable channel name
`thread_id`	`str`	Thread / topic id (Slack threads, Telegram topics)
`user_id`	`str`	Raw platform user id
`user_name`	`str`	Display name
`unified_user_id`	`str`	Result of `IdentityResolver.resolve()`
`origin`	`Optional[Origin]`	`None`	Platform-aware origin info — see Platform-Aware Agents
`reachable_targets`	`Optional[List[ReachableTarget]]`	`None`	Channels the agent can deliver to — see Platform-Aware Agents

Use set_session_context / clear_session_context for advanced custom adapters. Returns a token; reset in a finally block.

Concurrent Turns Across Adapters

With an identity resolver configured, near-simultaneous turns from different adapters that resolve to the same unified user run one at a time against that user’s single transcript. Each adapter — Telegram, Discord, Slack — keeps its own session manager, and the identity resolver unifies them onto one persisted session per human. Before this fix, each adapter still guarded its turns separately, so two adapters could run turns for the same human at the same time and scramble the order of their shared transcript.

When	What happens
One adapter, one user	Turns already serialise per user — unchanged.
Multiple adapters, no resolver	Each adapter keeps its own per-user history (`bot_{platform}_{user_id}`) — no unified transcript, no shared lock needed. Unchanged.
Multiple adapters, with resolver	Turns from any adapter for the same unified user run serially against the one shared transcript. This is the new behaviour.

When it matters

A cron or scheduled outbound delivery lands on platform A while the user replies on platform B — the mirror and the inbound reply serialise cleanly (see Mirror for Outbound Deliveries).
A user types on Telegram while their smartwatch fires a Slack message in the same second — the second turn waits for the first to commit before appending, so the transcript stays in strict user → assistant → user order.

Nothing to configure. This is automatic whenever an identity resolver is wired via BotOS(identity_resolver=…), the gateway’s identity: YAML block, or --identity-store. Deployments without a resolver are unchanged.

Multi-replica gateways: the shared turn lock stamped onto channel bots is in-process only. If you scale the gateway to replicas > 1, enable a distributed backend — see Gateway Turn Lock.

Mirror for Outbound Deliveries

Cron jobs, scheduled deliveries, and cross-platform replies need to mirror the assistant’s outbound message into the user’s history:

from praisonai.bots import mirror_to_session

# After sending a notification programmatically
mirror_to_session(
    session_mgr=bot._session,
    user_id="alice",
    message_text="Reminder: your standup is in 5 minutes.",
    source_label="cron",
)

Parameters

Parameter	Type	Description
`session_mgr`	`BotSessionManager`	Session manager instance
`user_id`	`str`	Unified user ID
`message_text`	`str`	Message content to mirror
`source_label`	`str`	Source identifier (`"cron"`, `"web"`, `"cross_platform"`)
`metadata`	`dict`	Optional extra metadata
`lock`	`threading.RLock`	Optional lock for synchronization

Errors are swallowed and logged — a mirror failure must never break the outbound delivery itself.

Storage & Privacy

FileIdentityResolver defaults to ~/.praisonai/identity.json (override via PRAISONAI_IDENTITY_PATH env var or constructor path=). File is written atomically and chmod 0o600.

Identity links are explicit and opt-in. No automatic linking — wire the resolver only after a verified DM-pairing flow confirms the same human controls both accounts.

Without a resolver, the legacy bot_{platform}_{user_id} storage key is preserved bit-for-bit — fully backward compatible.

Running the flagship daemon? See In the gateway (praisonai gateway start) for wiring the same resolver via the identity: YAML block, --identity-store, or the WebSocketGateway constructor.

Best Practices

Use StoreBackedIdentityResolver for production (with pairing)

For production wrapper deployments, use StoreBackedIdentityResolver.from_env() — it picks up paired channels automatically and falls back to the same safe platform:user_id default. Plain FileIdentityResolver is the right choice only when you do not use the pairing system.

from praisonai.bots import StoreBackedIdentityResolver

resolver = StoreBackedIdentityResolver.from_env()

Use FileIdentityResolver for explicit-only links

For production single-host bots without pairing integration, FileIdentityResolver provides persistent storage with atomic writes and proper file permissions.

from praisonaiagents.session import FileIdentityResolver

resolver = FileIdentityResolver()  # ~/.praisonai/identity.json

Implement custom IdentityResolverProtocol for scale

For multi-process/multi-host deployments, back it with SQLite, Redis, or a database:

from praisonaiagents.session import IdentityResolverProtocol

class DatabaseIdentityResolver:
    def resolve(self, platform: str, platform_user_id: str) -> str:
        # Query your database
        pass
    
    def link(self, platform: str, platform_user_id: str, unified_user_id: str) -> None:
        # Store in your database
        pass

Pair before linking

Never auto-link based on display name. Always require a DM-verified pairing flow:

# After DM verification succeeds
resolver.link("telegram", telegram_user_id, verified_unified_id)
resolver.link("discord", discord_user_id, verified_unified_id)

Read SessionContext in tools

Instead of os.environ, read SessionContext — concurrent message handlers won’t trample each other:

def get_user_platform() -> str:
    ctx = get_session_context()
    return ctx.platform  # Thread-safe, context-aware

BotOS

Multi-platform bot orchestrator

Messaging Bots

Platform-specific bot guides

Bot Pairing

Secure unknown-user onboarding

Unknown-User Pairing

Inline-button approval for bots

Gateway CLI

--identity-store and other gateway start flags

Gateway Config Reload

Hot-reload the identity: block without dropping turns

​How It Works

​Quick Start

​Choosing Your Resolver

​StoreBackedIdentityResolver

​link_paired() — Promote Paired Users to Explicit Links

​In the gateway (praisonai gateway start)

​Precedence

​End-to-end: one session across two platforms

​CLI: praisonai identity

​SessionContext for Tools

​SessionContext Fields

​Concurrent Turns Across Adapters

​When it matters

​Mirror for Outbound Deliveries

​Parameters

​Storage & Privacy

​Best Practices

​Related

BotOS

Messaging Bots

Bot Pairing

Unknown-User Pairing

Gateway CLI

Gateway Config Reload

How It Works

Quick Start

Choosing Your Resolver

StoreBackedIdentityResolver

link_paired() — Promote Paired Users to Explicit Links

In the gateway (`praisonai gateway start`)

Precedence

End-to-end: one session across two platforms

CLI: praisonai identity

SessionContext for Tools

SessionContext Fields

Concurrent Turns Across Adapters

When it matters

Mirror for Outbound Deliveries

Parameters

Storage & Privacy

Best Practices

Related