Web / API Access (WebChat) Guide

MateClaw's WebChat channel lets external websites reach the conversation engine over plain HTTP / SSE, with no JWT. Visitor identity is isolated under a shared API Key via visitorId + visitorToken (HMAC-signed).

There are two integration paths:

Embeddable widget — drop in one JS file, call init(...) once, and a chat bubble appears in the corner. Fastest to ship; ideal for marketing sites / landing-page support.
Custom HTTP / SSE integration — call the REST + SSE endpoints below and render your own UI. For deeply customized experiences.

The widget is a zero-dependency browser library shipped in both UMD (<script> tag) and ESM (npm) formats.

Option 1: script tag (UMD)

html

<script src="https://<your-deployment>/mateclaw-webchat.umd.js"></script>
<script>
  MateClawWebChat.init({
    apiKey: 'your-channel-api-key',   // from the channel edit page
    server: 'https://<your-deployment>',
    title: 'Support',
    placeholder: 'Type a message...'
  })
</script>

Option 2: npm (ESM)

bash

npm install @mateclaw/webchat

import { init } from '@mateclaw/webchat'

init({ apiKey: 'your-channel-api-key', server: 'https://<your-deployment>' })

Config options

Field	Required	Default	Notes
`apiKey`	yes	—	Channel API Key
`server`	yes	—	MateClaw server URL (no trailing slash)
`position`	no	`bottom-right`	Bubble position: `bottom-right` / `bottom-left`
`primaryColor`	no	`#D97757`	Primary color (any CSS color)
`title`	no	`MateClaw`	Panel title
`placeholder`	no	`Type a message...`	Input placeholder

Behavior

The visitor ID is generated on first open and persisted in localStorage (key mc-webchat-visitor), then reused — you don't manage it yourself.
The panel is themed entirely through CSS variables (--mc-primary / --mc-bg-elevated / ...); the host page can override them under :root.
The widget consumes the /stream SSE protocol described below. For richer interactions (session list, attachments, revocation), call the HTTP endpoints directly and build your own UI.

Custom integration: basics

Base URL: https://<your-MateClaw-deployment>/api/v1/channels/webchat
Auth: every endpoint requires the header X-MC-Key: <API Key> (from the channel edit page).
Session-management endpoints additionally require X-MC-Visitor-Token: <HMAC> (issued by the server and returned on the first /stream call).
Response envelope: R<T> → {"code": 200, "msg": "...", "data": T}; anything other than 200 is an error.
Charset: UTF-8. The SSE stream uses text/event-stream; charset=UTF-8.

Endpoint list

Method	Path	Auth	Purpose
POST	`/stream`	API Key	SSE streaming chat (issues visitorToken)
GET	`/config`	API Key	Get channel config (title/placeholder/...)
POST	`/sessions`	API Key	Explicitly create an empty session thread
GET	`/sessions`	+ visitorToken	List sessions (excludes archived by default)
GET	`/sessions/page`	+ visitorToken	Paginated + keyword search
PUT	`/sessions/title`	+ visitorToken	Rename
PUT	`/sessions/pinned`	+ visitorToken	Pin / unpin
PUT	`/sessions/archive`	+ visitorToken	Archive / unarchive
DELETE	`/sessions`	+ visitorToken	Delete
POST	`/sessions/stop`	+ visitorToken	Stop an in-flight stream
POST	`/sessions/regenerate`	+ visitorToken	Regenerate the last assistant reply
POST	`/sessions/approve`	+ visitorToken	Approve a pending tool approval and replay (SSE)
POST	`/sessions/deny`	+ visitorToken	Deny a pending tool approval (synchronous JSON)
GET	`/sessions/messages`	+ visitorToken	Message list (paginated)
POST	`/upload`	+ visitorToken	Upload an attachment (returns fileId)
GET	`/files`	+ visitorToken	Download a file (uploaded or agent-generated)

Admin-level (require a MateClaw JWT, outside the permitAll set above):

Method	Path	Purpose
POST	`/api/v1/admin/webchat/revoked-visitor`	Revoke a visitor's management token
DELETE	`/api/v1/admin/webchat/revoked-visitor`	Un-revoke

In the admin console, the "Conversations" list hides WebChat visitor sessions from regular admins by default — only a global admin sees them. This is a cross-workspace isolation and visitor-privacy guard.

