Developer documentation

Install the Guyche widget safely and asynchronously

This guide documents the public widget installation contract. Knowledge, appearance, and allowed domains are managed in the dashboard; private product endpoints are not a general-purpose public API.

Create a Site in the dashboard

Copy its Site ID from the widget page and register only real, approved host domains.

Load the script asynchronously

The snippet below runs outside the parser-critical path and should not block initial host-page rendering.

Align the Content Security Policy

For a restrictive CSP, allow https://www.guyche.ir in script-src and connect-src.

Test failure paths

Verify mobile keyboard behavior, streaming, unknown questions, reconnect, and human handoff before launch.

Replace the placeholder with the Site ID for that environment. A Site ID is not a secret, but it is valid only for its configured Site and allowed domains.

<script>
  (function () {
    var script = document.createElement("script");
    script.src = "https://www.guyche.ir/widget.js";
    script.async = true;
    script.dataset.siteId = "SITE_ID_FROM_GUYCHE_DASHBOARD";
    document.head.appendChild(script);
  })();
</script>

Security boundaries

Widget APIs validate Origin and allowed domains.
Message content and links are sanitized before rendering.
Never place AI provider secrets or API keys in the snippet.

Performance behavior

The script is asynchronous and renders inside Shadow DOM. The host site must still measure real loading, LCP and INP impact, and viewport behavior; async loading alone does not guarantee a score.