Per-Chat Session Scope

Share one transcript across a group with sender attribution

In group chats, share one transcript across all participants — each message prefixed with the sender’s name.

from praisonaiagents import Agent

agent = Agent(
    name="session-agent",
    instructions="Maintain separate context per chat session.",
)
agent.start("This is a new session — remember nothing from before.")

The user messages in a group chat; everyone shares one transcript with sender names attached.

# gateway.yaml
channels:
  telegram:
    platform: telegram
    token: "${TELEGRAM_BOT_TOKEN}"
    session:
      session_scope: per_chat

agent:
  name: assistant
  instructions: "Help the group. Refer to participants by name."
  model: gpt-4o-mini

Quick Start

1. Enable per_chat scope in your gateway config

   # gateway.yaml
   channels:
     telegram:
       platform: telegram
       token: "${TELEGRAM_BOT_TOKEN}"
       session:
         session_scope: per_chat
   
   agent:
     name: assistant
     instructions: "Help the group. Refer to participants by name."
     model: gpt-4o-mini
   

   Run with:

   praisonai gateway start gateway.yaml
   

   In a Telegram group, the agent now sees one shared transcript:

   [Alice] when is the launch?
   [Bob] next friday
   [Alice] cool, who's demoing?
   
2. Customise the attribution template

   channels:
     telegram:
       platform: telegram
       token: "${TELEGRAM_BOT_TOKEN}"
       session:
         session_scope: per_chat
         attribution: "[{sender} at {time}] "
   

   The attribution template supports two placeholders:

   • {sender} — the sender’s display name
   • {time} — current time in HH:MM format

   Result: [Alice at 14:32] when is the launch?

---

How It Works

The session key in per_chat mode is:

{platform}:acct:{account}:chat:{chat_id}:{thread_id}

This keeps different group chats and threads isolated from each other, even on the same platform.

---

per_user vs per_chat

Direct messages always use per_user scope, even when session_scope: per_chat is configured. Private conversations are never merged into a shared group transcript.

---

Configuration

Set these options under session: in your channel config:

Option	Type	Default	Description
session_scope	str	"per_user"	"per_user" for isolated sessions (default) or "per_chat" for shared group sessions
attribution	str	"[{sender}] "	Template prefixed to each turn in per_chat scope. Supports {sender} and {time}
max_history	int	100	Maximum number of turns to keep in session history

Valid values for session_scope: per_user, per_chat. Any other value raises a validation error.

Temporal grounding: add timestamps: true under session: to prefix each turn with its arrival time so the agent can reason about “now” and relative-time requests. In per_chat the time sits outermost, after the sender name. See Bot Temporal Grounding.

---

/new in Groups

The /new command clears the shared session for the whole group — not just the sender.

All seven supported adapters (telegram, slack, discord, whatsapp, email, linear, agentmail) thread chat_id through their reset handlers. A /new from inside a DM clears only that user’s private session, not any group session.

Alice: /new
Bot: ✅ Session cleared for this group.
Bob: what were we talking about?
Bot: I don't have any previous context — what would you like help with?

---

Best Practices

When to enable per_chat

Use per_chat when your group needs one coherent conversation thread — for example, a team planning bot, a group Q&A assistant, or a shared research helper. Keep per_user (the default) when each user needs their own private context, like a personal productivity or support bot added to a group.

Choose an attribution template

The default "[{sender}] " is clear and compact. Add {time} when timing context helps the agent reason about sequences of events:

attribution: "[{sender} at {time}] "

Set attribution: "" to disable attribution entirely — the agent sees messages without sender prefixes.

Avoid key collisions across accounts

The key includes account to namespace different bot accounts on the same platform. If you run two gateway bots on the same Telegram group with different tokens, each bot maintains its own independent shared session. No additional config is needed — this is automatic.

Watch the history budget in busy groups

A per_chat session accumulates turns from all participants. In active groups this fills max_history faster than a one-on-one conversation. Lower max_history or enable compaction to summarise older turns:

session:
  session_scope: per_chat
  max_history: 50
  compaction:
    enabled: true
    strategy: summarize

---

Related

Bot Gateway

Set up the gateway to connect agents to messaging platforms

Multi-Channel Bots

Run one agent across telegram, slack, discord, and more