Eigene Systeme

Auf dieser Seite

• Eigene Aktion
• Freigabe und Wertgrenze
• Eigener MCP-Server
• Mit Anmeldung verbinden (Notion, Linear, Atlassian)
• Statuspage
• Angemeldete Kunden
• Paldra API

Eigene Aktion

Tarif: Eigene Aktionen und eigene MCP-Server gibt es ab Business – dort bis zu 3 Aktionen und MCP-Werkzeuge zusammen und ein MCP-Server. Mit Enterprise bis zu 10 Aktionen und 5 MCP-Server.

Was passiert: Passt eine Frage zur Beschreibung, ruft der Chatbot dein System auf und formuliert die Antwort ausschließlich aus dem, was dein System zurückgibt. Geht auch mit Make und n8n (Webhook mit Antwort).

Bearbeiten und testen

Unter jeder Aktion stehen Bearbeiten (lädt sie ins Formular; Schlüssel und Token-Geheimnis bleiben, wenn du die Felder leer lässt) und Jetzt testen: Du trägst Beispielwerte ein, Paldra ruft dein System wirklich auf und zeigt Status, Dauer und den Anfang der Antwort. Bei POST fragt die Seite vorher nach – dein System führt die Aktion dann wirklich aus. Kopfzeilen und Schlüssel werden nie angezeigt.

Sicherheit & Grenzen

Je Aktion (beim MCP-Server je Server) unter Sicherheit & Grenzen:

• Nur für geprüfte Kunden (Vorgabe an, auch für bestehende Aktionen): Im Chat, auf WhatsApp und Instagram fragt der Chatbot nach der E-Mail-Adresse und schickt einen 6-stelligen Code (10 Minuten gültig, höchstens 5 Versuche). Angemeldete Kunden sind schon bestätigt. In Mails gilt nur eine technisch geprüfte Absenderadresse (DMARC/DKIM); sonst ruft der Chatbot nichts ab, und eine Aktion übernimmt ein Mitarbeiter. Code-Mails sind zusätzlich je Adresse, je Anfragendem und je Shop begrenzt. Erst danach läuft die Aktion – auch eine, die nur liest. Die bestätigte Adresse bekommt dein System in X-Alpheris-Customer-Email (bei der Eigenen Aktion mitsigniert).
• Höchstens je Gespräch (Vorgabe 3) und je Tag (Vorgabe 200, gezählt über 24 Stunden). Ist eine Grenze erreicht, sagt der Chatbot dem Kunden ehrlich, dass er es gerade nicht nachsehen kann.
• Abschalten nach Fehlern in Folge (Vorgabe 5): Antwortet dein System so oft hintereinander mit einem Fehler, schaltet Paldra die Aktion ab. Im Dashboard steht dann ein Hinweis mit dem letzten Fehler und Wieder einschalten; auch Speichern der Aktion schaltet sie wieder ein.
• Kanäle: Chat, E-Mail, WhatsApp und Instagram (Vorgabe alle). In anderen Kanälen bietet der Chatbot die Aktion nicht an.

Freigabe, Wertgrenze und was der Kunde erfährt

Unter jeder Aktion, die etwas ändert (Eigene Aktion mit POST, MCP-Werkzeug, das nicht nur liest), steht Freigabe:

• Wertgrenze: „Wenn Angabe > Wert, dann Entwurf oder Mitarbeiter“. Darunter gilt die Stufe, die du für die Aktion eingestellt hast (z. B. KI antwortet). Zur Auswahl stehen die Angaben vom Typ Zahl oder Ganze Zahl. Ein Wert, der keine Zahl ist, zählt als darüber. Die Grenze hebt die Stufe nur an, nie ab. Shopify-Erstattungen behalten ihre eigene Betragsgrenze aus den Shopify-Regeln.
• Wer darf freigeben: alle mit dem Team-Recht „Aktionen freigeben“ (Inhaber und Admins immer) oder nur bestimmte Personen. API-Schlüssel und verbundene Apps dürfen nie freigeben.

Annehmen im Chat, auf WhatsApp und Instagram: Hat die KI eine Aktion im Gespräch vorbereitet, führt Annehmen in der Inbox sie aus. Das Ergebnis steht danach an der Aktion (Erledigt oder Fehlgeschlagen mit Grund), und der Kunde bekommt im selben Kanal eine kurze Nachricht: „Erledigt: … ist ausgeführt.“ oder „Das hat leider nicht geklappt: … Unser Team kümmert sich darum und meldet sich bei dir.“ Beim Ablehnen schreibt Paldra nichts – warum, sagst du dem Kunden selbst.

Für Entwickler: Aufrufe prüfen, lange Aufträge, API

Bei jeder Eigenen Aktion findest du im Dashboard den Knopf Für Entwickler: Signatur-Geheimnis, Shop-ID, Rückmelde-Adresse und einen fertigen Auftrag zum Kopieren – für deinen Entwickler oder für Claude Code („Binde diese Paldra-Aktion in unser System ein“). So verbindest du auch ein eigenes SaaS, z. B. „erstelle dem Kunden einen Businessplan“.

Aufrufe prüfen (HMAC)

Jeder Aufruf trägt X-Alpheris-Timestamp, X-Alpheris-Request-Id und X-Alpheris-Signature: v1=…, bei bestätigten Kunden zusätzlich X-Alpheris-Customer-Email (angemeldet, per Code bestätigt oder bei Mails ein technisch geprüfter Absender). Signiert wird HMAC-SHA256(Geheimnis, "<timestamp>.<request_id>.<customer_email>.<body>") – <body> ist bei POST der rohe JSON-Text, bei GET der Query-String ohne „?“. Lehne Aufrufe ab, deren Zeitstempel mehr als 5 Minuten abweicht.

import hmac, hashlib, time

def alpheris_ok(geheimnis: str, kopf: dict, body: bytes) -> bool:
    ts = kopf.get("X-Alpheris-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    basis = f"{ts}.{kopf.get('X-Alpheris-Request-Id', '')}.{kopf.get('X-Alpheris-Customer-Email', '')}.".encode() + body
    soll = "v1=" + hmac.new(geheimnis.encode(), basis, hashlib.sha256).hexdigest()
    return hmac.compare_digest(soll, kopf.get("X-Alpheris-Signature", ""))

const crypto = require("crypto");
function alpherisOk(geheimnis, h, rawBody) {
  const ts = h["x-alpheris-timestamp"] || "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const basis = `${ts}.${h["x-alpheris-request-id"] || ""}.${h["x-alpheris-customer-email"] || ""}.` + rawBody;
  const soll = "v1=" + crypto.createHmac("sha256", geheimnis).update(basis).digest("hex");
  const ist = h["x-alpheris-signature"] || "";
  return soll.length === ist.length && crypto.timingSafeEqual(Buffer.from(soll), Buffer.from(ist));
}

Anmeldung mit Token (OAuth, Login)

Verlangt dein System zuerst einen Token, trägst du im Formular unter „Anmeldung mit Token“ die Token-Adresse, Schlüssel und Geheimnis ein – Paldra holt den Token selbst, hält ihn bis kurz vor Ablauf und holt ihn bei 401 einmal neu. Zwei Arten: OAuth 2 Client Credentials (z. B. Haufe axera link: Token-Adresse des Anbieters, Client-ID, Client-Secret) und Login per JSON (z. B. casavi: POST …/v2/authenticate mit den Feldern deines Anbieters, Token-Feld token, Kopfzeile token ohne Präfix; facilioo: Login mit API-Key). Das Geheimnis wird verschlüsselt gespeichert und nie angezeigt.

Anmeldung per OAuth („Mit X verbinden“)

Meldet man sich bei deinem System über eine Anmeldeseite an (OAuth 2 Authorization Code), richtest du das unter der Liste deiner Eigenen Aktionen bei „Anmeldung einrichten“ ein: Autorisierungs-Adresse, Token-Adresse, Client-ID, Client-Secret, Scopes und optional die Widerrufs-Adresse. Trage beim Anbieter die angezeigte Rückkehradresse https://app.alpheris.com/integrations/oauth/callback ein und tippe auf „Mit Anbieter verbinden“. Paldra nutzt PKCE (S256), speichert den Zugang verschlüsselt, schickt ihn als Authorization: Bearer … mit, erneuert ihn vor Ablauf und nach einem 401 einmal. Die Anmeldung bleibt erhalten, wenn du die Aktion bearbeitest.

Lange Aufträge

Braucht dein System länger als 8 Sekunden (z. B. ein Dokument erstellen), antworte sofort mit 202 und {"auftrag_id": "…", "hinweis": "Dauert etwa 2 Minuten."}. Der Chatbot sagt dem Kunden, dass es läuft. Ist das Ergebnis da, meldest du es signiert (gleiches Geheimnis, eigener Zeitstempel und eigene Request-Id) an https://api.alpheris.com/public/aktionen/rueckmeldung – mit der Kopfzeile X-Alpheris-Shop. Das Ergebnis erscheint im Chat des Kunden. status: fertig, fehler oder laeuft (Zwischenstand, höchstens drei).

curl -X POST https://api.alpheris.com/public/aktionen/rueckmeldung \
  -H "Content-Type: application/json" \
  -H "X-Alpheris-Shop: 148" -H "X-Alpheris-Timestamp: $TS" -H "X-Alpheris-Request-Id: $ID" \
  -H "X-Alpheris-Signature: v1=$SIG" \
  -d '{"auftrag_id":"bp-77","status":"fertig","text":"Dein Businessplan ist fertig.","link":"https://dein-system.de/p/77"}'

Aktionen per API anlegen

Mit einem API-Schlüssel legt dein Entwickler (oder Claude Code) Aktionen direkt an: GET/POST /v1/aktionen, DELETE /v1/aktionen/{domain}. Gleiche Felder und Prüfungen wie im Dashboard (dazu optional grenzen, z. B. {"je_gespraech": 3, "je_tag": 200, "aus_nach": 5, "kanaele": ["chat", "mail"]}); beim ersten Anlegen kommt das Signatur-Geheimnis einmal in der Antwort (geheimnis). Details in der API-Referenz.

curl -X POST "$ALPHERIS_BASE_URL/v1/aktionen" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Businessplan erstellen", "beschreibung": "Wenn ein Kunde einen Businessplan möchte",
       "url": "https://dein-system.de/alpheris/businessplan", "methode": "POST", "stufe": "kunde",
       "parameter": [{"name": "Branche", "typ": "auswahl", "werte": ["Café", "Handwerk"], "pflicht": true},
                     {"name": "Budget", "typ": "zahl"}],
       "antwort_felder": ["status", "plan.titel"]}'

