openclaw/docs/session-sharing.md

Cross-Provider Session Sharing

Overview

The session sharing feature allows users to link multiple messaging provider identities (e.g., WhatsApp phone number and Telegram user ID) to share a single Claude conversation session. This enables seamless conversation continuity across different platforms.

Supported Providers

• WhatsApp (via wa-web provider)
• Telegram
• Twilio (SMS/WhatsApp via Twilio API)

How It Works

Without Identity Mapping (Default)

By default, each provider maintains separate Claude sessions:

• WhatsApp messages from +1234567890 → session: +1234567890
• Telegram messages from user @john → session: telegram:@john
• Each provider has its own isolated conversation history

With Identity Mapping

When identities are linked, they share the same Claude session:

# Link WhatsApp and Telegram identities
warelay identity link --whatsapp +1234567890 --telegram @john --name "John Doe"

# Now both providers share session: shared-abc-123
# WhatsApp from +1234567890 → session: shared-abc-123
# Telegram from @john → session: shared-abc-123

Messages from either provider will continue the same conversation.

Architecture

Identity Mapping Storage

Identity mappings are stored in ~/.clawdis/identity-map.json:

{
  "version": 1,
  "mappings": {
    "shared-abc-123": {
      "id": "shared-abc-123",
      "name": "John Doe",
      "identities": {
        "whatsapp": "+1234567890",
        "telegram": "@john"
      },
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  }
}

Session ID Normalization

The normalizeSessionId() function in src/identity/normalize.ts handles the mapping:

// Without mapping
normalizeSessionId("telegram", "123456") → "telegram:123456"
normalizeSessionId("whatsapp", "+1234") → "+1234"

// With mapping (both return the same shared ID)
normalizeSessionId("telegram", "123456") → "shared-abc-123"
normalizeSessionId("whatsapp", "+1234") → "shared-abc-123"

Integration Points

Session normalization is integrated at the deriveSessionKey() level in src/config/sessions.ts, which means:

• All auto-reply systems automatically use the normalized session IDs
• Session storage (~/.clawdis/sessions.json) uses normalized IDs
• No changes needed in individual provider implementations

Provider ID Formats

Telegram

• Username format: @username (e.g., @john)
• User ID format: 123456789 (numeric)
• Normalized without mapping: telegram:@username or telegram:123456789

WhatsApp (wa-web)

• Format: E.164 phone number (e.g., +1234567890)
• Normalized without mapping: +1234567890 (phone number directly)

Twilio

• Format: E.164 phone number (e.g., +1234567890)
• Normalized without mapping: +1234567890 (phone number directly)

CLI Commands

The following commands are available for managing identity mappings:

Link Identities

warelay identity link --whatsapp +1234567890 --telegram @john --name "John"

Links multiple provider identities to share a single Claude session. At least two providers must be specified.

Options:

• --whatsapp <phone> - WhatsApp phone number in E.164 format
• --telegram <user> - Telegram username (@username) or numeric user ID
• --twilio <phone> - Twilio phone number in E.164 format
• --name <name> - Optional display name for the mapping

List All Mappings

warelay identity list [--json]

Shows all identity mappings with their linked providers and timestamps. Use --json for machine-readable output.

Show Mapping Details

warelay identity show <shared-id> [--json]

Displays detailed information about a specific identity mapping.

Unlink Identities

warelay identity unlink <shared-id>

Removes an identity mapping. After unlinking, each provider will have its own separate Claude session again.

Use Cases

1. Multi-Device Access

Link your personal WhatsApp and Telegram accounts to maintain conversation continuity:

• Start conversation on WhatsApp during work hours
• Continue same conversation on Telegram while commuting
• Claude remembers full context from both platforms

2. Family/Team Sharing

Link multiple family members' or team members' accounts to share a Claude assistant:

• Mom's WhatsApp: +1234567890
• Dad's Telegram: @dad_username
• Both access the same family assistant with shared context

3. Migration Scenarios

Smoothly migrate from one platform to another:

• Link old and new accounts before migration
• Conversation history preserved during transition
• Unlink old account after migration complete

Implementation Details

Provider Detection

The detectProvider() function in src/config/sessions.ts determines the provider from the ID format:

function detectProvider(from: string): "whatsapp" | "telegram" | "twilio" {
  // Telegram: "telegram:123" or "@username"
  if (from.startsWith("telegram:") || from.startsWith("@")) {
    return "telegram";
  }
  // WhatsApp/Twilio: E.164 phone numbers
  return "whatsapp";
}

Async Session Key Derivation

Session key derivation is now async to support identity lookup:

// Before (synchronous)
const key = deriveSessionKey(scope, ctx);

// After (asynchronous)
const key = await deriveSessionKey(scope, ctx);

All callers have been updated to handle the async nature:

• src/auto-reply/reply.ts - Auto-reply system
• src/commands/agent.ts - Agent command
• src/web/auto-reply.ts - Web provider auto-reply

Group Conversations

Identity mapping does NOT apply to group conversations. Groups maintain separate session keys to avoid mixing group and individual conversation contexts:

// Group conversations always use group JID as session key
if (ctx.From.includes("@g.us")) {
  return `group:${ctx.From}`; // No normalization
}

Testing

Comprehensive test coverage in src/identity/:

• normalize.test.ts (11 tests): Session ID normalization logic
• storage.test.ts (18 tests): Identity map persistence and operations

Run tests:

pnpm test src/identity

Backwards Compatibility

The feature is fully backwards compatible:

• No mapping = no change: Without identity mappings, behavior is identical to before
• Existing sessions preserved: Old session IDs continue to work
• Opt-in feature: Users must explicitly create mappings to enable sharing

Security Considerations

• Identity mappings are stored locally in ~/.clawdis/
• No server-side synchronization (privacy-first design)
• Users have full control over which identities are linked
• Unlinking is immediate and removes all associations

Future Enhancements

1. Web UI: Admin interface for managing identity mappings
2. Auto-discovery: Suggest linking when same phone number detected across providers
3. Audit Log: Track when identities were linked/unlinked
4. Export/Import: Backup and restore identity mappings
5. CLI Tests: Add comprehensive E2E tests for all CLI commands

Troubleshooting

Sessions not sharing after linking

1. Check if mapping was created: cat ~/.clawdis/identity-map.json
2. Verify provider IDs match exactly (case-sensitive for Telegram usernames)
3. Restart the relay to pick up new mappings

Wrong identity format

• WhatsApp/Twilio: Must use E.164 format with + prefix (e.g., +1234567890)
• Telegram usernames: Must include @ prefix (e.g., @john)
• Telegram user IDs: Numeric only (e.g., 123456789)

How to reset

Delete the identity map file:

rm ~/.clawdis/identity-map.json

Sessions will revert to provider-specific IDs on next message.