Channels

MateClaw supports 8 messaging channels through a unified ChannelAdapter interface. Users can interact with agents from the web UI, DingTalk, Feishu (Lark), WeChat Work, Telegram, Discord, QQ, or WeChat.

Architecture

┌──────┐ ┌────────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌───────┐ ┌────┐ ┌──────┐
│ Web  │ │DingTalk│ │Feishu│ │WeCom │ │ TG   │ │Discord│ │ QQ │ │WeChat│
│(SSE) │ │(Stream)│ │(WS)  │ │(Long)│ │(Poll)│ │(GW/WS)│ │    │ │(iLink)│
└──┬───┘ └──┬─────┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬────┘ └─┬──┘ └──┬───┘
   │        │          │        │        │        │        │        │
   └────────┴──────────┴───┬────┴────────┴────────┴────────┴────────┘
                           │
                  ┌────────┴────────┐
                  │ ChannelAdapter   │
                  │  Unified API     │
                  └────────┬────────┘
                           │
                  ┌────────┴────────┐
                  │   Agent Engine   │
                  └─────────────────┘

Supported Channels

Channel	Transport	Status
Web	SSE (Server-Sent Events)	Stable
DingTalk	Stream (recommended) / Webhook	Stable
Feishu (Lark)	WebSocket long connection / Webhook	Stable
WeChat Work (WeCom)	Long connection / Webhook	Stable
Telegram	Long-Polling (default) / Webhook	Stable
Discord	Gateway WebSocket (JDA)	Stable
QQ	WebSocket / Callback	Stable
WeChat Personal (iLink)	HTTP long polling	Experimental

ChannelAdapter Interface

All channel adapters implement the ChannelAdapter interface:

java

public interface ChannelAdapter {
    void onMessage(ChannelMessage message);
    void sendMessage(String channelId, String content);
    String getChannelType();
}

This unified interface means agents do not need to know which channel a message came from -- they receive the same ChannelMessage object regardless of source.

Channel Configuration

Channels are managed through the Channel Management page in the admin UI. Configuration is stored in the mate_channel database table:

Column	Description
`name`	Display name
`type`	Channel type
`agent_id`	Which agent handles messages
`config`	JSON object with channel-specific credentials
`enabled`	Whether the channel is active

Web Channel (SSE)

The web channel is built into MateClaw and requires no external configuration. It uses Server-Sent Events for real-time streaming.

Endpoints

Endpoint	Method	Description
`/api/v1/chat/stream`	POST	SSE stream for messages and responses

SSE Event Format

event: message
data: {"type": "text", "content": "Hello"}

event: tool_call
data: {"type": "tool_call", "tool": "WebSearchTool", "args": {"query": "..."}}

event: done
data: {"type": "done"}

DingTalk

The MateClaw DingTalk adapter supports two connection modes and two message formats:

Connection Mode	Description
Stream (recommended)	WebSocket long connection -- no public IP required; officially recommended by DingTalk
Webhook	HTTP callback -- requires a publicly accessible URL

Message Format	Description
markdown	Standard Markdown messages (default)
card	AI Card with streaming effect -- requires a `card_template_id`; supports typewriter-style output

Step 1: Create a DingTalk Application

Open the DingTalk Developer Console, go to App Development > Internal Apps > Create App
Under App Capabilities > Add Capability, add the Robot capability
Configure the robot settings. Set the message receiving mode to Stream mode, then publish
Under App Release > Version Management, create a new version and save
Under Basic Info > Credentials, get the Client ID (AppKey) and Client Secret (AppSecret)

Step 2: Configure in MateClaw

Add a DingTalk channel via the Channel Management page:

Field	Description
Channel Type	DingTalk
Connection Mode	`stream` (default, recommended) or `webhook`
Client ID	DingTalk application AppKey
Client Secret	DingTalk application AppSecret
Message Type	Message format: `markdown` (default) or `card`
Card Template ID	AI Card template ID (required when message type is `card`)
Agent	The agent to handle messages

