Channel Pairing

Overview

Channel pairing is the mechanism ArgentOS uses to link a platform-specific user identity (a Telegram user ID, Discord user, phone number, etc.) to an agent session. This ensures continuity -- your agent remembers the conversation regardless of which channel you use.

How Pairing Works

When a message arrives from a channel, the flow is:

1. Identify: Extract the platform user identifier (Telegram user ID, Discord user ID, phone number, etc.)
2. Lookup: Check if this identifier is already paired to an existing session
3. Create or Resume: If paired, resume the session. If not, create a new session and pair it.

Cross-Channel Identity

A single user can be paired across multiple channels. For example:

• Telegram user 123456789 -> Session user-jason
• Discord user jason#1234 -> Session user-jason
• WhatsApp +15551234567 -> Session user-jason

All three channels route to the same session, so the agent maintains one continuous conversation and shared memory context.

Configuring Pairs

Pairing happens automatically on first contact, but you can manually configure pairs:

argent channels pair --platform telegram --user-id 123456789 --session user-jason

Or in argent.json:

{
  "channels": {
    "pairing": {
      "123456789@telegram": "user-jason",
      "+15551234567@whatsapp": "user-jason"
    }
  }
}

Session Isolation

By default, unpaired users get their own isolated session. This prevents strangers from accessing your agent's context if they discover your bot.

Use allowedUsers on each channel to restrict who can interact with the agent at all.

Multiple Users

ArgentOS supports multiple paired users, each with their own session:

• User A messages on Telegram -> Session user-a
• User B messages on Discord -> Session user-b

Each session has its own context window, memory scope, and conversation history.