Webchat API Reference

Common Behavior

• CORS is enforced via webchat allowlist logic.
• OPTIONS is supported for preflight on each endpoint.
• JSON responses are returned for success and errors.

POST /api/webchat/init

Initialize or restore a visitor session.

Important: call GET /api/webchat/config first and pass initChallenge.token into init.

Rules

• At least one of publicKey, channelId, or botId is required.
• initChallenge is required and single-use within replay window.
• visitorContext and contact are both accepted for enrichment.
• botSignals.honeypot must remain empty.
• botSignals.elapsedMs is used for init bot-mitigation checks.

Error responses

• 400 invalid request
• 403 origin not allowed
• 404 active web channel not found
• 429 rate limit exceeded
• 500 server failure

GET /api/webchat/config

• Query requires one of publicKey or channelId or botId.
• Returns safe widget config plus signed init challenge.
• Also returns telemetry taxonomy and sample-rate metadata.

POST /api/webchat/message

• Requires signed session token and message body.
• Accepts metadata fields such as pageUrl, referrer, locale, pageTitle, origin, and utm values.
• meta.mode can be flow, ai, or safe_fallback.
• When AI engine is unavailable, safe fallback text is returned.

Error responses

• 400 invalid request
• 401 invalid session token
• 403 origin not allowed
• 404 invalid conversation ownership
• 429 rate limit exceeded
• 503 upstream AI unavailable
• 500 server failure

POST /api/webchat/events

Ingest widget telemetry events.

Supported types: OPEN, CLOSE, TYPING, ERROR, MESSAGE.

• Returns sampled status and sample rate in success response.
• Validates token, origin policy, and site ownership.