Or via API:

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "DingTalk Bot",
    "type": "dingtalk",
    "agentId": 1,
    "config": {
      "connection_mode": "stream",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret",
      "message_type": "markdown"
    },
    "enabled": true
  }'

TIP

Stream mode uses the official DingTalk SDK to establish a WebSocket long connection. No public IP is required, so it is the recommended choice. To enable AI Card streaming, set message_type to card and provide a template ID.

Step 3: Find and Use the Bot

Search for the bot name in DingTalk's message search bar
Find the bot under Features and click to start chatting
Start a conversation

TIP

You can also add the bot to a group chat via Group Settings > Robots > Add Robot.

Webhook URL

https://your-domain/api/v1/channels/webhook/dingtalk

Feishu (Lark)

Feishu supports both Webhook callback and WebSocket long connection modes. WebSocket mode does not require a public IP.

Step 1: Create a Feishu Application

Open Feishu Open Platform, create an enterprise custom app
Under Credentials & Basic Info, get the App ID and App Secret
Under Capabilities, enable the Bot capability

Under Permissions, configure the required permissions. You can use Batch Import with this JSON:

Permissions

json

{
  "scopes": {
    "tenant": [
      "im:chat", "im:message", "im:message.group_msg",
      "im:message.p2p_msg:readonly", "im:resource",
      "contact:user.base:readonly"
    ]
  }
}

Under Events & Callbacks, select WebSocket Long Connection mode (no public IP required)
Add an event subscription for Receive Messages v2.0
Under App Release, create a version and publish

Step 2: Configure in MateClaw

Field	Description
Channel Type	Feishu
App ID	Feishu App ID
App Secret	Feishu App Secret
Verification Token	Event subscription Verification Token (optional)
Encrypt Key	Event subscription Encrypt Key (optional)

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Feishu Bot",
    "type": "feishu",
    "agentId": 1,
    "config": {
      "appId": "cli_your_app_id",
      "appSecret": "your-app-secret",
      "verificationToken": "your-verification-token",
      "encryptKey": "your-encrypt-key"
    },
    "enabled": true
  }'

Step 3: Find and Use the Bot

In Feishu Workbench, click Add to Favorites, search for the bot and add it
Double-click the bot to start chatting

Webhook URL

https://your-domain/api/v1/channels/webhook/feishu

WeChat Work (WeCom)

Step 1: Create a WeCom Bot

Visit WeChat Work to register or log in
In the Workbench, go to Smart Robot > Create Robot, select API Mode > Long Connection
Get the Bot ID and Secret

Step 2: Configure in MateClaw

Field	Description
Channel Type	WeCom
Corp ID	Enterprise ID
Agent ID	Application Agent ID
Secret	Application Secret
Token	Message receiving Token
Encoding AES Key	Message encryption key

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "WeCom Bot",
    "type": "wecom",
    "agentId": 1,
    "config": {
      "corpId": "your-corp-id",
      "wecomAgentId": "1000002",
      "secret": "your-secret",
      "token": "your-token",
      "encodingAesKey": "your-encoding-aes-key"
    },
    "enabled": true
  }'

Step 3: Start Chatting

Find the bot in WeChat Work and start chatting.

Start Chat

Webhook URL

https://your-domain/api/v1/channels/webhook/wecom

The MateClaw Telegram adapter supports two connection modes:

Mode	Description	Best For
Long-Polling (default)	Continuously polls for messages via `getUpdates`	No public IP needed; ideal for development and internal deployments
Webhook	Telegram pushes messages to your server	Requires a publicly accessible HTTPS URL

Long-Polling is used by default and requires no webhook setup. If you provide a webhook_url in the configuration, the adapter automatically switches to Webhook mode.

Step 1: Create a Telegram Bot

Search for @BotFather in Telegram (look for the official blue verification badge)
Send /newbot and follow the prompts to create a new bot
Copy the Bot Token returned by BotFather

Step 2: Configure in MateClaw

