Referenz

Fehlerbehebung & FAQ

Häufige Probleme und deren Behebung, gruppiert nach Benutzergruppe. Jeder Eintrag enthält eine konkrete Lösung und verweist auf die ausführliche Dokumentation. Ersetzen Sie GROSSBUCHSTABEN-Platzhalter durch Ihre eigenen Werte. Die Produktionsdomain ist helpstack.eu.

Mitarbeiter & Administratoren#

Ein Teammitglied kann Einstellungen nicht sehen oder die Konfiguration nicht ändern

Die Rolle ist wahrscheinlich AGENT oder VIEWER. Mitarbeiter haben nur Lesezugriff auf Einstellungen, und Viewer haben nur Lesezugriff auf Gespräche und Analysen. Bitten Sie einen OWNER oder ADMIN, die Rolle zu ändern. Siehe ../guides/09-team-and-roles.md.

Ich erhalte keine Benachrichtigungen über neue Gespräche

Überprüfen Sie Ihre Benachrichtigungseinstellungen für das Ereignis (NEW_CONVERSATION / NEW_MESSAGE / ASSIGNED / STATUS_CHANGED) und den Kanal (IN_APP, EMAIL, PUSH usw.). Wenn der Umfang ASSIGNED_ONLY ist, erhalten Sie nur Benachrichtigungen für Gespräche, die Ihnen zugewiesen sind — wechseln Sie zu ALL, um über alles benachrichtigt zu werden. Siehe ../guides/10-notifications.md.

Ein Gespräch ist aus meinem Posteingang verschwunden

Überprüfen Sie seinen Status. Gespräche wechseln von OPEN → PENDING → CLOSED, und Ihr Posteingang-Filter blendet möglicherweise CLOSED- (oder PENDING-) Threads aus. Entfernen oder erweitern Sie den Statusfilter. Siehe ../guides/02-conversations.md.

Meine interne Notiz wurde an den Kunden gesendet

Interne Notizen sind privat für Ihr Team und werden niemals an den Kunden zugestellt — wenn der Kunde Text erhalten hat, wurde er als OUTBOUND-Antwort hinzugefügt, nicht als Notiz. Stellen Sie sicher, dass Sie das Notizfeld verwenden, nicht das Antwortfeld. Siehe ../guides/02-conversations.md.

KI & Wissensdatenbank#

KI-Antworten sind generisch, vage oder falsch

Zwei Dinge fundieren die KI: ein System-Prompt und Wissen. Schreiben Sie zunächst einen klaren kanalspezifischen System-Prompt, der Persona, Ton und Regeln festlegt. Hängen Sie dann die relevanten Wissensdatenbank-Gruppen an den Kanal an, damit Antworten über RAG auf Ihren eigenen Inhalten basieren. Ohne angehängte Wissensdatenbank-Gruppen verfügt das Modell nur über allgemeines Wissen. Siehe ../guides/03-ai-replies.md und ../guides/05-knowledge-base.md.

Es gibt nirgendwo eine KI-Antwortoption

Sie benötigen mindestens einen konfigurierten KI-Anbieter (OpenAI, Anthropic, Azure OpenAI oder Ollama) mit einem gesetzten Modell, und einen als Organisationsstandard markierten Anbieter. Fügen Sie einen Anbieter in den Einstellungen hinzu und markieren Sie ihn dann als Standard. Siehe ../guides/03-ai-replies.md.

Ein Wissensdatenbank-Artikel ist fehlgeschlagen oder zeigt einen Fehler

Artikel durchlaufen PROCESSING → READY/ERROR. Wenn ein Artikel in PROCESSING verbleibt, geben Sie dem Scraping/Upload Zeit zum Abschluss; wenn er ERROR anzeigt, ist die Quell-URL möglicherweise nicht erreichbar oder die hochgeladene Datei wird nicht unterstützt — fügen Sie ihn mit einer gültigen Quelle erneut hinzu. Nur READY-Artikel werden für RAG verwendet. Siehe ../guides/05-knowledge-base.md.

Die KI ignoriert meine Wissensdatenbank

Vergewissern Sie sich, dass die Wissensdatenbank-Gruppe, die diese Artikel enthält, tatsächlich an den Kanal angehängt ist, der das Gespräch bearbeitet, und dass die Artikel READY sind (nicht PROCESSING/ERROR). Die Wissensdatenbank-Fundierung erfolgt pro Kanal über angehängte Gruppen. Siehe ../guides/05-knowledge-base.md.