Auth flow

text

┌──────────┐  POST /stream {visitorId:"v1", message:"hi"}
│  Client  │ ─────────────────────────────────────────────► ┌──────────┐
└──────────┘                                                  │ MateClaw │
   ▲                                                          └──────────┘
   │  SSE meta event: {sessionId, conversationId, visitorToken}
   │  SSE content_delta events: {text}
   │  SSE done event
   └─────────────────────────────────────────────────────────
                                                              │
┌──────────┐  GET /sessions X-MC-Visitor-Token: <visitorToken>│
│  Client  │ ─────────────────────────────────────────────► │
└──────────┘ ◄──── 200 {code:200, data:[...]}                │

visitorToken is valid for 7 days by default; re-issue it through any /stream call once it expires. Every /stream call (even with a still-valid token) returns a fresh token in the meta event — the client should keep updating its stored copy.

Error codes

HTTP	When
400	Invalid parameter (visitorId / sessionId charset, title length, etc.)
401	Invalid API Key / missing, expired, or revoked visitorToken
404	The given sessionId does not exist or does not belong to the visitor
409	More than 5 inactive empty sessions

The error message is in R.msg and can be shown directly to the user.

SSE event protocol

/stream and /sessions/regenerate return text/event-stream:

event: meta
data: {"sessionId":"s1","conversationId":"webchat:abc123:v1:s1","visitorToken":"xxx.yyy"}

event: phase
data: {"phase":"planning","timestamp":1716700000000}

event: tool_start
data: {"tool":"web_search"}

event: tool_end
data: {"tool":"web_search","success":true}

event: plan
data: {"steps":["search the web","summarize"]}

event: content_delta
data: {"text":"He"}

event: content_delta
data: {"text":"llo"}

event: thinking_delta
data: {"text":"..."}    (optional, reasoning trace)

event: done
data: {"status":"completed"}

event: error
data: {"message":"..."}  (on failure)

The SSE spec requires clients to ignore unknown event types. The server may emit internal events prefixed with an underscore (e.g. _usage_final); these carry no contract for visitors and can be safely ignored.

Optional real-time progress events

phase / tool_start / tool_end / plan are optional events — used to show an "AI is typing…" bubble, tool-execution badges ("Searching…"), or a Plan-and-Execute step checklist in your SDK. The SDK can ignore them all and still render the full reply from content_delta alone.

Event	Triggered when	Data fields
`phase`	the agent enters a new execution phase (planning / generating / summarizing / ...)	`phase`, `timestamp`
`tool_start`	the agent calls a tool	`tool` (tool name)
`tool_end`	a tool call finishes	`tool`, `success`
`plan`	a Plan-and-Execute agent breaks work into steps	`steps` (string array)

Note: tool_start / tool_end carry only the tool name, never the call arguments or results — agent tool calls may involve PII (file paths, user queries, credentials), which would leak if forwarded to a third-party website frontend. The SDK should map tool names to localized labels (web_search → "Searching…").

File upload / download

POST /upload (multipart): returns {fileId, fileName, contentType, size}.
Add the fileId to the attachmentIds array in the body of the next /stream call. Unknown / expired / foreign fileIds are silently dropped (only the text part is sent, no error).
The agent reads server-side files directly; the fileUrl in a message is a relative download path (/api/v1/channels/webchat/files?storedName=...) — the client appends auth headers to download.
Agent-generated files (PDF/DOCX/...) appear in assistant replies as /api/v1/files/generated/<uuid> URLs, downloadable without auth, with a 7-day TTL.

Session lifecycle: pin / archive / delete

Pin (PUT /sessions/pinned): sorted first in the /sessions list.
Archive (PUT /sessions/archive): a soft close — the thread stays in the DB (history queryable, addressable by sessionId, files downloadable) but is hidden from /sessions by default (pass includeArchived=true to return it), and no longer counts against the "≤ 5 inactive empty sessions" quota.
Delete (DELETE /sessions): permanent, unrecoverable.

Each session returned by /sessions includes: sessionId, title, lastActiveTime, messageCount, pinned, archived, streamStatus (running / idle).

Tool approval resolve (API-Key channel)

When an agent bound to WebChat calls a tool protected by Tool Guard, that turn suspends waiting for approval. The visitor can approve or deny it in-session instead of letting it time out.

