> ## 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

> When the chat will not load, will not reply, or does not look right

Work down this page in order — the first three sections cover most of what
actually goes wrong.

***

## "This chat is not available."

One message covers several causes on purpose: telling an anonymous visitor
which one it is only helps somebody enumerate widget ids. Check them in this
order.

<AccordionGroup>
  <Accordion title="Your Widgets subscription is not active">
    **This is the most common cause, and it is invisible from the widget.**

    Reading is always allowed — the panel opens, the config loads, the knowledge
    base and past conversations are readable. What is refused is **starting a
    conversation, sending a message, or uploading a file**.

    Take or renew the Widgets subscription from
    [**Billing**](https://callkaro.ai/dashboard/billing).

    <Note>
      If the billing lookup itself cannot complete, the chat is allowed to work. A
      billing check is never the reason a working chat stops.
    </Note>
  </Accordion>

  <Accordion title="The widget is paused or deleted">
    A paused widget says *"This chat is currently paused."* Check the widget's
    status at [**Widgets**](https://callkaro.ai/dashboard/widgets).
  </Accordion>

  <Accordion title="The widget id is wrong">
    It must be the full `wgt_…` id from the widget's Integration tab. A voice
    widget's id will not work on `chat.html` — they are different widget types.
  </Accordion>

  <Accordion title="The agent has never been published">
    *"This assistant is not available yet."* Open the agent and press
    **Publish**. Creating a flow is not publishing it, and importing one
    certainly is not.
  </Accordion>

  <Accordion title="The agent is not on the widget channel">
    *"This assistant is not configured for chat."* The agent must be on the
    **Widget** channel — a WhatsApp or Instagram agent will not serve a widget.
  </Accordion>

  <Accordion title="The agent is in AI mode instead of flow mode">
    *"This agent is not a flow agent."* The create-agent dialog offers **Guided
    flow** and **AI assistant** for a widget agent, but the widget runtime only
    runs the first. An agent saved as AI assistant refuses every conversation.

    Create the agent again as **Guided flow**, and get your AI assistant as an
    [AI card](/widget/chat/ai-card) inside the flow — which is the supported
    way, and lets you attach your own functions to it.
  </Accordion>

  <Accordion title="The agent has no flow, or no start step">
    *"This assistant has no conversation flow configured yet."* or *"…has no
    start step."* The published version carries an empty graph. Draw the flow
    and publish again.
  </Accordion>
</AccordionGroup>

***

## "This conversation has expired. Please start again."

The conversation could not be resumed. Normally this is simply true — a session
resumes for **12 hours** of inactivity and then starts fresh.

It also appears when the flow was **republished** and the card the visitor was
sitting on no longer exists. Sending them back to the start is the only coherent
move; the alternative is a dead conversation with no explanation.

<Tip>
  If it appears immediately after a perfectly normal reply, that is not an
  expiry — check that both the chat service and NodeBackend are running the
  current release.
</Tip>

***

## The Bot Does Not Reply

<AccordionGroup>
  <Accordion title="Nothing happens when a button is tapped">
    The button is probably connected to nothing. Publishing blocks that, so the
    usual cause is an old published version — open the agent, check the canvas,
    publish again.
  </Accordion>

  <Accordion title="It replies once and then stops">
    Look for a card with no exits. In **Try it** you will hit it in seconds.
  </Accordion>

  <Accordion title="An API or Run code card always takes the error exit">
    Both have an **8-second** limit. Keep your own HTTP timeout below it — 5 or
    6 seconds — so a slow API returns a clear failure instead of being cut off
    mid-request.
  </Accordion>

  <Accordion title="The AI card never calls my function">
    Three things to check, in order:

    1. The code must define a tool decorated with `@tool`. Without the
       decorator there is nothing to call.
    2. The **Description** field is read as *when to use this*. If it only
       repeats what the function does, the model has no cue to call it.
    3. Some smaller models are weak at tool-calling. Try the card on a stronger
       model before concluding the function is wrong.

    Every call the assistant does make is recorded on the message in
    [Contacts](https://callkaro.ai/dashboard/contacts) — if the panel is empty,
    it genuinely did not call anything.
  </Accordion>

  <Accordion title="The AI card ends the conversation too early">
    It is instructed to finish only when the person signals they are done, and
    explicitly not because a function failed or it did not understand. If it is
    still finishing early, the card's own instructions are usually telling it to
    — look for anything resembling *"if you cannot help, end the conversation"*.
  </Accordion>
</AccordionGroup>

***

## Nothing Appears In Contacts

* Filter the channel to **Widget**. Widget conversations are not in Call
  History and never will be.
* A conversation with no `uid` and no phone number is keyed by a
  browser-minted visitor id — it is there, under a generated name like
  *Visitor 7K2QM*.
* If replies appear only after a refresh, the live push is not reaching the
  dashboard. That is a server-side connection, not a browser setting.

***

## In A Mobile App

<AccordionGroup>
  <Accordion title="Android WebView forgets the conversation every time">
    `domStorageEnabled` is **off by default** in `WebView`, and the failure is
    silent — the chat works, it just cannot remember anything, so every open
    starts from the greeting.

    ```kotlin theme={null}
    webView.settings.domStorageEnabled = true
    ```

    Prefer **Custom Tabs** unless the chat has to sit inside your own navigation;
    storage works there with no setup.
  </Accordion>

  <Accordion title="Deep-link buttons do nothing">
    Your `WebView` has to hand your own schemes to the system. Let everything on
    `widget.callkaro.ai` stay in the page and start an intent for the rest — the
    snippet is in [Install](/widget/chat/install).
  </Accordion>

  <Accordion title="The visitor is a stranger on every device">
    That is what happens with no `uid`. Pass one if your app knows who they are —
    [Variables and identity](/widget/chat/variables#how-the-contact-key-is-chosen).
  </Accordion>

  <Accordion title="The microphone does not work">
    Recording needs a secure context and the host app's own microphone
    permission. In a `WebView` you must also grant the page's permission request
    — a Custom Tab handles this for you.
  </Accordion>
</AccordionGroup>

***

## It Does Not Look Right

<AccordionGroup>
  <Accordion title="My logo is cropped">
    It is drawn in a circle. Use a square image.
  </Accordion>

  <Accordion title="Business hours are never shown">
    Three things must all be true: business hours **enabled**, the notice mode
    not set to **Never**, and — on the default mode — you must actually be
    closed. [Appearance → Business hours](/widget/chat/appearance#business-hours)
  </Accordion>

  <Accordion title="My **bold** shows as literal asterisks">
    Formatting works in authored message text and button labels. It does **not**
    work in values substituted from variables — those are escaped deliberately,
    so a visitor cannot make their own answer bold inside a message your account
    appears to have written.
  </Accordion>

  <Accordion title="My FAQs do not appear">
    The knowledge base is part of the agent's **version**. Editing it is not
    publishing it — press **Publish** on the agent.
    [Knowledge base →](/widget/chat/knowledge-base)
  </Accordion>

  <Accordion title="An image card shows a broken image">
    The link must be publicly reachable — no signed URL that expires, no
    file behind your login. Open it in a private window to check.
  </Accordion>
</AccordionGroup>

***

## Still Stuck

Have these ready and it will be a much shorter conversation:

* The **widget id** (`wgt_…`)
* The **session id** if you have it, or the contact in Contacts
* Roughly **when** it happened, with your timezone
* What you expected, and what happened instead

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Install in your app" icon="code" href="/widget/chat/install">
    The snippets, per platform
  </Card>

  <Card title="Card types" icon="diagram-project" href="/widget/chat/card-types">
    What blocks a publish
  </Card>
</CardGroup>