HTTP API
Public widget HTTP surface and response envelope. Dashboard routes are internal — not a partner API.
Scope
The public HTTP API is the widget surface under /api/widget.js and /api/v1/widget/**. Prefer the documented JavaScript Widget API (CanWeChat.open, identify, send, …) from host pages — it wraps these routes safely.
Dashboard and workspace routes (inbox, integrations, billing, webhook-relay admin, team, …) are session-authenticated internals for canwechat.dev. They are not documented here and must not be treated as a stable partner API.
Base URL
Production host: https://canwechat.dev.
Response envelope
Successful responses return { ok: true, data }. Failures return { ok: false, error: { code, message, fieldErrors? } } with an appropriate HTTP status.
{
"ok": true,
"data": { "id": "conv_..." }
}Public widget routes
Loader: GET /api/widget.js. Config, session, conversations, messages, read receipts, and the visitor socket live under /api/v1/widget/**. Auth is the public site key plus visitor session — never bot tokens.
OpenAPI
Machine-readable public OpenAPI 3.1: https://canwechat.dev/openapi.json. It lists only the public widget paths and the outbound webhook event schema.
Idempotency
Visitor message POSTs accept an idempotencyKey. Retries with the same key return the original message instead of duplicating sends.
CORS
Widget endpoints allow browser origins that match the site’s allowed domains. openapi.json is publicly readable with CORS * for tooling.