Gateway Live Session Handoff

Move an in-progress conversation onto a freshly created thread on another platform

Start a conversation on your laptop, continue it on Telegram — the same session, the same transcript, the next reply lands where you moved.

Quick Start

1. Minimal handoff

   from praisonai_bot.bots import BotOS, ThreadRef
   
   ref: ThreadRef = await botos.handoff(session_key, to="telegram")
   
   if ref.ok:
       print(f"Continue on {ref.target}")

2. With a seed message and breadcrumb

   from praisonai_bot.bots import BotOS, ThreadRef
   
   ref = await botos.handoff(
       session_key,
       to="telegram",
       name="Trip planning",
       seed_text="Continuing here — same conversation.",
       announce=True,
   )

How It Works

handoff reuses DeliveryRouter.create_thread to open the destination thread, then seeds it with the origin transcript so the conversation continues seamlessly — it adds no new per-platform behaviour.

The destination session key is composed as platform:channel:thread — subsequent turns arriving on the new thread route to it through the normal inbound path.

ThreadRef

handoff returns a frozen ThreadRef describing the destination thread and the session key subsequent turns route to.

handoff() Parameters

Status Decision Guide

Every call resolves to exactly one status — map it to the right caller action.

Capability Requirements

The target adapter must set supports_threads=True on its PlatformCapabilities; otherwise handoff returns status == "unsupported" and seeds nothing.

See Platform Capabilities for the per-adapter descriptor.

Common Patterns

Chat-command style — a /handoff <platform> wrapper moves the session and reports the outcome back.

from praisonai_bot.bots import BotOS, ThreadRef

async def on_handoff_command(botos: BotOS, session_key: str, platform: str, origin):
    ref = await botos.handoff(session_key, to=platform, origin=origin)
    if ref.ok:
        return f"Moved — continue on {ref.target}"
    return f"Could not hand off: {ref.status}"

Programmatic hand-off after a long-running step — move the user to their phone once the work is done.

ref = await botos.handoff(session_key, to="telegram", seed_text="Flight booked — continue with me here.")
if not ref.ok:
    ...  # unsupported | failed | no_route — keep the origin conversation

Best Practices

Long-running hosts

Gateways, bots, and servers keep bounded state (PraisonAI #5772):

Related