Field	Description
Channel Type	Telegram
Bot Token	Token from @BotFather
Webhook URL	Optional -- when set, the adapter switches to Webhook mode
Polling Timeout	Long-Polling timeout in seconds (default: 20)
HTTP Proxy	Optional proxy address for restricted networks (e.g. `http://127.0.0.1:7890`)
Show Typing	Whether to display a "typing" indicator while the agent is working (enabled by default)

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Telegram Bot",
    "type": "telegram",
    "agentId": 1,
    "config": {
      "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "show_typing": true,
      "polling_timeout": 20
    },
    "enabled": true
  }'

Step 3: Start Chatting

Long-Polling mode (default): After saving and enabling the channel, the bot automatically begins polling for messages. Simply search for your bot in Telegram and send a message.

Webhook mode: Set webhook_url in the configuration (e.g. https://your-domain/api/v1/channels/webhook/telegram) and the system will automatically register the webhook with Telegram.

TIP

Long-Polling mode has built-in exponential backoff reconnection (2s to 30s) and recovers automatically after network interruptions
A "typing" indicator is shown continuously (refreshed every 4 seconds) until the reply is complete
Markdown formatting automatically falls back to plain text if parsing fails
Users in China may need to configure http_proxy to access the Telegram API

Discord

The MateClaw Discord adapter is built on JDA (Java Discord API) and connects to Discord via the Gateway WebSocket. JDA handles automatic reconnection internally, so there is no need to manage the connection lifecycle manually.

Step 1: Create a Discord Bot

Open the Discord Developer Portal
Create a new Application
Go to Bot in the sidebar, create a Bot and copy the Token
Enable Message Content Intent and grant Send Messages and Attach Files permissions
Under OAuth2 > URL Generator, select bot scope, generate an invite link, and add the bot to your server

Step 2: Configure in MateClaw

Field	Description
Channel Type	Discord
Bot Token	Bot Token (required)
Accept Bot Messages	Whether to process messages from other bots (disabled by default)
HTTP Proxy	Optional proxy address for restricted networks

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Discord Bot",
    "type": "discord",
    "agentId": 1,
    "config": {
      "bot_token": "your-bot-token",
      "accept_bot_messages": false
    },
    "enabled": true
  }'

Step 3: Start Chatting

After saving and enabling the channel, the bot connects to Discord automatically via Gateway WebSocket. Mention the bot with @Bot or send a direct message in any server the bot has joined.

TIP

The Discord adapter receives messages through Gateway WebSocket -- no Webhook URL or Interactions Endpoint configuration is needed
Long replies (over 2000 characters) are automatically split into multiple messages while preserving code block integrity
Images and other media are uploaded via the REST API; uploads that fail are automatically downgraded to text links
A message deduplication mechanism (LRU cache of 500 entries) prevents duplicate processing during reconnections
Users in China may need to configure http_proxy to access the Discord API

QQ

Step 1: Create a QQ Bot

Open QQ Open Platform and create a bot application
Under Callback Configuration, enable C2C Message Event and Group Message AT Event
Under Development Management, get the AppID and AppSecret

Step 2: Configure in MateClaw

Field	Description
Channel Type	QQ
App ID	QQ Bot App ID
App Secret	QQ Bot AppSecret

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "QQ Bot",
    "type": "qq",
    "agentId": 1,
    "config": {
      "appId": "your-app-id",
      "appSecret": "your-app-secret"
    },
    "enabled": true
  }'

WeChat Personal (iLink)

WARNING

WeChat Personal Bot (iLink protocol) is currently in beta. Access must be applied for before use.

How It Works

Login: Scan a QR code to authorize on first use. The token is persisted automatically.
Receiving: HTTP long polling for new messages (text, images, voice, files).
Sending: Reply via the sendmessage API (text only).

Setup

Add a WeChat Personal channel in MateClaw Channel Management
Click Get Login QR Code and scan with your phone
Once authorized, the token is filled automatically -- save to activate

