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

# Troubleshooting

> The problems that actually come up, and the first thing to check for each one.

Ordered roughly by how often each one happens. Every entry starts with the check that resolves it most of the time.

## Messages

<AccordionGroup>
  <Accordion title="A customer says they messaged us and nothing arrived" icon="message-square-x">
    **Check the inbox is receiving at all**, not just this conversation. Send yourself a test message
    on the same channel. If the test arrives, the problem is with that one contact; if it does not,
    the channel is down for everyone and that is a different fix.

    If the test does **not** arrive:

    * **Web chat** — the script tag may not be on the page the customer was on. Check the page source.
    * **Email** — check the forwarding address is still forwarding. A rule change on your mail
      provider breaks it silently. See [Email](/channels/email).
    * **WhatsApp, Instagram, Messenger** — the provider's webhook subscription may have lapsed.
      Reconnect the channel from its settings page.
    * **Apple Messages for Business** — inbound messages stop if the brand's registration status
      changed. Check the registration state before looking anywhere else.

    If the test **does** arrive, the customer probably messaged a different number, address or
    entry point than you think. Ask them to screenshot what they sent it to.
  </Accordion>

  <Accordion title="Our reply shows as sent but the customer never got it" icon="send-horizontal">
    **Open the message and check its status.** Sent and delivered are different states, and a failed
    send carries its provider error.

    Common causes by channel:

    | Channel | Likely cause |
    | - | - |
    | **WhatsApp** | You replied outside the 24-hour service window. Free-form replies are only allowed inside it; outside, you need an approved template. See [Templates](/channels/templates). |
    | **SMS** | The number is a landline, or the carrier filtered the message. Filtering is silent and common on unregistered traffic — check your 10DLC registration. See [SMS and MMS](/channels/sms-mms). |
    | **Apple Messages** | One message is in flight per conversation at a time. A burst of replies queues rather than failing; give it a few seconds. |
    | **Email** | Check your sending domain's DNS. A missing SPF or DKIM record delivers to spam rather than failing. See [Custom domain](/channels/email/custom-domain). |
  </Accordion>

  <Accordion title="A rich message failed to send on Apple Messages" icon="layout-list">
    **Read the validation error** — it names the field. Apple's schemas reject unknown fields at every
    level, so a message fails in the composer rather than reaching a customer malformed. That is
    working as intended.

    The two that come up most:

    * **A form with a single field.** Not allowed — use a plain text question.
    * **An image URL that is not reachable.** Every image slot must be a URL Apple can fetch. A URL
      behind a login, or on a host that blocks unknown user agents, fails.
  </Accordion>
</AccordionGroup>

## Web chat

