Website Widget reference
Contract identity
| Item | Value |
|---|---|
| Public contract | qanivo.widget.public-api |
| Version | 1.0 |
| Base path | /api/integrations/v1/widget |
| Installation identity | publicSiteKey / siteKey |
| Session access | Short-lived origin- and audience-bound Bearer grant |
| Browser version header | X-Qanivo-Widget-Version: 1.0 |
| Side-effect key | Idempotency-Key |
| SSE resume | Last-Event-ID plus bounded afterSequence |
Route map
All paths are relative to the base path. Session/action routes require the access grant and matching allowed origin unless noted.
| Method | Path | Purpose / status |
|---|---|---|
GET | /config/{publicSiteKey} | Safe public bootstrap/configuration |
POST | /sessions | Create a visitor session |
POST | /sessions/renew | Renew eligible session grant |
POST | /sessions/identify | Associate verified visitor identity |
DELETE | /sessions/identify | Remove visitor identity |
POST | /forms/pre-chat | Authority target; not exposed by the current package/controller surface |
POST | /forms/offline | Authority target; not exposed by the current package/controller surface |
POST | /context/page | Report minimized page context |
POST | /typing | Publish typing state |
POST | /messages | Accept one idempotent message operation |
GET | /messages?afterSequence=... | Read bounded message history |
POST | /messages/{clientOperationId}/retry | Authority target; current package retries POST /messages with the original idempotency key |
GET | /events?afterSequence=... | Open/resume SSE events |
POST | /commands/navigation/{commandId}/acknowledgements | Acknowledge a navigation request |
POST | /commands/screenshots/{requestId}/acknowledgements | Record screenshot consent outcome |
POST | /commands/screenshots/{requestId}/upload | Upload a consented screenshot |
POST | /sessions/close | Close panel or end visitor continuity |
Common headers and errors
Browser requests include an allowed Origin and the contract-version header. Use Authorization: Bearer <YOUR_ACCESS_GRANT> only for scoped session routes. Use Idempotency-Key: <YOUR_OPERATION_ID> for side effects. Do not send grants or sensitive values in query parameters.
Safe errors expose a stable code, retryable, terminal, optional retryAfter, and safe correlationId. HTTP 429 may include Retry-After. Unknown request fields on security-sensitive/command routes are rejected; unknown informational event types are compatible only where the declared policy allows them.
Package surface
The framework-independent package exports createQanivoWidget, WIDGET_PUBLIC_API_PREFIX, and WIDGET_PUBLIC_API_VERSION. The instance provides mounting, launcher control, identity/reset operations, page-context updates, event subscriptions, and bounded message/form/media behavior. Refer to the installed package’s TypeScript declarations for the exact event and option types.
The canonical source references for this guide are qanivo-widget/SERVER_CONTRACTS.md, qanivo-widget/README.md, and the public Widget controller/contract implementation recorded in the repository crosswalk.