FAQs und die Wissensdatenbank sind verschiedene Funktionen. FAQs (Frage ≤280 Zeichen, Antwort ≤2000 Zeichen) steuern die Chips in der Widget-Begrüßung und müssen organisationsweit oder auf dem jeweiligen WEBSITE_CHAT-Kanal definiert sein. Die Wissensdatenbank fundiert KI-Antworten und erstellt keine Begrüßungs-Chips. Siehe ../guides/06-faqs.md.

Entwürfe werden nie automatisch gesendet

Der automatische Antwortmodus des Kanals ist wahrscheinlich off oder prepare. prepare erstellt einen Entwurf, wartet aber auf die Genehmigung durch einen Mitarbeiter; nur auto-approve sendet ohne Überprüfung. Setzen Sie den Modus auf auto-approve, wenn Sie automatisches Senden wünschen. Siehe ../guides/03-ai-replies.md.

Kanäle & Messaging#

Facebook-Nachrichten kommen nicht an

Gehen Sie der Reihe nach vor:

Verify-Token-Nichtübereinstimmung — der Token in Ihrer Facebook-App muss exakt mit FACEBOOK_VERIFY_TOKEN übereinstimmen, sonst schlägt die Verifizierungs-Challenge fehl und der Webhook wird nie abonniert.
Signaturfehler — FACEBOOK_APP_SECRET muss korrekt gesetzt sein, damit HelpStack die HMAC-Signatur bei eingehenden Payloads validieren kann; ein falsches Secret lehnt Ereignisse still ab.
Seiten-Abonnement — bestätigen Sie, dass die Facebook-Seite das Webhook Ihrer App mit aktivierten Messaging-Feldern abonniert hat.

Siehe ../integrations/webhooks.md.

Instagram- oder WhatsApp-Nachrichten kommen nicht an

Dieselbe Prüfliste wie bei Facebook, mit den entsprechenden Umgebungsvariablen: INSTAGRAM_VERIFY_TOKEN für Instagram und WHATSAPP_VERIFY_TOKEN für WhatsApp. Bestätigen Sie, dass der Verify-Token übereinstimmt, die Signatur/das Secret korrekt ist und das Konto/die Nummer das Webhook abonniert hat. Siehe ../integrations/webhooks.md.

Ich kann keine Telegram-Kanal-Option finden

TELEGRAM ist im Schema vorhanden, aber noch nicht in der Benutzeroberfläche verfügbar. Verwenden Sie EMAIL, FACEBOOK, INSTAGRAM, WHATSAPP oder WEBSITE_CHAT. Siehe ../guides/04-channels.md.

Überprüfen Sie der Reihe nach:

CHANNEL_ID — die id in der Script-URL muss Ihre WEBSITE_CHAT-Kanal-ID sein: <script src="https://helpstack.eu/widget.js?id=CHANNEL_ID" async></script>.
Domain-Allowlist — die Domain der Website muss für diesen Kanal erlaubt sein.
Script-Platzierung — stellen Sie sicher, dass der Snippet im ausgelieferten HTML vorhanden ist (nicht durch einen Tag-Manager oder CSP entfernt wurde) und dass er geladen wird.

Siehe ../integrations/widget-embed.md.

Verwenden Sie die programmatische API: window.ChatWidget.open(), .close(), .toggle() und .init(). Verknüpfen Sie diese mit dem Click-Handler Ihrer Schaltfläche. Siehe ../integrations/widget-embed.md.

Wiederkehrende Besucher werden nicht erkannt

Das Widget speichert eine visitorId im localStorage des Browsers. Wenn Besucher den Speicher leeren, den privaten/Inkognito-Modus verwenden oder den Browser/das Gerät wechseln, erhalten sie eine neue Identität. Siehe ../integrations/widget-embed.md.

Nein. Es gibt keine clientseitige Tool-JS-Registrierungs-API im Widget. Clientseitige Agent-Tools werden in HelpStack als CLIENT_SIDE-Agent-Tools definiert und im Browser des Besuchers über das Widget ausgeführt. Siehe ../guides/08-agent-tools.md und die technische Referenz unter ../integrations/custom-agent-tools.md.

Webhooks & Integrationen#

Die Webhook-Verifizierung schlägt weiterhin fehl

Der Anbieter sendet während der Einrichtung eine Challenge, die Ihren Verify-Token zurückgeben muss. Stellen Sie sicher, dass der beim Anbieter konfigurierte Token genau mit der entsprechenden Umgebungsvariable übereinstimmt (FACEBOOK_VERIFY_TOKEN, INSTAGRAM_VERIFY_TOKEN, WHATSAPP_VERIFY_TOKEN). Siehe ../integrations/webhooks.md.

