Skip to main content
Pending tool approvals normally live in process memory — a gateway restart loses in-flight decisions. A durable approval store persists them so a late Allow/Deny tap still resolves correctly.
Two durable stores, different jobs:
  • This page — the bot pending-approval queue (ApprovalStore at ~/.praisonai/state/approvals.sqlite) tracks in-flight tap prompts waiting for a decision.
  • Sibling — the gateway allow-list store (Gateway Scoped Approvals, ScopedAllowlistStore at ~/.praisonai/state/gateway/approvals.sqlite) tracks “allow always” grants that skip future prompts.
Transport wiring for Telegram is auto-configured — see Telegram Durable Approval. This page covers the underlying store used by that path.
from praisonai.bots import ApprovalStore, Bot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = Bot(
    "telegram",
    agent=agent,
    approval_store=ApprovalStore(path="~/.praisonai/state/approvals.sqlite"),
)
bot.run()
The user taps Allow or Deny on a channel; the durable store resolves the pending approval even after a gateway restart.

​
Quick Start

1

Create a store

from praisonai.bots import ApprovalStore

store = ApprovalStore(
    path="~/.praisonai/state/approvals.sqlite",
    ttl_seconds=7 * 86400,  # evict resolved rows after 7 days
)
2

Pass it to your bot

from praisonai.bots import Bot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = Bot("telegram", agent=agent, approval_store=store)
bot.run()
3

Restart safely

On startup, outstanding pending approvals are re-hydrated. Users can tap Allow/Deny on messages sent before the restart.

​
How It Works

Each ApprovalRequest carries a stable approval_id (UUID hex) used as the correlation key across restarts.
Persisted approvals can be recorded as reusable command prefixes — see Reusable Approval Scopes for the reusable_scope=True opt-in.

​
ApprovalStore API

MethodDescription
persist(approval_id, request, *, expires_at)Store a pending approval; refuses to overwrite resolved rows
list_pending()Return outstanding un-expired approvals
resolve(approval_id, decision)Record final decision; returns False if already resolved
expire_overdue()Mark past-expiry pending rows as expired
get(approval_id)Inspect a row for audit/doctor
purge()Delete all entries

​
What Gets Stored

pending_approvals(
    approval_id TEXT PRIMARY KEY,
    ts REAL,
    expires_at REAL,
    request TEXT,        -- JSON ApprovalRequest
    status TEXT,         -- pending | approved | denied | expired
    decision TEXT,       -- JSON ApprovalDecision when resolved
    approver TEXT,
    resolved_at REAL
)
Without a store, behaviour is unchanged — in-memory approvals remain the zero-dependency default. The core SDK defines ApprovalStoreProtocol; the SQLite implementation lives in praisonai.bots.
PersistentApproval entries in approvals.json carry a derived: bool field (default False). When derived=True, the pattern was auto-generated by the reusable command-prefix scope derivation — for example bash:git status * instead of the literal bash:git status -s. Derived patterns match the bare prefix too (bash:git status with no trailing args). Approvals from older approvals.json files default to derived=False and behave as before. See Reusable Approval Scopes.

​
Secure, Actor-Authorised Approval Backend

The secure (alias: presentation) backend wraps PresentationApprovalHandler and ApprovalStore together into a single ApprovalProtocol adapter — adding actor authorisation and fail-closed behaviour on top of the base durability layer.
--approval secure is fail-closed: if PRAISONAI_APPROVAL_ACTORS is empty or not set, the gateway refuses to start. This prevents an empty allow-list from silently permitting any actor to approve.

​
Activate via CLI

export PRAISONAI_APPROVAL_ACTORS="telegram:12345,slack:U0123456"
praisonai serve gateway --config gateway.yaml --approval secure

​
Activate via Python

from praisonaiagents import Agent
from praisonai.bots import Bot

agent = Agent(name="assistant", instructions="Be helpful")
bot = Bot("telegram", agent=agent, approval="secure")
bot.run()

​
How it differs from the base ApprovalStore

FeatureApprovalStore alone--approval secure
Persist to SQLite✅✅
Rehydrate on restart✅✅
Actor allow-list❌✅ (PRAISONAI_APPROVAL_ACTORS)
LLM classifier for Allow/DenySome backends❌ (never uses LLM)
Fail-closed on empty allow-list❌✅
Approval ID binding✅✅ (unguessable UUID)

​
Configuration

SettingHow to setRequired
Allow-listPRAISONAI_APPROVAL_ACTORS=telegram:123,slack:U456Yes (fail-closed)
Store pathPRAISONAI_HOME=/path/to/dir (approvals stored in <HOME>/state/approvals.sqlite)No (default: ~/.praisonai)

​
Rehydration guarantee

Allow-list actors are stored alongside each pending approval. On restart, re-hydrated approvals carry the original allow-list — late Allow/Deny taps after a redeploy are still bound to the original requester.

​
Best Practices

Telegram, Slack, and Discord bots that restart for deploys benefit most — users won’t lose half-resolved prompts.
Default eviction is 7 days. Tune ttl_seconds to bound disk growth while keeping an audit trail.
Console and webhook backends work without a store. Add one only when restart-safety matters.

Approval

Default approval behaviour and backends

Approval Protocol

ApprovalStoreProtocol and backend contracts

Messaging Bots

Deploy agents to chat channels