Widget request and error reference

Request lifecycle#

1. The loader sends an installation-detection request with the public website ID and current installation token.
2. When the visitor first needs a conversation, bootstrap sends opaque visitor/tab tokens, an idempotency key and the current page path.
3. A message sends the conversation UUID, tab token, a client-turn UUID, content and current page path.
4. Feedback, Action cards and handoff use their own conversation-bound requests.

The browser supplies an Origin header. The service validates its hostname against the configured site. Server-side scripts without the corresponding origin/session lifecycle cannot simply replay a browser request as a general chat client.

Use the Network panel with a clean public-page load, then open the chat and submit a safe question. This separates automatic detection from interaction requests without replaying tokens or inventing another client.

Installation detection#

POST /v1/widget/installations/detect expects publicSiteId and installationToken. The official loader obtains both from its script attributes. A successful response supplies the website name, saved widget appearance and available human-support control.

400 invalid_widget_request means an invalid body or origin. 403 installation_not_allowed means the credential and domain were not accepted. Detection is limited to 20 requests per minute; investigate duplicated loaders before repeatedly refreshing.

If detection is absent, first inspect the document and script download. If it is rejected, compare the final hostname and current credentials. A visible greeting can still be a local rendering with Support unavailable after failed detection.

Conversation bootstrap#

POST /v1/widget/bootstrap expects a UUID publicSiteId, 32–256 character visitorToken and tabToken, and a 16–256 character idempotencyKey. Optional currentPagePath is limited to 2,048 characters. Optional context follows the scalar-map contract.

A successful response contains conversationId, billableWindowId and countedNewConversation. The official loader saves the public conversation ID in tab session storage. 403 site_origin_not_allowed indicates a domain boundary failure. 402 workspace_access_unavailable means the conversation could not be opened; check workspace access and capacity. Bootstrap is limited to 30 requests per minute.

The 402 code identifies a conversation-opening failure, not necessarily a definitive diagnosis of one billing cause. Check effective access and paid capacity in the workspace, then collect safe evidence if those appear correct.

Message shape and replay#

POST /v1/widget/conversations/CONVERSATION_UUID/messages carries a body shaped as follows. This is a diagnostic template; opaque values and UUIDs must come from the actual verified lifecycle.

{
  "tabToken": "CURRENT_OPAQUE_TAB_TOKEN",
  "clientTurnId": "UNIQUE_CLIENT_TURN_UUID",
  "content": "What is your returns policy?",
  "currentPagePath": "/products/leather-bag"
}

Content is trimmed, must be non-empty and is limited to 4,000 characters. A completed replay of the same client-turn ID returns the prior answer with duplicate: true. A still-processing duplicate returns 409 turn_already_processing; it should not be treated as a second new question. Messages are limited to 30 requests per minute.

The message body does not include a fresh browser-context map. The current path may change between questions, while the scalar context attachment remains the first-bootstrap operation described in the browser context guide.

Failure states to distinguish#

404 conversation_not_found can indicate an invalid tab/conversation association, an expired conversation, a removed website or an origin mismatch. 503 ai_service_not_configured is a service availability/configuration issue rather than a missing installation.

A network failure, rejected request or unavailable service causes the official widget to show its temporary-unavailability message. Capture safe error codes and status values when diagnosing; never share raw visitor/tab tokens or installation credentials in screenshots. A fixed off-topic boundary reply is an intentional policy response, not an HTTP failure.

Compare a fresh browser context with an existing tab. An old session-stored conversation can fail while a new authorized conversation works. Reloading the old tab does not necessarily replace that saved identifier.

Worked trace: loader succeeds, first question fails#

The document contains the official tag, the CDN script returns successfully and installation detection accepts the current token and hostname. The launcher opens and displays a greeting. The customer’s first submitted question then triggers bootstrap, which returns 402 workspace_access_unavailable. This is not evidence of a missing loader, so regenerating installation code is not the next diagnostic step.

Inspect the workspace’s active access and capacity, the approximate request time and the safe response code. If bootstrap succeeded but the subsequent message failed, identify that later endpoint instead. A404conversation_not_foundcan have tab, origin, retention or site-boundary causes; a 503 response can indicate service availability. Keep those failure paths distinct.

Use a fresh normal browser context to compare behavior, and avoid repeatedly resending private information. Share the public domain, route, browser, time, failing stage and safe code with support. Redact installation, visitor and tab credentials and private query strings. The trace is diagnostic evidence, not a template for a general-purpose chat SDK.

Capture the smallest useful diagnostic record#

Record the public page, final hostname, browser/device, approximate time, endpoint stage, HTTP status and safe error code. State whether the issue occurs before any question, on first submission or after a previously working conversation. Note whether a fresh context succeeds and whether all routes fail or only one document layout.

Do not export an unredacted network archive by default: headers, payloads and page queries can contain continuity credentials or customer information. A safe filtered screenshot or a short status record is often sufficient. If a larger capture is required, follow the support team’s controlled process and redact unrelated values.

Do not infer an external operation succeeded because a request was sent, or infer every failure is a network retry candidate. Action write outcomes have their own unknown-state rules. For ordinary widget failures, identify the earliest failed stage and fix its prerequisite before repeating the full flow. Keep this reference alongside the installation and conversation-error guides.

Triage by the earliest failed stage#

If the script is missing, inspect the published document layout. If the download is blocked, read the browser policy or extension error. If detection returns 403, inspect the current site/token/hostname pairing. If bootstrap fails, inspect effective service access and the site boundary. If a message fails after bootstrap, inspect the conversation and tab association and relevant service error.

A successful earlier request narrows the diagnosis but does not guarantee later availability. Installation detection does not authorize another hostname, create private order permissions or establish that all Knowledge is ready. Similarly, a successful message request does not prove a separately configured Action has completed in its destination.

Use ordinary UI actions to reproduce one case at a time. Repeated rapid reloads can encounter the per-minute limits and obscure the original fault. The official client creates unique turn identifiers for new questions and handles completed duplicates differently from still-processing duplicates. Do not manually replace those values while collecting evidence.

Rate limits and replay are not a retry strategy#

Detection is limited to twenty requests per minute, and bootstrap and message routes to thirty per minute. These service limits are separate from your workspace conversation allowance. A burst of repeated page loads or duplicate script injections can cause a request-limit symptom even when the original configuration is valid.

The client-turn UUID identifies one submitted turn. A completed replay with that same ID returns its prior answer with a duplicate indicator; a processing replay can return 409 turn_already_processing. Sending a different ID is a new turn rather than a guaranteed safe retry of the old one. Leave the official loader’s lifecycle intact instead of constructing manual request loops.

When debugging, slow down and identify one public load and one safe question. Keep failed-stage evidence, then correct the underlying layout, host, access or service condition. For external write Actions, never assume that a generic HTTP retry rule applies: an uncertain destination outcome must be reconciled with its run reference before a new operation is attempted.