Skip to main content
Prefix each inbound message with its arrival time so the agent can answer “remind me in 2 hours” or “what did I say this morning?”.

​
Quick Start

1

Enable timestamps in your gateway config

Add one line under session: to stamp every inbound turn:
# gateway.yaml
channels:
  telegram:
    platform: telegram
    token: "${TELEGRAM_BOT_TOKEN}"
    session:
      timestamps: true       # enable arrival-time prefix

agent:
  name: assistant
  instructions: "You are a helpful assistant. Use the time prefix on each message to interpret relative-time requests."
  model: gpt-4o-mini
Run with:
praisonai gateway start gateway.yaml
The model now sees each turn with its real arrival time:
[Fri 2026-07-09 10:15 UTC] Remind me in 2 hours to call mum.
2

Customise the template

session:
  timestamps: true
  timestamp_template: "[%Y-%m-%d %H:%M] "   # drop weekday and timezone
The template must contain a YYYY-MM-DD HH:MM date-time — the replay de-dup regex anchors on it. The %a weekday and %Z timezone are optional, so non-English server locales are safe.

​
How It Works

The session manager strips any stale prefix and re-stamps each turn with its real arrival time before the agent sees it.
BehaviorDetail
ScopeApplied to both per_user (DM) and per_chat (group) turns
Group orderingThe time sits outermost, after sender attribution — e.g. [Fri 2026-07-09 10:15 UTC] [alice] hello
Replay-safeLeading prefixes are stripped and re-rendered each turn, so compaction / reset never accumulates [ts] [ts] … text
FallbackWithout a platform receive time, a timezone-aware UTC now() is used so %Z renders UTC
Fail-openOn a strftime error the raw un-stamped content is returned — a bad template never breaks chat

​
Configuration Options

Set these under session: in your channel config.
OptionTypeDefaultDescription
timestampsboolFalseWhen true, each inbound turn is prefixed with its arrival time. Off by default for prompt-cache stability
timestamp_templatestr"[%a %Y-%m-%d %H:%M %Z] "strftime template for the prefix. Must contain a YYYY-MM-DD HH:MM date-time — the replay de-dup regex anchors on it
Keep timestamps off unless the agent needs relative-time reasoning. Every stamped turn is billed again on replay, and the changing prefix breaks prompt caching.

​
Common Patterns

Relative-time reminders — the model reads the prefix to resolve “in 2 hours” against a real clock: 
session:
  timestamps: true
agent:
  instructions: "Resolve relative-time requests using the time prefix on each message."
Group chats — pair with per_chat scope; the timestamp sits outermost so sender attribution stays intact: 
session:
  session_scope: per_chat
  timestamps: true
The agent sees: [Fri 2026-07-09 10:15 UTC] [alice] when's the launch? Minimal prefix — drop the weekday and timezone to save tokens: 
session:
  timestamps: true
  timestamp_template: "[%Y-%m-%d %H:%M] "

​
Best Practices

Leave timestamps off for bots that never reason about time. The prefix changes on every turn, so it disrupts prompt caching and adds tokens to each replayed message. Turn it on for scheduling, reminders, or gap-aware assistants.
Every character in the prefix is billed on every replayed turn. "[%Y-%m-%d %H:%M] " is enough for most agents; the default adds the weekday and timezone for readability.
A custom timestamp_template must render a YYYY-MM-DD HH:MM inside the bracket — the replay de-dup regex anchors on that date-time, not on the English weekday. Templates that omit %a (or run under non-English locales) stay safe.
Don’t hand-format time prefixes in instructions. The session manager strips and re-stamps each turn so replay de-dup works; a manual prefix bypasses that and accumulates on history replay.

Per-Chat Session Scope

Share one transcript across a group — the scope this feature stacks on top of

Session Compaction

How stamped turns survive history compaction

Bot Gateway

Top-level gateway config that owns the session: block

Chat

Chat-level docs where received_at shows up