Bot Pairing - PraisonAI

Bot platform adapters now ship in the praisonai-bot package. praisonai bot serve still works exactly as documented here; for a standalone install see praisonai-bot Migration.

Bot pairing lets unknown users self-request access to your bot with secure 8-character codes that you approve from the CLI.

from praisonaiagents import Agent, BotConfig

agent = Agent(name="assistant", instructions="You are a helpful assistant.")
config = BotConfig(unknown_user_policy="pair")
agent.start("An unknown user wants access — generate a pairing code.")

The user DMs the bot for the first time; PraisonAI issues an 8-character code you approve from the CLI.

Quick Start

Enable Pairing Policy

from praisonaiagents import Agent
from praisonaiagents import BotConfig

config = BotConfig(
    allowed_users=["@owner"],
    unknown_user_policy="pair",  # Enable pairing for unknown users
)

# Bot setup with Telegram adapter (other platforms pending)
# from praisonai.bots.telegram import TelegramAdapter
# bot = TelegramAdapter(config)

The same config from gateway.yaml — both keys are read per-channel (PR #2856):

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    unknown_user_policy: pair
    owner_user_id: ${TELEGRAM_OWNER_ID}
    routes:
      default: assistant

Approve Pairing Requests

# List pending pairing requests
praisonai pairing list

# Approve a user's pairing code
praisonai pairing approve telegram ABCD1234 --label "alice"

# View all paired channels
praisonai pairing list

How It Works

The pairing flow now fires only when BotConfig.is_explicitly_allowed(user_id) returns False (empty allowlist, or user not on it). Users on allowed_users skip pairing entirely — PR #2856.

Policy Configuration

Unknown User Policies

from praisonaiagents import BotConfig

# Policy options
config = BotConfig(
    allowed_users=["@owner", "123456789"],
    unknown_user_policy="pair"  # Choose one below
)

Policy	Behavior	Use Case
`"deny"`	Silently drop messages (default)	Private bots, testing
`"allow"`	Allow all users (overrides allowed_users)	Public bots
`"pair"`	Use pairing flow for approval	Controlled access

Pairing Rate Limiting

The system includes built-in protection against code generation spam:

Rate Limit: 10 minutes between code generations per channel
Code TTL: Codes expire after a configurable time (default: check PaisingStore implementation)
Automatic Cleanup: Stale rate limit entries are automatically evicted

CLI Commands

List Commands

# List all paired channels
praisonai pairing list

# Example output:
# Found 3 paired channels:
#
# Platform: telegram
# Channel:  @alice_username  
# Paired:   2026-04-22 10:30:15
# Label:    alice
#
# Platform: telegram
# Channel:  987654321
# Paired:   2026-04-22 11:45:22
# Label:    bob

Approve Command

# Approve with auto-resolved channel ID (when code is bound)
praisonai pairing approve telegram ABCD1234

# Approve with explicit channel ID
praisonai pairing approve telegram ABCD1234 987654321

# Approve with human-readable label
praisonai pairing approve telegram ABCD1234 --label "alice"

# Use custom store directory
praisonai pairing approve telegram ABCD1234 --store-dir /path/to/store

Revoke Access

# Revoke specific channel
praisonai pairing revoke telegram 987654321

# Clear all pairings (with confirmation)
praisonai pairing clear
# Are you sure you want to clear ALL paired channels? [y/N]: y
# ✅ Cleared 3 paired channels

# Clear without confirmation prompt
praisonai pairing clear --confirm

Web-UI / HTTP API Approval

Approve, list, and revoke pairings from a web admin UI via the gateway’s HTTP API.

Endpoints

List Pending
Approve Pairing
Revoke Access

GET /api/pairing/pendingReturns pending pairing requests awaiting approval.

curl -X GET "http://localhost:8000/api/pairing/pending" \
  -H "Cookie: session=<admin-session-cookie>"

import httpx

resp = httpx.get(
    "http://localhost:8000/api/pairing/pending",
    cookies={"session": "<admin-session-cookie>"},
)
resp.raise_for_status()
print(resp.json())  # {"pending": [{"channel_type": "ui", "code": "ABCD1234", "channel_id": "user123", "age_seconds": 45}]}

POST /api/pairing/approveApprove a pairing code to authorize the channel.

curl -X POST "http://localhost:8000/api/pairing/approve" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<admin-session-cookie>" \
  -d '{"channel": "ui", "code": "ABCD1234"}'

import httpx

# Admin operator approves a pending UI pairing
resp = httpx.post(
    "http://localhost:8000/api/pairing/approve",
    json={"channel": "ui", "code": "ABCD1234"},
    cookies={"session": "<admin-session-cookie>"},
)
resp.raise_for_status()
print(resp.json())  # {"approved": True, "channel": "ui", "code": "ABCD1234"}

POST /api/pairing/revokeRevoke authorization for a previously paired channel.

curl -X POST "http://localhost:8000/api/pairing/revoke" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<admin-session-cookie>" \
  -d '{"channel": "ui", "user_id": "user123"}'

import httpx

resp = httpx.post(
    "http://localhost:8000/api/pairing/revoke",
    json={"channel": "ui", "user_id": "user123"},
    cookies={"session": "<admin-session-cookie>"},
)
resp.raise_for_status()
print(resp.json())

All three routes are gated by an admin auth checker (auth_admin) wired in by create_pairing_routes(pairing_store, auth_admin). Non-admin sessions receive 403. Invalid codes return 404.

The code parameter on /approve is consumed atomically — replays return 404.

Reacting to Pairing Approvals (EventBus)

Subscribe to the pairing_approved event to run agent logic the moment a channel is approved — for example, send a welcome DM, log to your CRM, or warm a per-user memory store.

from praisonaiagents import Agent
from praisonaiagents.bus import get_default_bus

welcomer = Agent(
    name="Welcomer",
    instructions="Write a one-line friendly welcome message for a new user.",
)

def on_pairing_approved(event):
    channel = event.data["channel"]
    code = event.data["code"]
    welcome = welcomer.start(f"Welcome the new {channel} user with code {code}")
    print(welcome)

get_default_bus().subscribe(on_pairing_approved, ["pairing_approved"])

Event Payload

Field	Type	Description
`event.type`	`str`	Always `"pairing_approved"`
`event.data["channel"]`	`str`	Channel type (e.g., `"telegram"`, `"ui"`, `"slack"`)
`event.data["code"]`	`str`	The pairing code that was approved

Handlers run synchronously in the request path — keep them fast or hand off to a background queue.

Platform Support

Current Implementation

Platform	Status	Handler Wiring	CLI Support
Telegram	✅ Shipped	✅ Complete	✅ Full
Web UI (HTTP API)	✅ Shipped	✅ via /api/pairing/* routes	✅ Full
Discord	🔧 Pending	❌ Not wired	✅ CLI ready
Slack	🔧 Pending	❌ Not wired	✅ CLI ready
WhatsApp	🔧 Pending	❌ Not wired	✅ CLI ready

Platform Implementation Status: PR #1504 ships the pairing system and CLI with full Telegram support. Other platform adapters need handler wiring to complete the integration.

Telegram Integration

# Telegram adapter includes UnknownUserHandler wiring
from praisonai.bots.telegram import TelegramAdapter
from praisonaiagents import BotConfig

config = BotConfig(
    token=os.getenv("TELEGRAM_BOT_TOKEN"),
    unknown_user_policy="pair"
)

# Handler automatically wired in Telegram adapter
bot = TelegramAdapter(config)

Security Model

Store Hardening (PraisonAI #3974)

PraisonAI #3974 hardens the pairing store without changing its public API — legacy plaintext pairing.json stores still load, so there is nothing to migrate.

At-rest hashing

Since #3974, only a salted SHA-256 of each pending code is written to pairing.json. Reading the file never yields a usable code, and a rainbow table is useless without the per-install HMAC secret used as salt.

{
  "pending": [
    {
      "code_hash": "9f2c…64-hex-chars…a1",
      "signature": "…",
      "channel_type": "telegram",
      "channel_id": "tg_42",
      "created_at": 1755255600.0
    }
  ]
}

On a fresh process, praisonai pairing list (or PairingStore.list_pending()) against a store whose code was created in another process returns entries with code: None and the code_hash — the pending request stays visible, the raw code does not.

Store-level brute-force lockout

verify_and_pair() counts failed verifications per channel_type and refuses further attempts once the ceiling trips — uniformly across every approval surface (HTTP route, in-chat Approve/Deny button, CLI praisonai pairing approve). Tune via constructor kwargs:

Constructor kwarg	Default	Meaning
`max_failures`	`5`	Consecutive failed verifications before lockout trips
`lockout_window`	`60.0` s	Sliding window that counts failures
`lockout_cooldown`	`300.0` s	How long a `channel_type` is refused once tripped

A success clears the counter; a valid HMAC presented against the wrong channel_id does not (otherwise a repeated wrong-binding guess would reset the budget). Once locked out, even a valid code for that channel_type is refused until the cooldown expires — the lockout is store-level, not surface-level.

Log line to watch in operator dashboards: Pairing verification locked out for channel_type=<type> (level WARNING).

Unambiguous alphabet

Generated codes use ABCDEFGHJKLMNPQRSTUVWXYZ23456789 — 8 characters, dropping 0/O/1/I so codes read aloud or retyped from another device are not mis-entered. Length is unchanged; entropy rises to log2(32^8) = 40 bits.

max_pending now counts entries rehydrated from disk, so repeated restarts can no longer grow pairing.json past the configured bound.

Code Generation

8-character codes: Unambiguous alphabet ABCDEFGHJKLMNPQRSTUVWXYZ23456789 (drops 0/O/1/I, since #3974)
HMAC signatures: Codes are cryptographically signed
Hashed at rest: Only a salted SHA-256 of each code is persisted (since #3974)
Per-install secret: Auto-generated if PRAISONAI_GATEWAY_SECRET unset
Channel binding: Codes can be bound to specific channel IDs

Secret Management

# Option 1: Set explicit gateway secret (recommended for production)
export PRAISONAI_GATEWAY_SECRET="your-secure-secret-key"

# Option 2: Auto-generated per-install secret
# Stored at ~/.praisonai/gateway/.gateway_secret with 0600 permissions
# Persists across restarts, unique per installation

Pairing codes and the inline Approve/Deny callback buttons share this one persisted HMAC secret at ~/.praisonai/gateway/.gateway_secret. Both survive gateway restarts by default — no operator action required. See Unknown-User Pairing → HMAC-signed Callbacks for the callback-button flow.

Secret Persistence & Remediation (updated in PR #2850):Without PRAISONAI_GATEWAY_SECRET, a per-install HMAC secret is auto-generated at <store_dir>/.gateway_secret with mode 0o600. This file signs pairing codes, so world-readable permissions would let an attacker forge codes. Every PairingStore(...) construction re-checks and remediates the file — not only at creation:

POSIX: any mode other than 0o600 is chmod-ed to 0o600 and an INFO line is logged ("Remediated insecure gateway secret permissions <mode> -> 0o600 at <path>"). If chmod itself fails, PairingStore construction raises OSError (fail closed). It deliberately does not fall back to regenerating the secret, because regeneration would rotate the HMAC key and invalidate every outstanding pairing code.
Windows: POSIX mode bits are not authoritative. A best-effort ACL lockdown runs via %SystemRoot%\System32\icacls.exe <path> /inheritance:r /grant:r "<user>":F — inheritance stripped, current user granted Full access. icacls is resolved from System32 (not PATH) to avoid a hijacked binary. Success and failure both log at DEBUG only, no operator action is required, and this path never raises.

An existing 0o666 file left over from an older install is fixed automatically on the next startup — no manual chmod needed. See Security → PR #2850 for the hardening summary.

Security Features

Rate Limiting: 600s (10 min) window per channel prevents spam
HMAC Verification: Codes are cryptographically signed and verified
TTL Expiration: Codes automatically expire after configured time
Atomic Operations: Pairing state persisted atomically to disk

User Interaction Flow

Step-by-Step Process

Unknown User DMs Bot
Unknown User: Hello!

Bot Generates Pairing Code

Bot: Your pairing code: `ABCD1234`
Owner: `praisonai pairing approve telegram ABCD1234`

Owner Approves via CLI

$ praisonai pairing approve telegram ABCD1234 --label "alice"
✅ Successfully paired telegram channel 987654321
   Label: alice

User Can Now Interact Normally

Unknown User: Hello!
Bot: Hi there! How can I help you today?

Rate Limit Handling

If a user tries to generate codes too frequently:

User: Hello!
Bot: [no response - rate limited]

# In logs:
# DEBUG: Rate limited channel 987654321 (last code: 120.5s ago)

The user must wait for the rate limit window (10 minutes) to expire before requesting a new code.

Configuration Options

Store Directory

# Default: ~/.praisonai/pairing/
praisonai pairing list

# Custom directory
praisonai pairing list --store-dir /custom/path

# All commands support --store-dir
praisonai pairing approve telegram ABCD1234 --store-dir /custom/path

Environment Variables

# Explicit gateway secret (recommended for production)
export PRAISONAI_GATEWAY_SECRET="your-256-bit-secret"

# Custom store directory (optional)
export PRAISONAI_STORE_DIR="/custom/store/path"

Best Practices

Production Secret Management

Set PRAISONAI_GATEWAY_SECRET explicitly in production environments to ensure consistent code verification across deployments.

# Generate secure secret
openssl rand -hex 32 > gateway_secret.txt

# Set in production
export PRAISONAI_GATEWAY_SECRET=$(cat gateway_secret.txt)

Monitor Rate Limits

Watch for rate limiting warnings in logs - they indicate potential pairing spam or legitimate users hitting limits.

# Look for these log patterns:
# DEBUG: Rate limited channel 123456 (last code: 45.2s ago)
# INFO: Generated pairing code for user123 on telegram: ABCD1234

Use Descriptive Labels

Add labels when approving pairings to identify channels later.

# Good - easy to identify
praisonai pairing approve telegram ABCD1234 --label "alice-work"
praisonai pairing approve telegram EFGH5678 --label "bob-personal"

# Less helpful
praisonai pairing approve telegram ABCD1234

Regular Pairing Audits

Periodically review paired channels and revoke access for inactive users.

# Review all pairings
praisonai pairing list

# Revoke specific channels  
praisonai pairing revoke telegram 987654321

# Clear all if starting fresh
praisonai pairing clear --confirm

Pair a user with a non-empty --label (the canonical id) and StoreBackedIdentityResolver automatically unifies their session across every channel paired under the same label. No separate praisonai identity link calls needed. See Cross-Platform Sessions › StoreBackedIdentityResolver.

Bot Security

Comprehensive bot security and DM policies

Messaging Bots

Bot platform setup and configuration

Cross-Platform Sessions

Unified per-user sessions across platforms

​Quick Start

​How It Works

​Policy Configuration

​Unknown User Policies

​Pairing Rate Limiting

​CLI Commands

​List Commands

​Approve Command

​Revoke Access

​Web-UI / HTTP API Approval

​Endpoints

​Reacting to Pairing Approvals (EventBus)

​Event Payload

​Platform Support

​Current Implementation

​Telegram Integration

​Security Model

​Store Hardening (PraisonAI #3974)

​At-rest hashing

​Store-level brute-force lockout

​Unambiguous alphabet

​Code Generation

​Secret Management

​Security Features

​User Interaction Flow

​Step-by-Step Process

​Rate Limit Handling

​Configuration Options

​Store Directory

​Environment Variables

​Best Practices

​Related

Bot Security

Messaging Bots

Cross-Platform Sessions

Quick Start

How It Works

Policy Configuration

Unknown User Policies

Pairing Rate Limiting

CLI Commands

List Commands

Approve Command

Revoke Access

Web-UI / HTTP API Approval

Endpoints

Reacting to Pairing Approvals (EventBus)

Event Payload

Platform Support

Current Implementation

Telegram Integration

Security Model

Store Hardening (PraisonAI #3974)

At-rest hashing

Store-level brute-force lockout

Unambiguous alphabet

Code Generation

Secret Management

Security Features

User Interaction Flow

Step-by-Step Process

Rate Limit Handling

Configuration Options

Store Directory

Environment Variables

Best Practices

Related