> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.poly.ai/feedback

```json
{
  "path": "/webchat/widget-troubleshooting",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Widget troubleshooting

> Fix common chat widget issues and follow deployment best practices.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget does not appear">
    **Possible causes:**

    * The snippet is not loading on that page
    * The script is blocked by a Content Security Policy (CSP)
    * An ad blocker or privacy extension is blocking the script
    * Tag Manager or website code has syntax errors (missing quotes, unclosed tags)

    **What to try:**

    1. Confirm the snippet is present in the page source and placed before `</body>`
    2. Temporarily disable ad blockers and retry
    3. Open Developer Tools → **Console** tab and look for script load errors
    4. Verify any Tag Manager configuration has proper punctuation and syntax
  </Accordion>

  <Accordion title="CSP or security headers block the widget">
    If your site uses Content Security Policy (CSP), your policy may need to allow the widget script.

    **What to try:**

    1. Ask your web team to add the widget CDN domain to your CSP allowlist
    2. Check your CSP header for `script-src` directives that may block external scripts
    3. If your CSP is strict, you may also need to allow any required destinations used by the widget

    <Note>
      If your organization requires a formal security review, share your CSP errors and current CSP header with PolyAI support.
    </Note>
  </Accordion>

  <Accordion title="Cookie consent banner overlaps the widget">
    **What to try:**

    1. Adjust your cookie banner placement or `z-index`
    2. [Adjust the widget position](/webchat/widget-installation#widget-positioning) using CSS on the `#poly-ai-chat` element
    3. Test on mobile, where banners often cover more screen space
  </Accordion>

  <Accordion title="iFrame or embed restrictions">
    If your website is primarily rendered inside an iFrame, some browser rules can restrict behavior.

    **What to try:**

    1. Test the widget on the top-level page (not embedded in an iFrame)
    2. Check your iFrame `sandbox` attributes and whether scripts and top navigation are allowed
  </Accordion>

  <Accordion title="tel: links do not launch calls">
    **Possible causes:**

    * Desktop browsers may not have a default calling app
    * Some managed devices block `tel:` links

    **What to try:**

    1. Test on a mobile device
    2. Confirm your number is valid and in international format
    3. Verify device policies allow phone links
  </Accordion>

  <Accordion title="QR code does not scan">
    **Possible causes:**

    * Low contrast or too small on mobile
    * Camera permissions or scanner limitations

    **What to try:**

    1. Increase the QR size (if configurable)
    2. Test with a different scanner app
    3. Ensure screen brightness is sufficient
  </Accordion>

  <Accordion title="Ad blockers prevent loading">
    **What to try:**

    1. Confirm the issue reproduces with extensions disabled
    2. If your audience often uses ad blockers, consider adding installation guidance to your help center
  </Accordion>
</AccordionGroup>

## Best practices

### Placement and UX

* Place the widget in a **bottom corner** and keep it consistent across pages
* Avoid overlapping key UI elements: cookie banners, accessibility controls, "Back to top" buttons, mobile navigation
* If you use a sticky footer, test the widget on mobile to ensure it remains tappable

### Performance

* Load the widget **asynchronously** (the script snippets do this by default)
* Avoid duplicating the snippet in multiple places
* For performance-sensitive sites, consider loading the widget only on high-intent pages (checkout, booking, support)

### Privacy and security

* Only include the widget on domains you control
* Review your privacy policy to ensure it covers chat interactions
* If you use cookie consent, confirm whether chat functionality should wait until consent is granted

## Contacting support

If you can't resolve an issue, contact support and include:

* The affected **page URL(s)**
* The **date and time** the issue occurred
* **Browser and version** (e.g., Chrome 122)
* **Device and OS** (e.g., iPhone 15, iOS 17)
* Whether ad blockers, VPN, or privacy tools are enabled
* A screenshot of the broken widget and any browser console errors

## Related pages

<CardGroup cols={3}>
  <Card title="Widget" icon="window-maximize" href="/webchat/widget">
    Create and configure chat widgets.
  </Card>

  <Card title="Widget installation" icon="code" href="/webchat/widget-installation">
    Embed the widget using direct HTML or Tag Manager.
  </Card>

  <Card title="Chat configuration" icon="message" href="/webchat/chat-configuration">
    Configure LLM, greeting, and safety filters for chat.
  </Card>
</CardGroup>