Channels Overview

Channels are messaging platform integrations that allow your agents to communicate with users through external services. The gateway loads and initializes channel bridges during startup, polling for messages and routing them to bound agents.

Available Channels

Channel	Status	Features
Telegram	Stable	Bot, voice messages, bot commands, pairing codes
Discord	Stable	Bot, server integration, Message Content Intent

Architecture

                    ┌──────────────────────┐
                    │   Moxxy Gateway      │
                    │   (port 3000)        │
                    └──────────┬───────────┘
                               │
                    ┌──────────┴───────────┐
                    │  Channel Bridges      │
                    │  (loaded at startup)  │
                    └──────────┬───────────┘
                               │
              ┌────────────────┼────────────────┐
              │                                  │
              ▼                                  ▼
    ┌──────────────────┐              ┌──────────────────┐
    │ TelegramTransport│              │ Discord Transport│
    │  (message poll)  │              │  (message poll)  │
    └────────┬─────────┘              └────────┬─────────┘
             │                                  │
             └────────────────┬─────────────────┘
                              │
                    ┌─────────┴──────────┐
                    │  Channel Bindings   │
                    │  (agent ↔ chat)     │
                    └─────────┬──────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │    Agent Pool     │
                    └──────────────────┘

How Channels Work

Message Flow

User sends message on platform
    → Channel transport receives message
    → Gateway looks up channel binding (agent ↔ chat)
    → Message routed to bound agent
    → Agent processes with ReAct loop
    → Response sent back through channel transport
    → User receives reply on platform

Channel Bindings

Each channel connection is bound to a specific agent and external chat. Bindings are stored in the channel_bindings table:

• agent_id -- which agent handles messages for this chat
• channel_id -- which channel configuration to use
• external_chat_id -- the platform-specific chat/group identifier

Pairing

Agents are bound to chats via pairing codes. When a channel is created, a pairing code can be generated. Users send this code in their chat to bind the agent to that conversation.

Channel API

All channel endpoints use the /v1/ prefix on port 3000 with Bearer token authentication (mox_ prefix).

Create a Channel

POST /v1/channels

curl -X POST http://localhost:3000/v1/channels \
  -H "Authorization: Bearer mox_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "telegram",
    "config": {
      "bot_token_secret_ref": "secret-ref-uuid"
    }
  }'

List Channels

GET /v1/channels

curl http://localhost:3000/v1/channels \
  -H "Authorization: Bearer mox_YOUR_TOKEN"

Pair a Chat to an Agent

POST /v1/channels/pair

curl -X POST http://localhost:3000/v1/channels/pair \
  -H "Authorization: Bearer mox_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-uuid",
    "channel_id": "channel-uuid",
    "external_chat_id": "123456789"
  }'

Delete a Channel

DELETE /v1/channels/{id}

curl -X DELETE http://localhost:3000/v1/channels/{id} \
  -H "Authorization: Bearer mox_YOUR_TOKEN"

Channel Credentials

Bot tokens for channels are stored in the vault. Use the vault API to create a secret reference and grant the relevant agent access.

# Store bot token as a vault secret
curl -X POST http://localhost:3000/v1/vault/secrets \
  -H "Authorization: Bearer mox_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "TELEGRAM_BOT_TOKEN",
    "value": "123456:ABC-DEF",
    "policy_label": "channel"
  }'

Multi-Channel Agents

An agent can be bound to multiple channels and chats simultaneously:

# Bind agent to a Telegram chat
curl -X POST http://localhost:3000/v1/channels/pair \
  -H "Authorization: Bearer mox_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent-uuid", "channel_id": "telegram-channel-uuid", "external_chat_id": "111"}'

# Bind same agent to a Discord server
curl -X POST http://localhost:3000/v1/channels/pair \
  -H "Authorization: Bearer mox_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent-uuid", "channel_id": "discord-channel-uuid", "external_chat_id": "222"}'

Troubleshooting

Channel Not Responding

1. Check the gateway is running on port 3000
2. Verify the channel was created successfully: GET /v1/channels
3. Verify channel bindings exist for the chat
4. Check that the bot token in the vault is valid

Messages Not Routing

1. Confirm the pairing between the agent and the external chat ID
2. Check that the agent is running: GET /v1/agents
3. Review gateway logs for routing errors

Bot Token Invalid

1. Regenerate the token on the platform (BotFather for Telegram, Developer Portal for Discord)
2. Update the vault secret with the new token
3. Restart the gateway

Best Practices

1. Use separate agents for different channels or audiences
2. Store tokens in the vault -- never hardcode credentials
3. Monitor channel bindings to ensure correct agent-chat mappings
4. Rotate bot tokens periodically for security