API-Referenz

REST-API für das HelpStack-Dashboard, Widget und Webhooks.

Kurzüberblick#

Erwarten Sie eine 404-Antwort auf /api selbst und eine 401-Antwort auf authentifizierte Endpunkte. Unter der blanken URL https://helpstack.eu/api gibt es keine Route — sie gibt 404 by design zurück, da die API aus Unterpfaden besteht (/api/conversations, /api/channels, …), kein durchsuchbares Stammverzeichnis. Wenn Sie einen echten Endpunkt wie /api/conversations im Browser öffnen, erhalten Sie 401 (kein Sitzungs-Cookie), was bestätigt, dass er existiert und authentifizierungsgeschützt ist. Keiner dieser Statuswerte ist ein Fehler.

Authentifizierungsmodell — bitte zuerst lesen#

Derzeit gibt es kein öffentliches API-Schlüssel- oder Bearer-Token-System für externe Aufrufer. Suchen Sie nicht nach einem „API-Schlüssel" — es gibt keinen. Die Dashboard-/interne API wird mit dem NextAuth-Sitzungs-Cookie eines angemeldeten Benutzers authentifiziert, und jede Anfrage wird durch Middleware automatisch auf die Organisation dieses Benutzers beschränkt (withOrganization / withAdmin / withAgent). Diese Endpunkte werden von der HelpStack-Dashboard-Benutzeroberfläche genutzt.

Um Dashboard-Endpunkte von außerhalb des Browsers aufzurufen, müssen Sie ein authentifiziertes Sitzungs-Cookie wiederverwenden. Wenn Sie Machine-to-Machine-Zugriff benötigen, sind die unterstützten öffentlichen Oberflächen:

• Widget-Endpunkte — öffentlich, IP/Besucher rate-limitiert (siehe Widget-Einbettung).
• Webhook-Endpunkte — öffentlich, durch Token + HMAC-Signatur verifiziert (siehe Webhooks).

Behandeln Sie alles, was ein Sitzungs-Cookie erfordert, bei programmatischer Nutzung als „gegen Ihre Deployment verifizieren".

Antwort-Envelope#

Alle API-Routen geben einen Standard-Envelope zurück.

Erfolg

{ "success": true, "data": { } }

Fehler

{
  "success": false,
  "error": {
    "message": "Human-readable message",
    "code": "OPTIONAL_CODE",
    "fields": { "fieldName": ["error 1"] }
  }
}

code und fields sind optional. fields wird bei Validierungsfehlern (Zod) mit feldspezifischen Meldungen befüllt.

Fehlercodes & HTTP-Status#

Fehler werden durch typisierte Fehlerklassen und einen zentralen Handler erzeugt. Übergeordnete Zuordnung:

Zod-Validierungsfehler geben 400 mit code: "VALIDATION_ERROR" und einem fields-Objekt zurück. Unerwartete Fehler geben 500 mit einer generischen Meldung zurück ("An unexpected error occurred"); das tatsächliche Detail wird nur serverseitig protokolliert.

Endpunkt-Katalog#

Rollen: Ein mit ADMIN markierter Endpunkt erfordert Admin-Rechte (withAdmin), AGENT erfordert Mitarbeiter-Rechte oder höher (withAgent), Sitzung erfordert ein authentifiziertes Organisationsmitglied (withOrganization).

Kanäle

Kanal erstellen — POST /api/channels (validierter Body, createChannelSchema):

{
  "type": "WEBSITE_CHAT",
  "name": "Website Chat",
  "region": "eu",
  "defaultLanguage": "en",
  "autoTranslate": true,
  "translateToLanguage": "en",
  "fallbackLanguage": "sl",
  "aiProviderId": "PROVIDER_ID",
  "credentials": {},
  "responseTemplate": {},
  "autoReply": false,
  "autoApprove": false,
  "autoEnhance": false
}

Die Strukturen der Anmeldedaten (credentials) werden je nach Kanaltyp separat validiert — z. B. erfordert E-Mail { host, port, username, password, from, secure?, imapHost?, imapPort?, imapSecure?, imapAllowSelfSigned? }; Facebook erfordert { pageId, accessToken, appSecret? }; Instagram erfordert { accountId, accessToken }. Anmeldedaten werden verschlüsselt gespeichert (AES-256-GCM).

Gespräche

status-Filterwerte: OPEN | PENDING | CLOSED | ARCHIVED. pageSize ist auf 100 begrenzt (Standard 20).

Nachricht senden — POST /api/conversations/[id]/messages (validierter Body, sendMessageSchema):

{
  "conversationId": "CONVERSATION_ID",
  "content": "Thanks for reaching out — here's how to fix that.",
  "attachments": ["storage/path/file.png"]
}

Verhalten: Die Nachricht wird als OUTBOUND erstellt. Wenn der Kanal autoTranslate aktiviert hat und eine Kundensprache bekannt ist, wird die Nachricht nicht freigegeben erstellt und im Hintergrund übersetzt (der Mitarbeiter genehmigt sie vor dem Senden). Das Senden verbraucht Plan-Token; wenn der Organisation die Token ausgegangen sind, gibt die Route 402 mit code: "INSUFFICIENT_TOKENS" zurück. Bei Erfolg gibt die Route die erstellte Nachricht mit HTTP 201 zurück.

Nachrichten

FAQs

Medien

Benachrichtigungen

KI-Anbieter

Agent-Tools

Die vollständige Tool-Anatomie finden Sie unter Benutzerdefinierte Agent-Tools.

Widget (öffentlich)

Payloads finden Sie unter Widget-Einbettung.

Webhooks (öffentlich)

Handshake- und Signaturdetails finden Sie unter Webhooks.

Verwandte Themen#

• Widget-Einbettung
• Webhooks
• E-Mail-Kanal
• Benutzerdefinierte Agent-Tools
• Kanäle-Leitfaden
• Glossar