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

# Troubleshooting

> Fixes for the most common widget installation and connection problems

## Overview

Almost every widget problem falls into one of three buckets: the launcher does
not appear, it appears but looks wrong, or conversations fail to start.

<Tip>
  Open your browser's developer console (**F12**) before you start. The widget
  logs a clear message for most failure modes, which usually points straight at
  the cause.
</Tip>

***

## The Launcher Does Not Appear

<AccordionGroup>
  <Accordion title="The snippet is not actually on the page" icon="file-code">
    View your page source and search for `w.js`. If it is missing, the snippet
    was added to a template that this page does not use, or a caching layer is
    still serving the old HTML.

    **Fix:** clear your site and CDN cache, then reload with a hard refresh.
  </Accordion>

  <Accordion title="The widget is paused or deleted" icon="pause">
    A paused widget deliberately renders nothing, and a deleted widget id no
    longer resolves.

    **Fix:** open **Embed Widgets** in the dashboard and confirm the widget is
    **Active** and that the id in your snippet matches.
  </Accordion>

  <Accordion title="A Content Security Policy is blocking it" icon="shield">
    The console will show a CSP violation naming `widget.callkaro.ai`.

    **Fix:** allow the widget's origins:

    ```
    script-src  https://widget.callkaro.ai;
    frame-src   https://widget.callkaro.ai;
    connect-src https://backend.callkaro.ai;
    ```
  </Accordion>

  <Accordion title="React strips the script tag" icon="react">
    A plain `<script src>` written inside JSX is removed by React and never
    executes — a very common cause in React and Next.js sites.

    **Fix:** use `next/script`, or inject the tag in a `useEffect`. See
    [installation](/widget/install-on-your-website#react).
  </Accordion>

  <Accordion title="An ad or tracker blocker is removing it" icon="ban">
    Some aggressive blockers treat any third-party script as tracking.

    **Fix:** confirm by testing in a private window with extensions disabled.
    This affects only that visitor, not your installation.
  </Accordion>
</AccordionGroup>

***

## The Launcher Appears But Looks Wrong

<AccordionGroup>
  <Accordion title="Default icon and colours instead of my branding" icon="palette">
    The widget loads its appearance from our servers at page load. If that
    request is blocked, it falls back to defaults — the widget still works, it
    just is not branded.

    **Common causes:** a `connect-src` CSP rule that omits
    `backend.callkaro.ai`, or a network-level blocker.

    **Fix:** allow `connect-src https://backend.callkaro.ai` and check the
    console for a blocked request.
  </Accordion>

  <Accordion title="Recent dashboard changes have not shown up" icon="clock">
    Configuration is cached briefly so the widget stays fast.

    **Fix:** wait about a minute and hard-refresh.
  </Accordion>

  <Accordion title="It overlaps another chat widget" icon="layer-group">
    Two widgets are competing for the same corner.

    **Fix:** change the CallKaro widget's **Position** to the opposite corner.
  </Accordion>

  <Accordion title="It sits behind something on my page" icon="eye-slash">
    Rare, but possible if your site uses extremely high `z-index` values on a
    sticky header or overlay.

    **Fix:** lower the `z-index` on the element covering it, or contact support.
  </Accordion>
</AccordionGroup>

***

## Conversations Fail To Start

This is the "Could not connect" message inside the panel.

<AccordionGroup>
  <Accordion title="Your site is not served over HTTPS" icon="lock">
    Browsers only allow microphone access on secure origins. The launcher and
    panel work on `http://`, but starting a conversation always fails.

    **Fix:** serve your site over HTTPS. `http://localhost` is exempt, so local
    development works without a certificate.
  </Accordion>

  <Accordion title="Microphone permission was denied" icon="microphone-slash">
    If the visitor dismissed or blocked the browser prompt, no audio can be
    captured. Browsers remember the choice, so it will not ask again.

    **Fix:** click the padlock in the address bar, reset the microphone
    permission for the site, and reload.
  </Accordion>

  <Accordion title="A Permissions-Policy header blocks the microphone" icon="shield-halved">
    The widget delegates microphone access to its iframe. A header such as
    `Permissions-Policy: microphone=()` prevents that delegation, so the widget
    loads perfectly and then fails the moment a visitor presses **Talk**.

    **Fix:** remove the restriction, or explicitly allow
    `microphone=(self "https://widget.callkaro.ai")`.
  </Accordion>

  <Accordion title="A corporate network is blocking the connection" icon="network-wired">
    Voice needs a real-time media connection. Some corporate firewalls and VPNs
    block the required traffic.

    **Fix:** test on a different network — mobile data is a quick check. If it
    works there, ask IT to permit real-time audio to `callkaro.ai`.
  </Accordion>
</AccordionGroup>

***

## Audio Problems During A Conversation

<AccordionGroup>
  <Accordion title="Status shows Live but nobody can hear anything" icon="volume-xmark">
    The session connected but audio is not flowing — usually a restrictive
    network blocking real-time media, or the wrong input device selected.

    **Fix:** try another network, and check the browser's site settings for
    which microphone is selected.
  </Accordion>

  <Accordion title="The visitor cannot hear the agent" icon="volume-low">
    Browsers block audio playback until the visitor interacts with the page.
    Pressing **Talk** normally satisfies that, but an aggressive autoplay policy
    can still intervene.

    **Fix:** check the tab is not muted, then reload and press **Talk** again.
  </Accordion>

  <Accordion title="The agent keeps interrupting or mishears" icon="ear-listen">
    This is agent tuning rather than a widget problem — background noise and
    interruption thresholds are configured on the agent.

    **Fix:** see
    [call initiation and termination](/agents/configurations/call-initiation-and-termination)
    and [transcriber settings](/agents/configurations/transcriber).
  </Accordion>
</AccordionGroup>

***

## The Transcript

<AccordionGroup>
  <Accordion title="Some speech is faded" icon="spinner">
    Faded text is expected. It marks speech still being transcribed; it
    solidifies once finalised.
  </Accordion>
</AccordionGroup>

***

## Still Stuck?

When contacting support, include these — it usually turns a long back-and-forth
into a single reply:

* The **widget id** and the **page URL** where it is installed
* Your **browser and version**, and the operating system
* Any **console errors**, copied as text
* Whether it fails for everyone or just one person or network

<CardGroup cols={2}>
  <Card title="Contact Support" icon="headset" href="mailto:support@callkaro.ai">
    Send us the details above and we will investigate
  </Card>

  <Card title="Installation guide" icon="code" href="/widget/install-on-your-website">
    Re-check your setup against the reference snippets
  </Card>
</CardGroup>