Widget configuration and security

Appearance settings

Open a site’s Settings tab to change the values below. Changes apply to the installed snippet after the widget reads the site configuration.

Setting	Accepted values	Default
Assistant name	1–60 trimmed characters	AI Assistant
Welcome message	1–240 trimmed characters	Hi, how can I help?
Placeholder	1–120 trimmed characters	Ask a question...
Primary color	Six-digit hex, for example #0b7fd3	#1f8062
Position	bottom-right or bottom-left	bottom-right
Theme	light, dark, or system	light
Suggested questions	Up to 5 strings, 1–80 trimmed characters each	None

The server validates these bounds. Invalid stored values are normalized back to safe defaults. Widget settings do not change what the crawler indexes or what the answer model is allowed to say.

Allowed origins and domain matching

The site domain is checked at the widget session, config, and chat endpoints.

In production, the embedding page must use HTTPS. HTTP is allowed only for localhost development origins.
The origin hostname must match the site domain. The check ignores a leading www. prefix, but it does not allow arbitrary subdomains.
The configured Refleks app origin is also allowed for dashboard/test use. This does not make every customer domain trusted.
Unknown or mismatched origins receive an origin-not-allowed response. CORS headers are reflected only after the origin passes validation.

Not supported

No wildcard customer-domain verification

There is no DNS/TXT challenge and no wildcard subdomain grant in the current flow. Dashboard “Verify installation” fetches your site output and checks the expected script, key, origin, and HTTPS; it is an install probe, not a proof of domain ownership.

Content Security Policy (CSP)

Strict CSP is supported when the host page allows the Refleks app origin in the places the loader uses it.

Replace https://YOUR_REFLEKS_APP with the origin in your generated script. A minimal host-page policy usually needs the app origin in script-src, connect-src, and frame-src:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://YOUR_REFLEKS_APP;
  connect-src 'self' https://YOUR_REFLEKS_APP;
  frame-src 'self' https://YOUR_REFLEKS_APP;

script-src permits the versioned loader.
connect-src permits the host-page visitor-session request.
frame-src permits the sandboxed Refleks-origin chat frame.

Your site may also have a tag manager policy, consent manager, or platform-specific script policy. Those rules can delay or prevent the loader even when the generated snippet is correct.

What installation verification checks

Supported

Normal script tag

The probe looks for a Refleks widget script, checks its HTTPS URL and expected app origin, and compares the data-widget-key to the site key.

Conditional

Framework or tag-manager reference

If the raw script tag is absent, the probe can recognize the expected URL and key in framework output. A tag manager that runs only in a browser may still require manual confirmation.

The verification result distinguishes installed, framework reference found, missing script, wrong key, wrong app URL, HTTP URL, and unreachable site. A successful probe means the fetched output matched; it does not test every page or guarantee that a customer’s CSP and consent settings allow execution in every browser.

Visitor session and loading behavior

The loader establishes a site-bound visitor session before mounting the iframe when visitor sessions are enabled.
The iframe is sandboxed and communicates with the loader using origin-checked messages. The chat API enforces the same site-origin and plan checks.
When the site has no active index, is outside the account’s current site allocation, or has hit a rate limit, the widget cannot provide normal answers until that condition is resolved.

For a complete copy-and-publish walkthrough, read Install. For quota-related widget errors, read Plans and limits.