Chat & Messaging

This guide covers how messages flow through MateClaw, from user input to agent response, including SSE streaming and conversation history.

Message Flow

User Input (Web / IM Channel)
        │
        ▼
┌───────────────┐
│  REST API      │  POST /api/v1/chat/{agentId}/message
└───────┬───────┘
        │
        ▼
┌───────────────┐
│  Conversation  │  Load or create conversation, append user message
│  Manager       │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│  Agent Engine  │  ReAct loop / Plan-and-Execute
└───────┬───────┘
        │
        ▼
┌───────────────┐
│  SSE / Direct  │  Stream tokens or return complete response
│  Response      │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│  Persist       │  Save assistant message to database
└───────────────┘

Sending a Message

REST Endpoint

curl -X POST http://localhost:18088/api/v1/chat/1/message \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What is the current time in Tokyo?",
    "conversationId": "conv-abc123"
  }'

If conversationId is omitted, a new conversation is created automatically.

Response

{
  "code": 200,
  "data": {
    "messageId": "msg-xyz789",
    "conversationId": "conv-abc123",
    "content": "The current time in Tokyo is 2025-03-15 23:30:22 JST.",
    "role": "assistant"
  }
}

SSE Streaming

For real-time token-by-token responses, use the SSE endpoint:

Connecting

const eventSource = new EventSource(
  '/api/v1/chat/1/stream?conversationId=conv-abc123',
  { headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN' } }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.content);  // Partial response token
};

eventSource.onerror = (error) => {
  console.error('SSE connection error', error);
  eventSource.close();
};

Event Types

The SSE stream emits these event types:

Event	Description
message	A chunk of the assistant's response text
tool_call	The agent is invoking a tool (includes tool name and parameters)
tool_result	The tool returned a result
thinking	The agent's internal reasoning step (ReAct thought)
plan	A plan was generated (Plan-and-Execute mode)
error	An error occurred during processing
done	The response is complete

Example SSE Stream

event: thinking
data: {"content": "The user wants the current time in Tokyo. I should use DateTimeTool."}

event: tool_call
data: {"tool": "DateTimeTool", "input": {"timezone": "Asia/Tokyo"}}

event: tool_result
data: {"tool": "DateTimeTool", "output": "2025-03-15T23:30:22"}

event: message
data: {"content": "The current time in Tokyo is "}

event: message
data: {"content": "2025-03-15 23:30:22 JST."}

event: done
data: {}

File & Directory Upload

Upload Methods

Method	Description
Click	Click the attachment button to select files
Paste	Paste files from clipboard (Ctrl+V / Cmd+V)
Drag & Drop	Drag files or folders into the chat area

Drag & Drop

When dragging files or folders into the chat area, a translucent overlay appears. On drop:

• Files — Uploaded to the server as attachments
• Folders (Electron) — Local absolute path recorded as reference; Agent accesses files via ReadFileTool / ShellExecuteTool
• Folders (Web) — Directory recursively expanded, all files uploaded individually

Upload Limits

Setting	Default
Max file size	100 MB
Max request size	200 MB
File types	All (*/*)

Conversation Management

Data Model

mate_conversation

Column	Description
id	Conversation ID
user_id	Owner
agent_id	Associated agent
title	Conversation title (auto-generated from first message)
create_time	When the conversation started
update_time	Last activity time

mate_message

Column	Description
id	Message ID
conversation_id	Parent conversation
role	user, assistant, system, tool
content	Message text
tool_calls	JSON array of tool calls (for assistant messages)
tool_call_id	Associated tool call ID (for tool messages)
create_time	Timestamp

API Endpoints

List conversations:

curl http://localhost:18088/api/v1/conversations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get conversation history:

curl http://localhost:18088/api/v1/conversations/conv-abc123/messages \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Delete a conversation:

curl -X DELETE http://localhost:18088/api/v1/conversations/conv-abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Context Window

MateClaw automatically manages the context window sent to the LLM:

1. System prompt -- Always included
2. Recent messages -- As many recent messages as fit in the model's context limit
3. Tool results -- Included inline with the conversation
4. Memory -- Workspace memory entries if enabled

When the conversation exceeds the context limit, older messages are truncated from the beginning while preserving the system prompt and the most recent exchanges.

Multi-Channel Support

Different channels handle messages using different protocols:

Channel	Protocol	Description
Web	SSE	Real-time streaming output in the browser
DingTalk	Stream (long connection)	Sends and receives messages via DingTalk official SDK WebSocket
Feishu	WebSocket	Sends and receives messages via Feishu long-connection mode
WeCom	Long connection	Sends and receives messages via WeChat Work long-connection mode
Telegram	Long-Polling / Webhook	Default Long-Polling mode, switchable to Webhook
Discord	Gateway WebSocket	Sends and receives messages via JDA library Gateway long connection

All channels share the same Agent engine and tool system -- only the message input/output adapters differ.

Next Steps

• Agent Engine -- How agents process messages
• Memory -- Short-term and long-term memory
• Channels -- Multi-platform message delivery