Reference
Troubleshooting & FAQ
Common problems and how to fix them, grouped by who runs into them. Each entry gives an actionable fix and links to the deep doc when you need more. Replace CAPS placeholders with your own values. The production domain is helpstack.eu.
Agents & admins#
A teammate can't see Settings or change configuration
Their role is likely AGENT or VIEWER. Agents have read-only access to settings, and viewers are read-only across conversations and analytics. Ask an OWNER or ADMIN to change their role. See ../guides/09-team-and-roles.md.
I'm not getting notified about new conversations
Check your notification settings for the event (NEW_CONVERSATION / NEW_MESSAGE / ASSIGNED / STATUS_CHANGED) and channel (IN_APP, EMAIL, PUSH, etc.). If the scope is ASSIGNED_ONLY, you only get alerts for conversations assigned to you — switch to ALL to be notified about everything. See ../guides/10-notifications.md.
A conversation disappeared from my inbox
Check its status. Conversations move OPEN → PENDING → CLOSED, and your inbox filter may be hiding CLOSED (or PENDING) threads. Clear or widen the status filter. See ../guides/02-conversations.md.
My internal note was sent to the customer
Internal notes are private to your team and are never delivered to the customer — if the customer received text, it was added as an OUTBOUND reply, not a note. Make sure you use the note field, not the reply box. See ../guides/02-conversations.md.
AI & knowledge base#
AI replies are generic, vague, or wrong
Two things ground the AI: a system prompt and knowledge. First, write a clear per-channel system prompt that sets the persona, tone, and rules. Second, attach the relevant knowledge-base groups to the channel so replies are grounded in your own content via RAG. Without attached KB groups the model only has general knowledge. See ../guides/03-ai-replies.md and ../guides/05-knowledge-base.md.
There's no AI reply option anywhere
You need at least one configured AI provider (OpenAI, Anthropic, Azure OpenAI, or Ollama) with a model set, and one provider marked as the org default. Add a provider in settings, then mark it default. See ../guides/03-ai-replies.md.
A knowledge-base article is stuck or shows an error
Articles move PROCESSING → READY/ERROR. If an article sits in PROCESSING, give scraping/upload time to finish; if it shows ERROR, the source URL may be unreachable or the uploaded file unsupported — re-add it with a valid source. Only READY articles are used for RAG. See ../guides/05-knowledge-base.md.
The AI ignores my knowledge base
Confirm the knowledge-base group containing those articles is actually attached to the channel handling the conversation, and that the articles are READY (not PROCESSING/ERROR). KB grounding is per channel via attached groups. See ../guides/05-knowledge-base.md.
FAQ chips aren't showing in the widget, but KB looks fine
FAQs and the knowledge base are different features. FAQs (Question ≤280 chars, Answer ≤2000 chars) drive the chips in the widget greeting and must be defined org-wide or on that WEBSITE_CHAT channel. The knowledge base grounds AI replies and does not create greeting chips. See ../guides/06-faqs.md.
Drafts never send on their own
The channel's auto-reply mode is probably off or prepare. prepare drafts a reply but waits for an agent to approve it; only auto-approve sends without review. Set the mode to auto-approve if you want hands-off sending. See ../guides/03-ai-replies.md.
Channels & messaging#
Facebook messages aren't arriving
Work through these in order:
- Verify token mismatch — the token in your Facebook app must exactly match
FACEBOOK_VERIFY_TOKEN, or the verification challenge fails and the webhook is never subscribed. - Signature failure —
FACEBOOK_APP_SECRETmust be set correctly so HelpStack can validate the HMAC signature on incoming payloads; a wrong secret silently rejects events. - Page subscription — confirm the Facebook Page is subscribed to your app's webhook with messaging fields enabled.
See ../integrations/webhooks.md.
Instagram or WhatsApp messages aren't arriving
Same checklist as Facebook, using the matching env vars: INSTAGRAM_VERIFY_TOKEN for Instagram and WHATSAPP_VERIFY_TOKEN for WhatsApp. Confirm the verify token matches, the signature/secret is correct, and the account/number is subscribed to the webhook. See ../integrations/webhooks.md.
I can't find a Telegram channel option
TELEGRAM exists in the schema but is not yet available in the UI. Use EMAIL, FACEBOOK, INSTAGRAM, WHATSAPP, or WEBSITE_CHAT. See ../guides/04-channels.md.
Website widget#
The widget doesn't appear on my site
Check, in order:
- CHANNEL_ID — the
idin the script URL must be yourWEBSITE_CHATchannel ID:<script src="https://helpstack.eu/widget.js?id=CHANNEL_ID" async></script>. - Domain allowlist — the site's domain must be allowed for that channel.
- Script placement — make sure the snippet is present in the served HTML (not stripped by a tag manager or CSP) and that it loads.
See ../integrations/widget-embed.md.
How do I open or close the widget from my own button?
Use the programmatic API: window.ChatWidget.open(), .close(), .toggle(), and .init(). Wire these to your button's click handler. See ../integrations/widget-embed.md.
Returning visitors aren't recognized
The widget stores a visitorId in the browser's localStorage. If visitors clear storage, use private/incognito mode, or switch browsers/devices, they get a new identity. See ../integrations/widget-embed.md.
Can I register a custom JavaScript tool in the widget?
No. There is no client-tool JS registration API in the widget. Client-side agent tools are defined in HelpStack as CLIENT_SIDE agent tools and run in the visitor's browser through the widget. See ../guides/08-agent-tools.md and the technical reference in ../integrations/custom-agent-tools.md.
Webhooks & integrations#
Webhook verification keeps failing
The provider sends a challenge during setup that must echo back your verify token. Make sure the token configured at the provider exactly matches the corresponding env var (FACEBOOK_VERIFY_TOKEN, INSTAGRAM_VERIFY_TOKEN, WHATSAPP_VERIFY_TOKEN). See ../integrations/webhooks.md.
Incoming webhook events are rejected as unauthorized
HelpStack verifies an HMAC signature on incoming payloads. Confirm the app secret (e.g. FACEBOOK_APP_SECRET) is set correctly and that no proxy rewrites the raw request body before HelpStack reads it — signature checks run over the exact bytes received. See ../integrations/webhooks.md.
Is there an API key I can use to call the API?
No. There is no external API-key system. The dashboard and API use NextAuth session auth scoped to your organization. Widget and webhook endpoints are public but rate-limited and signature-verified. See ../integrations/api-reference.md.
An agent tool is never called by the AI
The model decides whether to call a tool based on its description. Rewrite the description to clearly state what the tool does and when to use it, and make sure the JSON-Schema parameters are accurate. Calls are logged, so check the tool's call log to see whether it was attempted. See ../guides/08-agent-tools.md for the overview and ../integrations/custom-agent-tools.md for endpoint, schema, and timeout details.
Email channel#
Emails aren't importing
Check, in order:
- IMAP credentials — the mailbox host, port, username, and password/app-password must be correct and the account must allow IMAP access.
- Dedicated mailbox or flag — use a dedicated mailbox (or the configured flag) so HelpStack knows which messages to pull and doesn't compete with another client.
EMAIL_MAX_AGE_DAYS— messages older than this window are skipped; raise it if you expect older mail to import.
Outbound email isn't being delivered
Outbound system mail relies on the SMTP_* settings. Confirm the SMTP host, port, and credentials are valid and that your sending domain is allowed to relay. See ../guides/04-channels.md.
Billing & tokens#
I can't change the plan, buy a top-up, or open billing
Billing actions are OWNER-only. Ask the organization owner to manage the plan or buy a top-up through the Stripe customer portal. See ../guides/12-billing.md.
I'm running out of tokens
Usage is metered in tokens. Either upgrade your plan (Free / Starter / Growth / Enterprise) or buy a one-time top-up. Both are done by an OWNER via the Stripe customer portal. See ../guides/12-billing.md.
Translation#
Translations look wrong on short messages
Short messages (fewer than 6 words) inherit the conversation's language instead of being independently detected, which can mislabel a brief reply like "ok" or "thanks". Set a fallback/expected language for the conversation so short messages resolve correctly. See ../guides/02-conversations.md.
Notifications#
Push notifications don't work on my iPhone
On iOS, web push requires the site to be added to the Home Screen (installed as a PWA) and used through Safari — push won't fire from a regular Safari tab. Add HelpStack to your Home Screen, open it from there, and allow notifications. See ../guides/10-notifications.md.