Channels

Channels let you DM your heroes from Telegram or Discord. Send prompts, approve plans, grant permissions, and get replies — all from your phone or desktop messaging app. Each DM conversation binds to a specific hero, so messages route directly to the right agent.

How It Works

AgentCraft runs its own Telegram and Discord adapters on the server. You provide a bot token, DM the bot /pair, and approve the pairing request in the AgentCraft UI. Once bound, that DM becomes a two-way channel to your hero:

• You send a message — it arrives as a prompt in the hero's session
• The hero finishes — the final reply is sent back to your DM
• The hero needs approval — you get interactive buttons (approve/deny) directly in the DM

Bindings are attached to a heroId, not a session ID, so they persist across hero restarts.

Supported Providers

Setting Up Telegram

Step 1: Create a Telegram Bot

1. Open Telegram and find BotFather
2. Send /newbot
3. Choose a display name (e.g., "My AgentCraft Bot")
4. Choose a username ending in bot (e.g., my_agentcraft_bot)
5. BotFather replies with a token — copy it

Step 2: Configure the Token in AgentCraft

1. Open the Alliance Panel in the AgentCraft UI
2. Click the Channels card
3. In the Channels modal, paste your Telegram bot token into the Telegram field
4. Click Set — AgentCraft connects to the Telegram API and starts polling for messages

The token is saved to ~/.agentcraft/channels/state.json.

Step 3: Pair Your Account

1. Open Telegram and DM /pair to your bot
2. The bot replies with a 6-digit pairing code
3. In AgentCraft, open the Side Panel for the hero you want to bind
4. A pending pairing request appears with the code — click Approve

The binding is now active. Messages you send to the bot go directly to that hero.

Setting Up Discord

Step 1: Create a Discord Bot

1. Go to the Discord Developer Portal
2. Click New Application and give it a name
3. Go to the Bot section in the left sidebar
4. Click Reset Token and copy the token

Step 2: Enable Required Intents

Still in the Developer Portal, in your bot's Bot settings:

1. Scroll to Privileged Gateway Intents
2. Enable Message Content Intent
3. Save changes

Step 3: Configure the Token in AgentCraft

1. Open the Alliance Panel in the AgentCraft UI
2. Click the Channels card
3. In the Channels modal, paste your Discord bot token into the Discord field
4. Click Set — AgentCraft connects via discord.js and starts listening for DMs

The token is saved to ~/.agentcraft/channels/state.json.

Step 4: Pair Your Account

1. Open Discord and DM /pair to your bot
2. The bot replies with a 6-digit pairing code
3. In AgentCraft, open the Side Panel for the hero you want to bind
4. A pending pairing request appears with the code — click Approve

The binding is now active.

What You Can Do Over a Channel

Once paired, your DM becomes a full control surface for the bound hero:

When the hero finishes its turn, the final assistant reply is sent back to your DM automatically.

If the hero is busy when your message arrives, it's queued server-side and delivered when the hero returns to idle.

UI Indicators

Alliance Panel

The Channels card in the Alliance Panel shows:

• Number of configured providers
• Number of pending pairing requests
• Number of active bindings

Side Panel

For each hero, the Side Panel shows:

• Pending Pairings — Pairing requests waiting for approval, with the 6-digit code
• Bound Channels — Active bindings with a remove button

Chat View

Messages that arrived over a channel display a source pill (e.g., "Telegram" or "Discord") so you can distinguish them from messages typed in the AgentCraft composer.

Managing Bindings

Remove a Binding

Open the hero's Side Panel, find the binding under Bound Channels, and click the remove button. The DM sender will no longer be able to reach that hero.

Rebind to a Different Hero

Remove the existing binding, then DM /pair again. Approve the new pairing request from the target hero's Side Panel.

Security

• Only private DMs are accepted — group chats, guild channels, and threads are ignored
• Both the sender ID and conversation ID must match the binding for a message to be routed
• Action buttons are validated against both the action token and the binding identity
• Pairing requests expire after 10 minutes
• Action button tokens expire after 20 minutes
• Bot tokens are stored separately from shared settings, in ~/.agentcraft/channels/state.json

Eligible Heroes

Channels are available for internal heroes (Claude Code, Codex, OpenCode, Cursor). Web heroes and OpenClaw-backed heroes are not eligible.

Persistence

Channel state persists in ~/.agentcraft/channels/state.json: