Skip to main content
The ironclaw pairing command manages direct message (DM) pairing requests for messaging channels like Telegram and Slack. Pairing allows you to approve or deny incoming messages from unknown senders.

​
Usage

ironclaw pairing <subcommand>

​
Subcommands

​
list

List pending pairing requests for a channel. 
ironclaw pairing list <channel> [OPTIONS]
​
channel
string
required
Channel name (e.g., telegram, slack)
​
--json
boolean
Output results in JSON format
Example: 
# List Telegram pairing requests
ironclaw pairing list telegram

# Output as JSON
ironclaw pairing list telegram --json
Example output: 
Pending pairing requests for telegram:

  Code: ABC12345
  From: @john_doe (User ID: 123456789)
  Received: 2025-03-04 10:30:42
  Message: "Hi, I'd like to connect with IronClaw"

  Code: XYZ67890
  From: @jane_smith (User ID: 987654321)
  Received: 2025-03-04 11:15:18
  Message: "Hello!"

Use 'ironclaw pairing approve <channel> <code>' to approve a request.

​
approve

Approve a pairing request by code. 
ironclaw pairing approve <channel> <code>
​
channel
string
required
Channel name (e.g., telegram, slack)
​
code
string
required
Pairing code to approve (e.g., ABC12345)
Example: 
# Approve a Telegram pairing request
ironclaw pairing approve telegram ABC12345

# Approve a Slack pairing request
ironclaw pairing approve slack XYZ67890
Example output: 
✓ Approved pairing request ABC12345 for telegram
  From: @john_doe (123456789)
  
The user can now send direct messages to your IronClaw agent.

​
How DM Pairing Works

IronClaw’s DM pairing system protects you from unsolicited messages while allowing approved users to communicate with your agent.
1

Pairing request initiated

When an unknown user sends a message to your IronClaw agent through a channel (Telegram, Slack, etc.), the message is queued and a pairing code is generated.
2

User receives pairing code

The sender receives a message with a unique pairing code and instructions to wait for approval:
Your message has been queued for approval.
Pairing code: ABC12345

Please wait for the agent owner to approve your request.
3

Owner lists pending requests

The IronClaw owner runs ironclaw pairing list <channel> to see pending requests with codes, user information, and original messages.
4

Owner approves or ignores

The owner can:
  • Approve: Run ironclaw pairing approve <channel> <code> to allow future messages
  • Ignore: Leave the request pending (it will expire after a configurable timeout)
5

User can now communicate

Once approved, the user can freely send messages to the IronClaw agent. The queued message is also delivered.

​
Pairing Policies

Channels can be configured with different pairing policies:

Strict (default)

All unknown senders must be explicitly approved via pairing codes

Allow all

Accept messages from anyone without pairing (not recommended for privacy)

Allowlist only

Only accept messages from a pre-configured list of user IDs

Denylist

Accept all messages except from blocked user IDs
Pairing policies are configured per-channel in the onboarding wizard or via environment variables. See the channel configuration guide for details.

​
Pairing Expiration

Pairing requests expire after a configurable timeout (default: 24 hours). Expired requests are automatically removed from the pending list. To adjust expiration: 
# Set expiration to 48 hours (in seconds)
export TELEGRAM_PAIRING_EXPIRATION_SECS=172800

​
Examples

​
Approve a Telegram DM request

# List pending requests
ironclaw pairing list telegram

# Output:
#   Code: ABC12345
#   From: @alice (123456789)
#   Message: "Hi! I need help with my code"

# Approve the request
ironclaw pairing approve telegram ABC12345

# Alice can now send messages freely

​
Monitor pairing requests in JSON

# Export pending requests to JSON
ironclaw pairing list telegram --json > pending.json

# Process with jq
ironclaw pairing list telegram --json | jq '.[] | {code, user_id, message}'

​
Batch approval workflow

#!/bin/bash
# List all pending Telegram requests
codes=$(ironclaw pairing list telegram --json | jq -r '.[].code')

# Review and approve each
for code in $codes; do
  echo "Approve $code? (y/n)"
  read -r response
  if [ "$response" = "y" ]; then
    ironclaw pairing approve telegram "$code"
  fi
done

​
Troubleshooting

If ironclaw pairing list shows no requests:
  • Ensure the channel is running and connected
  • Verify the channel is configured with pairing enabled (not allow_all policy)
  • Check if requests have expired (default: 24 hours)
  • Ensure messages are being sent to the correct bot/channel
If approval fails with “code not found”:
  • Verify the code is correct (codes are case-sensitive)
  • The request may have expired (default: 24 hours)
  • List current requests again: ironclaw pairing list <channel>
If messages are still blocked after approval:
  1. Restart the IronClaw agent to reload pairing state
  2. Verify the channel is running: ironclaw status
  3. Check the channel policy: ironclaw config get channels.<channel>.pairing_policy
  4. Ensure no denylist is blocking the user ID
To disable pairing and accept all messages (not recommended):
# For Telegram
export TELEGRAM_PAIRING_POLICY=allow_all

# Restart IronClaw
ironclaw service restart
Or reconfigure during onboarding:
ironclaw onboard --channels-only

Telegram setup

Configure Telegram channel with pairing

Channels overview

Learn about IronClaw’s multi-channel architecture

ironclaw status

Check channel connection status

Configuration

Channel environment variables

Build docs developers (and LLMs) love

Get started for freeTalk to us