Approve POST /sessions/approve — with sessionId + pendingId. Auth reuses visitorToken + conversation ownership; the pendingId is strictly validated to belong to this session (else 404), closing a cross-visitor IDOR. Approving replays the suspended tool call and resumes as SSE.
Deny POST /sessions/deny — with sessionId + pendingId, returns synchronous JSON, no replay.

Both broadcast a tool_approval_resolved SSE event (see Optional realtime progress events above) so the SDK / frontend clears the approval banner in real time.

Whether an approval appears depends on whether the agent's bound Tool Guard rules set require_approval for some tool. Get pendingId from the tool_approval_requested event.

bash

# Approve (resumes as SSE)
curl -N -X POST "https://mate.example.com/api/v1/channels/webchat/sessions/approve" \
  -H "X-MC-Key: <API Key>" -H "X-Visitor-Token: <visitorToken>" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"s1","pendingId":"<pendingId>"}'

# Deny (synchronous JSON)
curl -X POST "https://mate.example.com/api/v1/channels/webchat/sessions/deny" \
  -H "X-MC-Key: <API Key>" -H "X-Visitor-Token: <visitorToken>" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"s1","pendingId":"<pendingId>"}'

visitorToken revocation (admin)

A visitor abusing the channel? An admin calls:

bash

curl -X POST https://mate.example.com/api/v1/admin/webchat/revoked-visitor \
  -H "Authorization: Bearer <admin JWT>" \
  -H "Content-Type: application/json" \
  -d '{"channelId":123, "visitorId":"v1", "reason":"abuse"}'

After revocation, all of that visitor's management endpoints return 401 (/stream is unaffected and can re-issue a fresh token). Revocation state is briefly cached, so under a multi-instance deployment it takes up to ~10 minutes to fully propagate. Un-revoke via DELETE on the same endpoint.

curl examples

Step 1: send the first message

bash

curl -N -X POST https://mate.example.com/api/v1/channels/webchat/stream \
  -H "X-MC-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"visitorId":"v1","message":"hi"}'

Save the visitorToken and sessionId from the meta event.

Step 2: list sessions

bash

curl https://mate.example.com/api/v1/channels/webchat/sessions?visitorId=v1 \
  -H "X-MC-Key: your-api-key" \
  -H "X-MC-Visitor-Token: <from step 1>"

Step 3: upload an attachment and send

bash

# upload
curl -X POST https://mate.example.com/api/v1/channels/webchat/upload \
  -H "X-MC-Key: your-api-key" \
  -H "X-MC-Visitor-Token: <token>" \
  -F "visitorId=v1" \
  -F "file=@report.pdf"
# returns {"fileId":"abc-uuid", ...}

# send a message with the attachment
curl -N -X POST https://mate.example.com/api/v1/channels/webchat/stream \
  -H "X-MC-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"visitorId":"v1","sessionId":"<sid>","message":"take a look at this report","attachmentIds":["abc-uuid"]}'

Limits

Inactive empty sessions per visitor ≤ 5 (creation is rejected past 5 — send a message or delete an old session first)
Upload: single file ≤ configured cap, extension + MIME dual whitelist; ≤ 50 files / 200 MB per session (configurable)
visitorToken expires in 7 days; agent-generated file URLs have a 7-day TTL
Currently a single-instance deployment (staging registry + streamTracker are both in-memory). Multi-instance support is on the roadmap.

Upstream epic issue: https://github.com/mateaix/mateclaw/issues/355

Web / API Access (WebChat) Guide ​

Embeddable widget (mateclaw-webchat) ​

Custom integration: basics ​

Endpoint list ​

Auth flow ​

Error codes ​

SSE event protocol ​

Optional real-time progress events ​

File upload / download ​

Session lifecycle: pin / archive / delete ​

Tool approval resolve (API-Key channel) ​

visitorToken revocation (admin) ​

curl examples ​

Limits ​

Related ​

Web / API Access (WebChat) Guide

Embeddable widget (mateclaw-webchat)

Custom integration: basics

Endpoint list

Auth flow

Error codes

SSE event protocol

Optional real-time progress events

File upload / download

Session lifecycle: pin / archive / delete

Tool approval resolve (API-Key channel)

visitorToken revocation (admin)

curl examples

Limits

Related