Troubleshooting

Widget bubble doesn't appear on the page

  • Open the browser console — widget.js logs [Deskly] Missing data-bot-key attribute on the widget script tag. if data-bot-key wasn't set on the <script> tag
  • Confirm the src on the script tag points at your actual Deskly deployment, not localhost, if you're testing on a real domain
  • Check that the bot exists and is_active is true — an inactive or deleted bot's iframe renders a plain "This assistant is not available." message instead of the chat UI

Widget shows "This assistant is not configured for this website."

The Referer header on the iframe's initial load didn't match any domain in the bot's allowed_domains. Two common causes:

  • The domain wasn't added to the bot's allowlist in /dashboard/bots/[botId] — check for a www. mismatch too (the check tolerates example.com vs www.example.com, but not other subdomain variations)
  • You're testing via a file:// URL or a tool that strips Referer — this check only blocks when a Referer is present and wrong; if you're getting this message, a Referer likely is being sent and doesn't match, so check the allowlist first

See Embeddable Widget for exactly how this check works and why it isn't a hard security boundary.

Widget shows "This assistant has not been configured with an allowed website yet."

The bot's allowed_domains array is empty. Add at least one domain in /dashboard/bots/[botId] — a bot refuses to render anywhere until it has at least one allowed domain, by design.

Visitor gets the generic "temporarily unavailable" message

This is the graceful-degradation path — it fires when either:

  • The bot owner's profiles.credits is <= 0, or
  • The estimated cost of the next response would exceed the owner's remaining balance

This is not a bug — top up the owner's account to resolve it. If RESEND_API_KEY and the owner's email are configured, they should have received a notification the first time this triggered.

429 Too Many Requests from /api/widget/chat

One of the three rate limit layers was hit — per-visitor (20/min), per-bot-hourly (300/hr), or per-bot-daily (1,000/day). See Abuse Protection for the exact thresholds. These are in-memory limits, so they reset on deploy/restart — expected in a single-instance deployment, but worth knowing if you're debugging "why did the limit reset."

RAG isn't returning any context

  • Confirm the document was uploaded against the specific bot (/dashboard/bots/[botId]), not the account-level dashboard chat feature — documents are scoped by bot_id and the two are not interchangeable
  • Confirm the document's status is completed — only completed documents are eligible for retrieval
  • With zero documents, the bot still answers from its system_prompt alone — that's expected behavior, not a failure

CRM OAuth connect fails or createAppointment throws

Appointment creation is intentionally stubbed and always throws — see CRM Integrations. If the connect step itself fails, check that JOBBER_CLIENT_ID/JOBBER_CLIENT_SECRET (or the Housecall Pro equivalents) are set and that NEXT_PUBLIC_APP_URL matches the redirect URI registered with the provider exactly.

Still stuck?

Check Getting Started and Configuration for setup steps you may have skipped, or reach out to our support team.