API Configuration

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "WeChat Personal",
    "type": "weixin",
    "agentId": 1,
    "config": {
      "botToken": "your-bot-token"
    },
    "enabled": true
  }'

Channel Management API

bash

# List all channels
curl http://localhost:18088/api/v1/channels \
  -H "Authorization: Bearer <token>"

# Enable/disable a channel
curl -X PUT "http://localhost:18088/api/v1/channels/1/toggle?enabled=true" \
  -H "Authorization: Bearer <token>"

# Delete a channel
curl -X DELETE http://localhost:18088/api/v1/channels/1 \
  -H "Authorization: Bearer <token>"

Session Source Tracking

All channel conversations record their source information. In the session management view and the chat console, each session displays the corresponding channel icon so you can easily identify where a message originated.

Sessions from IM channels (DingTalk, Feishu, WeCom, Telegram, Discord, QQ) belong to the system user and can be viewed and managed from both the session list and the sidebar in the console.

Important Notes

Channels using Webhook mode require an HTTPS address -- use an Nginx reverse proxy with an SSL certificate for production
Channels using Long-Polling, Stream, or Gateway modes (Telegram, DingTalk, Discord) do not require a public IP
Each channel is bound to one agent; different channels can bind to different agents
Channel credentials are encrypted in the database
Users in China may need to configure an HTTP proxy for Telegram and Discord APIs (set the http_proxy field in the channel configuration)

Next Steps

Chat & Messaging -- Deeper look at message flow and SSE
Agent Engine -- How agents process channel messages
Configuration -- Full channel configuration reference

Channels ​

Architecture ​

Supported Channels ​

ChannelAdapter Interface ​

Channel Configuration ​

Web Channel (SSE) ​

Endpoints ​

SSE Event Format ​

DingTalk ​

Step 1: Create a DingTalk Application ​

Step 2: Configure in MateClaw ​

Step 3: Find and Use the Bot ​

Webhook URL ​

Feishu (Lark) ​

Step 1: Create a Feishu Application ​

Step 2: Configure in MateClaw ​

Step 3: Find and Use the Bot ​

Webhook URL ​

WeChat Work (WeCom) ​

Step 1: Create a WeCom Bot ​

Step 2: Configure in MateClaw ​

Step 3: Start Chatting ​

Webhook URL ​

Telegram ​

Step 1: Create a Telegram Bot ​

Step 2: Configure in MateClaw ​

Step 3: Start Chatting ​

Discord ​

Step 1: Create a Discord Bot ​

Step 2: Configure in MateClaw ​

Step 3: Start Chatting ​

QQ ​

Step 1: Create a QQ Bot ​

Step 2: Configure in MateClaw ​

WeChat Personal (iLink) ​

How It Works ​

Setup ​

API Configuration ​

Channel Management API ​

Session Source Tracking ​

Important Notes ​

Next Steps ​

Channels

Architecture

Supported Channels

ChannelAdapter Interface

Channel Configuration

Web Channel (SSE)

Endpoints

SSE Event Format

DingTalk

Step 1: Create a DingTalk Application

Step 2: Configure in MateClaw

Step 3: Find and Use the Bot

Webhook URL

Feishu (Lark)

Step 1: Create a Feishu Application

Step 2: Configure in MateClaw

Step 3: Find and Use the Bot

Webhook URL

WeChat Work (WeCom)

Step 1: Create a WeCom Bot

Step 2: Configure in MateClaw

Step 3: Start Chatting

Webhook URL

Telegram

Step 1: Create a Telegram Bot

Step 2: Configure in MateClaw

Step 3: Start Chatting

Discord

Step 1: Create a Discord Bot

Step 2: Configure in MateClaw

Step 3: Start Chatting

QQ

Step 1: Create a QQ Bot

Step 2: Configure in MateClaw

WeChat Personal (iLink)

How It Works

Setup

API Configuration

Channel Management API

Session Source Tracking

Important Notes

Next Steps