Eigener MCP-Server

Was passiert: Passt eine Frage zu einem Werkzeug, ruft der Chatbot es auf und antwortet aus dem Ergebnis - wie Fin mit MCP-Connectoren. Bis zu fünf Server mit Enterprise, einer mit Business – dort wählst du je Werkzeug mit „Nutzen“, welches einen der 3 Plätze belegt. Sicherheit & Grenzen gelten wie bei der Eigenen Aktion (je Server, gezählt je Werkzeug); die bestätigte Adresse kommt in der Kopfzeile X-Alpheris-Customer-Email.

Mit Anmeldung verbinden (Notion, Linear, Atlassian)

Notion, Linear und Atlassian (Jira, Confluence) bieten eigene MCP-Server mit Anmeldung an. Du brauchst dafür keinen Schlüssel und keine Entwickler-App: Du meldest dich beim Anbieter an und erlaubst Paldra den Zugriff.

Eigener MCP-Server mit Anmeldung: Verlangt dein Server eine Anmeldung (Antwort 401 mit WWW-Authenticate), trägst du nur die Adresse ein und tippst auf „Mit Anmeldung verbinden“. Paldra liest die Anmeldedaten des Servers (OAuth Protected Resource Metadata, Authorization Server Metadata), meldet sich dort als App an (Dynamic Client Registration) und öffnet die Anmeldung. Bietet dein Server keine automatische App-Anmeldung an, verbinde ihn mit einem Zugangstoken.

Was Paldra speichert: den Zugang verschlüsselt, die gewährten Rechte und den Ablauf. Paldra erneuert den Zugang selbst, kurz bevor er abläuft. Lehnt der Anbieter die Erneuerung ab, steht auf der Kachel „Anmeldung abgelaufen“, du bekommst eine E-Mail, und der Chatbot benutzt die Werkzeuge erst wieder nach „Neu verbinden“. Beim Trennen widerruft Paldra den Zugang beim Anbieter, soweit er das anbietet.

Rückkehradresse (für Eigene Aktionen mit Anmeldung): https://app.alpheris.com/integrations/oauth/callback

Statuspage

Was passiert: Fragt jemand nach einer Störung („Geht die Kasse gerade nicht?“), antwortet der Chatbot mit den offenen Störungen und Wartungen deiner Statusseite - oder dass alles normal läuft.