Eingehende Webhook-Ereignisse werden als nicht autorisiert abgelehnt

HelpStack verifiziert eine HMAC-Signatur bei eingehenden Payloads. Bestätigen Sie, dass das App-Secret (z. B. FACEBOOK_APP_SECRET) korrekt gesetzt ist und dass kein Proxy den rohen Request-Body umschreibt, bevor HelpStack ihn liest — Signaturprüfungen laufen über die exakt empfangenen Bytes. Siehe ../integrations/webhooks.md.

Gibt es einen API-Schlüssel, mit dem ich die API aufrufen kann?

Nein. Es gibt kein externes API-Schlüsselsystem. Das Dashboard und die API verwenden NextAuth-Sitzungsauthentifizierung, die auf Ihre Organisation beschränkt ist. Widget- und Webhook-Endpunkte sind öffentlich, aber rate-limitiert und signaturverifiziert. Siehe ../integrations/api-reference.md.

Ein Agent-Tool wird von der KI nie aufgerufen

Das Modell entscheidet anhand der Beschreibung, ob ein Tool aufgerufen werden soll. Schreiben Sie die Beschreibung neu, um klar anzugeben, was das Tool tut und wann es verwendet werden soll, und stellen Sie sicher, dass die JSON-Schema-Parameter korrekt sind. Aufrufe werden protokolliert — überprüfen Sie das Aufrufprotokoll des Tools, um zu sehen, ob ein Versuch unternommen wurde. Siehe ../guides/08-agent-tools.md für die Übersicht und ../integrations/custom-agent-tools.md für Endpunkt-, Schema- und Timeout-Details.

E-Mail-Kanal#

E-Mails werden nicht importiert

Überprüfen Sie der Reihe nach:

IMAP-Anmeldedaten — Host, Port, Benutzername und Passwort/App-Passwort des Postfachs müssen korrekt sein und das Konto muss IMAP-Zugriff erlauben.
Dediziertes Postfach oder Flag — verwenden Sie ein dediziertes Postfach (oder das konfigurierte Flag), damit HelpStack weiß, welche Nachrichten abgerufen werden sollen, und nicht mit einem anderen Client konkurriert.
EMAIL_MAX_AGE_DAYS — Nachrichten, die älter als dieses Zeitfenster sind, werden übersprungen; erhöhen Sie den Wert, wenn Sie erwarten, dass ältere E-Mails importiert werden sollen.

Siehe ../guides/04-channels.md.

Ausgehende E-Mails werden nicht zugestellt

Ausgehende System-E-Mails basieren auf den SMTP_*-Einstellungen. Bestätigen Sie, dass SMTP-Host, Port und Anmeldedaten gültig sind und dass Ihre Versanddomain das Relaying erlaubt. Siehe ../guides/04-channels.md.

Abrechnung & Token#

Ich kann den Plan nicht ändern, eine Aufladung kaufen oder die Abrechnung öffnen

Abrechnungsaktionen sind nur für OWNER verfügbar. Bitten Sie den Organisationsinhaber, den Plan zu verwalten oder eine Aufladung über das Stripe-Kundenportal zu kaufen. Siehe ../guides/12-billing.md.

Mir gehen die Token aus

Die Nutzung wird in Token gemessen. Entweder upgraden Sie Ihren Plan (Free / Starter / Growth / Enterprise) oder kaufen Sie eine einmalige Aufladung. Beides erfolgt durch einen OWNER über das Stripe-Kundenportal. Siehe ../guides/12-billing.md.

Übersetzung#

Übersetzungen sehen bei kurzen Nachrichten falsch aus

Kurze Nachrichten (weniger als 6 Wörter) übernehmen die Gesprächssprache, anstatt unabhängig erkannt zu werden, was eine kurze Antwort wie „ok" oder „danke" falsch beschriften kann. Legen Sie eine Fallback-/erwartete Sprache für das Gespräch fest, damit kurze Nachrichten korrekt aufgelöst werden. Siehe ../guides/02-conversations.md.

Benachrichtigungen#

Push-Benachrichtigungen funktionieren nicht auf meinem iPhone

Unter iOS erfordert Web-Push, dass die Website zum Home-Bildschirm hinzugefügt (als PWA installiert) und über Safari verwendet wird — Push funktioniert nicht aus einem normalen Safari-Tab. Fügen Sie HelpStack zu Ihrem Home-Bildschirm hinzu, öffnen Sie es von dort und erlauben Sie Benachrichtigungen. Siehe ../guides/10-notifications.md.