<AccordionGroup>
  <Accordion title="The widget does not appear" icon="message-circle-off">
    In order of likelihood:

    1. **The snippet is in `<head>` and your app hydrates late.** Load it after mount instead.
    2. **You copied the snippet from documentation rather than from your inbox settings page.** The
       real one carries your own website token and base URL. See [Web chat](/channels/web-chat).
    3. **A content security policy is blocking it.** Check the browser console for a CSP violation
       naming the SDK URL.
    4. **An ad blocker.** Test in a clean profile before assuming anything else.
  </Accordion>

  <Accordion title="Two widgets appear on the same page" icon="copy">
    **The snippet is running more than once.** In a single-page app, load it once at app boot — the
    widget survives client-side route changes on its own, and re-running it per route produces a
    second instance.
  </Accordion>

  <Accordion title="The agent will not answer anything account-specific" icon="shield-question-mark">
    **Identity verification is probably off.** Without it, every visitor is an anonymous stranger and
    the agent correctly refuses to discuss an account it cannot prove belongs to them.

    Turn on HMAC identity verification and the conversation binds to a real contact. See
    [Identity verification](/channels/web-chat#identity-verification).
  </Accordion>
</AccordionGroup>

## The dashboard

<AccordionGroup>
  <Accordion title="A conversation is stuck loading" icon="loader">
    **Wait about ten seconds.** If the messages have not loaded by then, a **Retry** appears — use it
    rather than reloading the page. Retry re-fetches that thread specifically.

    If retry does not fix it, reload once. A reload after a deploy picks up the new build; Tied
    handles that automatically the first time and offers a manual **Refresh** if it happens again.
  </Accordion>

  <Accordion title="The dashboard is behaving oddly after a release" icon="refresh-cw">
    **Take the update.** When a new version is available, an update action appears in the sidebar
    footer, above your profile menu. Tied never reloads underneath you — it waits for you to click,
    so you are never interrupted mid-conversation — which means an old tab can stay on an old build
    for a long time.
  </Accordion>

  <Accordion title="I cannot see a setting the docs describe" icon="eye-off">
    Three possibilities, in order:

    1. **Your role does not include it.** Most settings are administrator-only. See
       [Roles and permissions](/roles-permissions).
    2. **It is per-inbox, and you are looking at account settings** — or the reverse. Business hours,
       assignment and greetings are inbox settings.
    3. **It is not on your plan.** See [Plans](/pricing/plans).
  </Accordion>
</AccordionGroup>

## The AI agent

<AccordionGroup>
  <Accordion title="It escalates almost everything" icon="user">
    **Check which ground is firing** — the reason is recorded on every handoff, and the fix is
    different for each. See [Guardrails and safety](/agents/guardrails).

    | Ground | What it means | Fix |
    | - | - | - |
    | **No knowledge** | Retrieval found nothing usable | Add content, or re-crawl after a site change |
    | **Low confidence** | It found something and was not sure | Usually a content problem too — the answer is partial |
    | **Must refuse** | The question fell in a refusal category | Narrow the category, or connect the system that would let it answer |
    | **Human requested** | The customer asked for a person | Working as intended. This cannot be switched off |

    If it is **no knowledge** or **low confidence**, check the retrieval numbers before rewriting
    content — "didn't know" and "couldn't find what it knew" look identical in a transcript and have
    opposite fixes. See [Knowledge and retrieval](/agents/knowledge).
  </Accordion>

  <Accordion title="It answered something it should not have" icon="shield-alert">
    **Add or widen a refusal category** for the shape of question involved, then re-run evaluation.

    Write the category as a test on **what a correct answer would require** — this customer's own
    record, a recommendation, a prediction — rather than on the topic. Topic-named categories match
    far more widely than their description implies.

    Then add the specific case to a golden set from the quality queue, so it becomes a permanent
    regression test rather than a one-off fix. See [Evaluation](/agents/evaluation).
  </Accordion>

  <Accordion title="It cannot look anything up in our systems" icon="unplug">
    **Check the integration is connected and has the scope the action needs.** The agent only ever
    sees tools for integrations you have connected and are entitled to — a tool it cannot see is one
    it cannot call, by design.

    A read-only connection produces exactly this symptom: the agent can answer questions about your
    data but cannot change anything. See [Actions and tools](/agents/actions).
  </Accordion>

  <Accordion title="A resolution I expected to bill did not" icon="receipt">
    **This is usually correct, not a bug.** Silence never bills. A resolution needs a positive signal:
    the customer confirming, a system verifying the outcome, or silence plus at least one
    corroborator.

    The most common unbilled outcome is **silence with no corroborator** — a good answer, no reply,
    and no read receipt, opened link or system change to corroborate it. Ambiguity always resolves to
    unbilled.

    A human sending a message in the thread also makes the resolution unbillable entirely, however
    much work the agent did first. See [What counts as a resolution](/pricing/resolutions).
  </Accordion>
</AccordionGroup>

## Billing

<AccordionGroup>
  <Accordion title="An SMS bill is far higher than expected" icon="message-square-dot">
    **Check for non-GSM characters.** One curly quote, one emoji, or one em dash forces the whole
    message into Unicode encoding, which cuts the segment size from 160 characters to 70 — more than
    doubling the segment count on a long message.

    This is by a wide margin the most common cause of a surprising SMS bill. See
    [SMS and MMS](/channels/sms-mms).
  </Accordion>

  <Accordion title="A charge on the invoice looks wrong" icon="circle-question-mark">
    **Open its receipt.** Every billed resolution has one, showing the conversation it came from,
    which signal tier justified billing it, the class and the specific trail entry that fixed the
    price, and the itemised model cost.

    If it still looks wrong, **dispute it from the receipt** — one click, not a support queue. See
    [Operations](/agents/operations).
  </Accordion>

  <Accordion title="The model cost line is not zero on a conversation that did not bill" icon="cpu">
    **That is deliberate.** The two numbers on your invoice are independent. The orchestration fee is
    zero because nothing was resolved. The model cost is not zero because tokens were genuinely
    consumed, and zeroing a real provider charge would make the receipt easier to read and less true.

    On your own provider key, model cost never appears on a Tied invoice at all. See
    [Model costs and BYOK](/pricing/model-costs-byok).
  </Accordion>
</AccordionGroup>

## API and webhooks

<AccordionGroup>
  <Accordion title="A webhook is not firing" icon="webhook">
    1. **Check the endpoint returns 2xx quickly.** A slow or erroring endpoint gets retried and then
       backed off.
    2. **Check you subscribed to the event you think you did.** See
       [Webhook events](/api-reference/webhooks/events).
    3. **Test the endpoint directly** before assuming the problem is upstream. See
       [Testing webhooks](/api-reference/webhooks/testing).
  </Accordion>

  <Accordion title="Signature verification fails" icon="file-key">
    **Verify against the raw request body**, before any JSON parsing or re-serialisation. Parsing and
    re-encoding changes whitespace and key order, and the signature is over the exact bytes sent. This
    is the cause almost every time. See [Signatures](/api-reference/webhooks/signatures).
  </Accordion>

  <Accordion title="An API call returns 401" icon="key-round">
    Check, in order: the token is being sent in the header the endpoint expects, the token has not
    been rotated, and the account id in the path matches the one the token belongs to. See
    [Authentication](/api-reference/authentication).
  </Accordion>
</AccordionGroup>

## Still stuck

<CardGroup cols={2}>
  <Card title="Known limitations" icon="triangle-alert" href="/channels/apple-messages/limitations">
    Some behaviour is a platform constraint rather than a bug. Check here before spending an hour on
    it.
  </Card>

  <Card title="Core concepts" icon="lightbulb" href="/concepts">
    A lot of confusion is a channel-versus-inbox or conversation-versus-resolution mix-up.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.