Workflows

Was passiert: Tritt das Ereignis ein und passen die Bedingungen, schickt Paldra es innerhalb weniger Sekunden an das Ziel – jedes Ereignis genau einmal. An eine Adresse geht derselbe JSON-Körper wie bei den Webhooks, signiert mit dem Geheimnis des Workflows (im Dashboard unter „Geheimnis“); eine Eigene Aktion bekommt {"ereignis", "workflow", "daten"}, signiert mit ihrem Geheimnis und der Kopfzeile X-Alpheris-Event. Bei jedem Workflow steht, wann er zuletzt gelaufen ist und ob es geklappt hat.

Angemeldete Kunden

Was passiert: Stimmt die Signatur, steht die E-Mail als bestätigt im Gespräch. Bestellstatus und offene Rechnungen nennt der Chatbot dann ohne Nachfrage, wenn die E-Mail zur Bestellung oder Rechnung passt; Eigene Aktionen und MCP-Werkzeuge laufen ohne Code. Ohne gültige Signatur ändert sich nichts.

Paldra API

Was passiert: Dein System liest und schreibt Gespräche, Tickets und Leads. Details stehen in der API-Referenz.

Eigene Aktion: PUT, PATCH, DELETE, Kopfzeilen, JSON-Body mit Platzhaltern, GraphQL

Unter „Mehr: Kopfzeilen, JSON-Body mit Platzhaltern, GraphQL“ im Formular der Eigenen Aktion (oder per /v1/aktionen) geht mehr als GET und POST:

• Methoden: GET und DELETE schicken die Angaben in der Adresse, POST, PUT und PATCH als JSON. PUT und PATCH starten mindestens mit der Stufe Entwurf; DELETE führt die KI nie allein aus – nur nach „Kunde bestätigt“, als Entwurf oder durch einen Mitarbeiter.
• Weitere Kopfzeilen: bis zu 8, Werte verschlüsselt gespeichert (z. B. CF-Access-Client-Id und CF-Access-Client-Secret für Cloudflare Access). Nicht erlaubt: Host, Content-Length, Content-Type und alle X-Alpheris-….
• JSON-Body mit Platzhaltern: gültiges JSON mit Platzhaltern {{angabe}} in Anführungszeichen, beliebig verschachtelt. Steht ein Platzhalter allein im String, wird der Wert mit seinem Typ eingesetzt (Zahl bleibt Zahl); fehlt eine optionale Angabe, fällt der Schlüssel weg.
• GraphQL: POST mit query und einer variables mit Platzhaltern. Eine query liest nur, eine mutation ist eine Aktion mit Stufe. Antwortet der Server nur mit errors, gilt der Aufruf als gescheitert.

{
  "kunde": { "email": "{{email}}", "name": "{{name}}" },
  "positionen": [ { "sku": "{{artikel}}", "menge": "{{menge}}" } ],
  "notiz": "Bestellt im Chat: {{artikel}}"
}

Der OpenAPI-Import liest jetzt auch YAML (openapi.yaml) und schlägt Aktionen für GET, POST, PUT, PATCH und DELETE vor. Signatur, Adressprüfung, 8 Sekunden Zeitlimit und „keine Umleitungen“ gelten für alle Methoden gleich; der Body ist auf 100 KB begrenzt.

Steht dein System nicht im öffentlichen Internet (Warenwirtschaft, Hausverwaltung, ERP im Firmennetz), lies Interne Systeme anbinden.

Nachschlagetabellen

Für Wissen, das in einer Tabelle steht: Lieferzonen nach PLZ, Öffnungszeiten je Filiale, Ersatzteilnummern, Wartungsverträge, Wohnungen und Ansprechpartner. Die KI schlägt darin nach – nur lesen, nie schreiben.

Was passiert: Fragt ein Kunde etwas, das in einer Tabelle steht, holt die KI höchstens fünf passende Zeilen und formuliert die Antwort nur daraus. Mit Kundenprüfung bekommt nur ein sicher erkannter Kunde etwas – im Chat angemeldet über Angemeldete Kunden, in der Mail über seine Absenderadresse, wenn deren Echtheit per DKIM/DMARC geprüft ist – und nur Zeilen mit seiner eigenen E-Mail-Adresse. Eine im Chat eingetippte Adresse genügt nie.