> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Channel Pairing

> How ArgentOS links platform users to agent sessions across channels.

## 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

```mermaid theme={null}
flowchart TD
    A[Message arrives from channel] --> B[Extract platform user ID]
    B --> C{Already paired?}
    C -->|Yes| D[Resume existing session]
    C -->|No| E[Create new session & pair]
```

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`

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

## Configuring Pairs

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

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    argent channels pair --platform telegram --user-id 123456789 --session user-jason
    ```
  </Tab>

  <Tab title="Config File">
    ```json theme={null}
    {
      "channels": {
        "pairing": {
          "123456789@telegram": "user-jason",
          "+15551234567@whatsapp": "user-jason"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 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.

<Info>
  Use `allowedUsers` on each channel to restrict who can interact with the agent at all.
</Info>

## 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.