# Make Agent Fast documentation (de)

---

# Änderungsprotokoll

Source: /de/docs/account/changelog.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Plattform&#x22;, icon: &#x22;spark&#x22; }, { label: &#x22;API&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;Dokumentation&#x22;, icon: &#x22;book&#x22; }]" />

## 2026-08-27 [#2026-08-27]

* Den Start per URL-zu-Agent dokumentiert: Generierungswartezeit, Prüfen und veröffentlichen, Genehmigen und veröffentlichen sowie Aktivierung beim ersten Besucher-Chat oder Lead.
* Das Erscheinungsbild **Website verwenden** im Vergleich zu Hell/Dunkel dokumentiert sowie die Tatsache, dass das Speichern des Erscheinungsbilds das Live-Embed (und übrig gebliebene gehostete Seiten) ohne erneute Veröffentlichung aktualisiert.
* Embed-Snippets an die aktuellen Attribute von `embed.js` und den `?v=`-Cache-Buster des Dashboards angepasst.
* Live-Gespräche im Plattform-Tester im Vergleich zur veröffentlichten Website und zum Embed dokumentiert.
* Eigene Domain, Domainkauf und Subdomain-Einstellungen als Produktfunktion entfernt. Binden Sie den Agent in die bestehende Website des Kunden ein. Übrig gebliebene Polar-Ereignisse zum Domain-Add-on werden weiterhin ignoriert oder storniert.

## 2026-07-28 [#2026-07-28]

* Verlauf der Nutzung vereinfacht: Statt getrennter Reservierungs- und Erstattungseinträge werden nun die tatsächlich verbrauchten Credits angezeigt; sehr geringe Nutzung wird als `<0.001` dargestellt.
* Auswahlecken im Aktionsmenü der Dokumentation passen sich nun mehrzeiligen Inhalten an, wobei die Geometrie von Auslöser und Menü weiterhin übereinstimmt.
* Englische, koreanische und usbekische Anleitungen erweitert, u. a. zu Abrechnung von Live-Anrufen, Medieneingabe im visuellen Builder, Änderungen an gehosteten Subdomains, Datenschutz- und Sicherheitseinstellungen des Kontos sowie zum Ereignis-Feed der Benachrichtigungen.

## 2026-07-15 [#2026-07-15]

* Zweisprachige Dokumentationsplattform von Make Agent Fast eingeführt.
* Markdown pro Seite, Downloads, Suche sowie ChatGPT- und Claude-Aktionen hinzugefügt.
* `/docs/llms.txt`, `/docs/llms-full.txt` und kanonische `.md`-Routen hinzugefügt.
* Öffentliche API, SDK-Vertrag, Webhooks, Embeds, Connectors, Betrieb, Preise, Sicherheit und Datenschutz dokumentiert.
* Implementierungsanleitungen für gängige Frameworks und Website-Builder hinzugefügt.

## Versionierungsrichtlinie [#versionierungsrichtlinie]

Korrekturen an der Dokumentation und additive API-Felder können fortlaufend veröffentlicht werden. Für abwärtsinkompatible Änderungen an der öffentlichen API ist ein neuer Hauptpfad oder ein dokumentierter Migrationszeitraum erforderlich.

---

# Tarife und Preise

Source: /de/docs/account/pricing.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;Launch&#x22;, icon: &#x22;layers&#x22; },
{ label: &#x22;Operate&#x22;, icon: &#x22;spark&#x22; },
{ label: &#x22;Scale&#x22;, icon: &#x22;bolt&#x22; },
{ label: &#x22;Credit-Pakete&#x22;, icon: &#x22;layers&#x22; }
]"
/>

<TutorialVideo episode="ep08" start="132" />

## Tarifvergleich [#tarifvergleich]

| Tarif   | Monatliche Abrechnung | Jahresbetrag | Monatliche Credits |                                   Agents |    Live-Sprache | Branding-Badge |
| ------- | --------------------: | -----------: | -----------------: | ---------------------------------------: | --------------: | -------------- |
| Launch  |            15 $/Monat |   144 $/Jahr |               1000 |                                        1 | Nicht enthalten | Erforderlich   |
| Operate |            35 $/Monat |   336 $/Jahr |               3000 |                                        3 |   30 Min./Monat | Entfernbar     |
| Scale   |            79 $/Monat |   758 $/Jahr |               8000 | Unbegrenzt, im Rahmen der fairen Nutzung |   90 Min./Monat | Entfernbar     |

Die jährliche Abrechnung ist 20 % günstiger, als zwölfmal den Monatspreis zu zahlen. Launch und Operate beginnen mit einer siebentägigen kostenlosen Testphase ohne Kreditkarte; hinterlegen Sie nach Tag 7 eine Karte, damit der Agent weiterhin live bleibt. Scale wird sofort abgerechnet und hat keine Testphase. Wenn eine Karte erforderlich ist, zeigt der Checkout vor dem Kauf den genauen Preis, den Verlängerungszeitraum, die Steuern und die Bedingungen an.

Launch ist ein funktionsfähiger Embed-Agent noch in dieser Woche. Operate ist der nächste Schritt, sobald Ihre Kunden tatsächlich mit dem Agent sprechen – mit Live-Sprache, einem umfangreicheren Widget und Messaging-Channels. Scale ist das vollständige Studio: alle Look-Optionen, Teamrollen und Ihre eigenen Anbieter-Schlüssel.

## Funktionsübersicht [#funktionsübersicht]

| Funktion                     | Launch                                       | Operate                                                       | Scale                                                            |
| ---------------------------- | -------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
| Agents                       | 1                                            | 3                                                             | Unbegrenzt, im Rahmen der fairen Nutzung                         |
| Widget-Studio                | Akzentfarbe, Position, Hell/Dunkel           | + Launcher-Beschriftung, Voreinstellungen, zusätzliche Farben | Alle Optionen (Radius, Schatten, Rahmen, Schriftart, Glaseffekt) |
| Sprachen für Sprache         | 1                                            | 2                                                             | Alle unterstützten                                               |
| Aufnahme von Wissen          | Einfügen, URL, Dateien                       | + YouTube, Podcast, RSS                                       | Wie Operate                                                      |
| Messaging-Channels           | Bestehende Verbindungen funktionieren weiter | Neue Verbindungen                                             | Neue Verbindungen                                                |
| Eigene Schlüssel (BYOK)      | Bestehende Schlüssel funktionieren weiter    | Bestehende Schlüssel funktionieren weiter                     | Neue Schlüssel speichern                                         |
| Einladungen für Team members | Bestehende Mitglieder bleiben erhalten       | Bestehende Mitglieder bleiben erhalten                        | Neue Einladungen mit Rollen                                      |

Wir verkaufen keine Kundendomains und verknüpfen auch keine. Binden Sie den Agent in die Website ein, die Sie bereits haben.

## In jedem Tarif enthalten [#in-jedem-tarif-enthalten]

Alle aktuellen Tarife enthalten:

* Ein Embed für die Website, die Sie bereits haben (`embed.js` + `data-agent`).
* Text-Chat, Sprachnachrichten, Standardstimmen, Wissensabruf, strukturierte FAQs/Produkte und Lead-Erfassung.
* Website-Einbettung mit exakter Origin-Steuerung.
* Zugriff auf die öffentliche API mit Schlüsseln mit begrenztem Umfang, OAuth für geprüfte Apps, OpenAPI und tarifabhängigen Ratenlimits.
* Analysen, Konversationen, Nutzungsverfolgung und die Möglichkeit, Credit-Pakete zu kaufen.

Das Kontingent der öffentlichen API beträgt bei Launch 120 Anfragen pro API-Schlüssel und Minute, bei Operate 600 und bei Scale 1.800. Diese Anfragelimits ersetzen weder Ressourcenberechtigungen noch Credit-Prüfungen, Idempotenz oder anbieterspezifische Limits. Siehe [Rate limits](/de/docs/api/rate-limits).

## Credits verstehen [#credits-verstehen]

Credits bezahlen abgerechnete KI-Leistungen wie Generierung, Agent-Antworten, Wissens-Embeddings, Transkription und Sprachsynthese. Sie entsprechen keiner festen Anzahl an Nachrichten: Anbieter, Modell, Länge von Ein- und Ausgabe, Mediendauer und Art des Vorgangs beeinflussen die Kosten.

Die monatlichen Tarif-Credits werden in jedem Abrechnungszeitraum neu bereitgestellt. Nicht genutztes monatliches Guthaben wird für einen weiteren Zyklus übertragen und verfällt danach. Gekaufte Top-up-Credits verfallen nicht, solange ein Abonnement aktiv ist. Ein positives Credit-Guthaben schaltet keine tarifabhängigen Funktionen wie Live-Anrufe, zusätzliche Websites oder das Entfernen des Badges frei.

Eigene Anbieter-Schlüssel (BYOK) verursachen separate Kosten bei OpenRouter (Text) oder Speko (Sprache), den beiden Anbietern, für die sich ein neuer Schlüssel hinzufügen lässt; ältere Schlüssel direkter Anbieter, die bereits hinterlegt sind, funktionieren weiter, bis sie widerrufen werden. Das Speichern eines Schlüssels ist nur bei Scale möglich. Mit Ihrem eigenen Schlüssel kostet jede Aktion eine pauschale Plattformgebühr (1 Credit pro Chat-Antwort) anstelle der tokenbasierten Abrechnung. BYOK wandelt Anbieterrechnungen weder in Credits von Make Agent Fast um noch hebt es die Prüfung von Plattformberechtigungen auf. Siehe [AI provider keys](/de/docs/account/provider-keys).

## Sprachberechtigungen [#sprachberechtigungen]

Sprachnachrichten sind in allen Tarifen enthalten, doch Transkription, Modell und Sprachverarbeitung können Credits verbrauchen. Echtzeit-Live-Sprache nutzt ein separates monatliches Minutenkontingent: keines bei Launch, 30 Minuten bei Operate und 90 Minuten bei Scale.

## Agents und Branding [#agents-und-branding]

Launch unterstützt einen kundenorientierten Agent, Operate bis zu drei. Die Beschreibung „unbegrenzte Agents“ bei Scale unterliegt der fairen Nutzung und ist keine Einladung, missbräuchlich viele oder automatisiert erzeugte Mandanten anzulegen. Ein Agent umfasst sein Wissen, die Embed-Konfiguration, Connectors, Analysen und Konversationsdaten. Jeder Agent erhält einen Agent link, eine öffentliche Chat-Seite unter einer eigenen Subdomain. Übrig gebliebene gehostete Demoseiten werden weiterhin unter Subdomains angezeigt; neue Agents erhalten keine gehostete Marketingseite.

Das Empfehlungs-Badge „Made with Make Agent Fast“ bleibt bei Launch bestehen. Owner mit Operate oder Scale können es von berechtigten veröffentlichten Websites entfernen.

## Credit-Pakete [#credit-pakete]

| Kauf            |         Preis | Was sich ändert                                                        |
| --------------- | ------------: | ---------------------------------------------------------------------- |
| Kleines Paket   |  8 $ einmalig | Fügt 1000 Credits hinzu, die während des Abonnements nicht verfallen   |
| Mittleres Paket | 35 $ einmalig | Fügt 5000 Credits hinzu, die während des Abonnements nicht verfallen   |
| Großes Paket    | 90 $ einmalig | Fügt 15.000 Credits hinzu, die während des Abonnements nicht verfallen |

Top-ups erhöhen nur die Nutzungskapazität. Sie erhöhen weder die Anzahl der Websites noch die API-Anfragelimits, die Live-Minuten oder die Branding-Berechtigungen.

## Testphasen, Verlängerung und Kündigung [#testphasen-verlängerung-und-kündigung]

Die kostenlose Testphase von Launch/Operate wird nicht automatisch in ein kostenpflichtiges Abonnement umgewandelt: An Tag 7 wird der Agent pausiert, bis Sie eine Karte hinterlegen. Sobald eine Karte hinterlegt ist, kann eine Kündigung oder eine fehlgeschlagene Verlängerung den aktiven Zugriff nach dem jeweiligen Zeitraum bzw. Statuswechsel beim Anbieter beenden. Embeds, Connectors, API-Clients und Sprachanrufe können dann stoppen, auch wenn die gespeicherten Workspace-Daten erhalten bleiben.

## Einen Tarif wählen [#einen-tarif-wählen]

* Wählen Sie **Launch** für einen eingebetteten Agent mit Text, Sprachnachrichten und einem einfachen Widget.
* Wählen Sie **Operate**, sobald Ihre Kunden mit dem Agent sprechen: Live-Anrufe, Messaging-Channels, ein individuelles Widget, Sprache in zwei Sprachen oder das Entfernen des Badges.
* Wählen Sie **Scale**, wenn mehrere Agents produktiv laufen: alle Widget-Optionen, Sprache in allen unterstützten Sprachen, Teamrollen und Ihre eigenen API-Schlüssel.

Schätzen Sie anhand realer Abnahmetests und nicht nur anhand der Nachrichtenanzahl. Veröffentlichen Sie einen repräsentativen Agent, messen Sie die Nutzung von Text, Sprache und Wissen, rechnen Sie dann das erwartete Aufkommen hoch und planen Sie Reserven für Wiederholungen, Connectors, Automatisierung und Spitzen beim Launch ein.

## Maßgebliche Quelle für die Abrechnung [#maßgebliche-quelle-für-die-abrechnung]

Der aktuelle Checkout und das Abrechnungs-Dashboard sind die maßgebliche Quelle für einen konkreten Kauf. Steuern, Währungsdarstellung, Zahlungsmethoden, Berechtigung für die Testphase und die Formulierungen des Anbieters können je nach Standort und Kontostatus variieren. Weicht ein Checkout von dieser Seite ab, brechen Sie den Vorgang ab und verwenden Sie die Checkout-Bedingungen oder wenden Sie sich vor der Zahlung an den Support.

---

# Datenschutz und Daten

Source: /de/docs/account/privacy.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Besucherdaten&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Aufbewahrung&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;Kontrollen&#x22;, icon: &#x22;shield&#x22; }]" />

Der Website-Inhaber entscheidet, welches Wissen, welche Eingaben von Besuchern und welche Integrationen für sein Angebot verwendet werden. Make Agent Fast verarbeitet Plattformdaten, um den Service bereitzustellen, vorbehaltlich der geltenden Nutzungsbedingungen und der Datenschutzerklärung.

## Hinweis für Besucher [#hinweis-für-besucher]

Erläutern Sie den Einsatz von KI, Aufzeichnungen, die Erfassung von Leads, Analysen und Nachfassaktionen in einer Sprache, die zum jeweiligen Angebot und zu den lokalen Anforderungen passt. Weisen Sie den Agent nicht an, Daten zu erheben, die Sie nicht benötigen.

## Datenlebenszyklus [#datenlebenszyklus]

Das Entfernen einer Source wirkt sich auf künftige Abrufe aus. Das Löschen von Zugangsdaten beendet den autorisierten Zugriff. Frühere Konversationen, Exporte, Daten externer Channels und Datensätze von Anbietern können jeweils eigenen Aufbewahrungsregeln unterliegen.

## Kontrollen für Owner [#kontrollen-für-owner]

Auf der Seite **Analysen** der Website können erfasste Leads als JSON exportiert und einzelne Leads gelöscht werden. Analyseberichte lassen sich außerdem als Markdown, Excel oder in einer Druck-/PDF-Ansicht exportieren. Ein Export erzeugt eine neue Kopie, die unter Ihrer Kontrolle steht; das Löschen des Datensatzes auf der Plattform entfernt weder einen früheren Download noch eine zugehörige Konversation, einen Datensatz bei einem externen Anbieter oder Daten, die aufgrund gesetzlicher Vorgaben aufbewahrt werden.

Über die **Kontoeinstellungen** können Sie alle Geräte abmelden oder das Konto dauerhaft löschen. Bei der Kontolöschung wird zunächst versucht, das Plattform-Abonnement, übrig gebliebene Polar-Domain-Add-on-Abonnements und Connector-Ressourcen zu beenden. Anschließend werden die Websites, Agents, Wissensinhalte, Konversationen, Leads, API-/OAuth-Zugangsdaten, Sitzungen und lokal gespeicherten Abrechnungsverläufe des Kontos entfernt. Lässt sich nicht bestätigen, dass die externe Abrechnung beendet wurde, schlägt die Löschung sicherheitshalber fehl und das Konto bleibt unverändert, sodass Sie es erneut versuchen oder den Support einschalten können.

## Anfragen [#anfragen]

Nutzen Sie die Self-Service-Kontrollen, wenn sie zur Anfrage passen. Für weitergehende Anfragen auf Auskunft, Berichtigung, Export oder Löschung wenden Sie sich an den Account-Support und folgen Sie dem Verfahren, das in der aktuellen Datenschutzerklärung beschrieben ist. Prüfen Sie die Identität der anfragenden Person, bevor Sie Kontodaten offenlegen, und berücksichtigen Sie in Ihrem Vorgehen auch nachgelagerte Exporte und externe Anbieter.

---

# KI-Anbieterschlüssel

Source: /de/docs/account/provider-keys.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;spark&#x22;, title: &#x22;Textgenerierung&#x22;, description: &#x22;Ein OpenRouter-Schlüssel finanziert die Textgenerierung Ihres Agents über alle verfügbaren Modelle.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;Sprache&#x22;, description: &#x22;Ein Speko-Schlüssel finanziert Transkription und Sprachsynthese.&#x22; },
{ icon: &#x22;shield&#x22;, title: &#x22;Verschlüsselte Speicherung&#x22;, description: &#x22;Vollständige Schlüssel werden verschlüsselt gespeichert und nach dem Speichern nie wieder angezeigt.&#x22; }
]"
/>

Mit Bring your own key (BYOK) können unterstützte KI-Anfragen über Ihr eigenes Konto beim KI-Anbieter laufen. Sie benötigen keinen Schlüssel: Standardmäßig stellt die Plattform die Modelle bereit. Zum Speichern eines Schlüssels ist der Tarif Scale erforderlich. Bereits hinterlegte Schlüssel funktionieren weiterhin in Launch und Operate. Sie zahlen weiterhin den Make Agent Fast-Tarif plus eine pauschale Plattformgebühr pro Aktion; die Modellnutzung stellt Ihnen der Anbieter direkt in Rechnung.

## Unterstützte Anbieter [#unterstützte-anbieter]

Neue Schlüssel können nur für zwei Anbieter hinzugefügt werden – einen für Text und einen für Sprache:

| Anbieter   | Verwendung                                                                  | Schlüssel erstellen oder prüfen                   |
| ---------- | --------------------------------------------------------------------------- | ------------------------------------------------- |
| OpenRouter | Textgenerierung des Agents über die Modelle, an die OpenRouter weiterleitet | [OpenRouter API keys](https://openrouter.ai/keys) |
| Speko      | Speech-to-Text und Text-to-Speech                                           | [Speko platform](https://platform.speko.ai)       |

### Legacy-Schlüssel [#legacy-schlüssel]

Direkte Anbieterschlüssel, die vor der Umstellung auf OpenRouter und Speko gespeichert wurden, erscheinen unter **Legacy-Schlüssel**. Sie funktionieren weiter, bis Sie sie widerrufen, und Sie können sie weiterhin widerrufen, aber keine neuen hinzufügen oder bestehende ersetzen:

| Legacy-Anbieter                                 | Verwendung                                                      | Anbieterreferenz                                                                                                                                                                                                              |
| ----------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Anthropic, OpenAI, Google Gemini, xAI, DeepSeek | Textgenerierung des Agents                                      | [Anthropic API documentation](https://platform.claude.com/docs/en/api/overview), [OpenAI API quickstart](https://developers.openai.com/api/docs/quickstart), [Gemini API keys](https://ai.google.dev/gemini-api/docs/api-key) |
| Deepgram                                        | Speech-to-Text, wenn Deepgram als STT-Anbieter konfiguriert ist | [Deepgram API keys](https://developers.deepgram.com/docs/create-additional-api-keys)                                                                                                                                          |
| ElevenLabs                                      | Text-to-Speech, wenn ElevenLabs konfiguriert ist                | [ElevenLabs authentication](https://elevenlabs.io/docs/api-reference/authentication)                                                                                                                                          |

Die Verfügbarkeit der Anbieter hängt außerdem von den auf der Plattform konfigurierten Text-, Sprach- und Echtzeitanbietern ab. Das Speichern eines gültigen Schlüssels erzwingt nicht, dass jede Funktion diesen Anbieter verwendet.

<Callout title="BYOK ist nicht dasselbe wie ein Make Agent Fast-API-Schlüssel">
  Ein Anbieterschlüssel autorisiert Kosten und Modellaufrufe beim externen KI-Anbieter. Ein Schlüssel der Form `maf_live_...` autorisiert Ihre Software, die öffentliche API von Make Agent Fast aufzurufen. Fügen Sie niemals den einen in das Feld für den anderen ein.
</Callout>

## Anbieterschlüssel hinzufügen [#anbieterschlüssel-hinzufügen]

1. Erstellen Sie in der Konsole von OpenRouter oder Speko einen Schlüssel und aktivieren Sie gegebenenfalls die Abrechnung beim Anbieter oder ein Ausgabenlimit.
2. Öffnen Sie **Dashboard → Einstellungen → KI-Anbieterschlüssel**. Nur der Abrechnungsinhaber eines Scale-Workspace kann einen Schlüssel speichern.
3. Fügen Sie den Schlüssel in die Karte **OpenRouter** oder **Speko** ein.
4. Wählen Sie **Testen & speichern**.
5. Warten Sie auf das Validierungsergebnis und testen Sie anschließend die Funktion, die den Anbieter verwendet.

Make Agent Fast führt vor dem Speichern eines Schlüssels eine Live-Validierungsanfrage durch; dabei werden weder Modell-Token noch Plattform-Credits verbraucht. Der Schlüssel darf keine Leerzeichen oder Zeilenumbrüche enthalten und muss zwischen 16 und 512 Zeichen lang sein. OpenRouter-Schlüssel müssen mit `sk-or-` beginnen; Speko-Schlüssel müssen mit `sk_speko_` oder `sk_live_` beginnen. Maßgeblich ist die Live-Validierung.

Wenn Sie einen weiteren funktionierenden Schlüssel für denselben Anbieter speichern, ersetzt er den zuvor gespeicherten Wert. Ein Schlüssel, der die Validierung nicht besteht, wird nicht gespeichert, sodass der bereits hinterlegte Schlüssel weiter funktioniert. Das Dashboard behält nur unkritische Identifikationsdaten wie die letzten vier Zeichen, den Validierungszeitpunkt und den Status.

## So funktioniert die Auswahl des Textanbieters [#so-funktioniert-die-auswahl-des-textanbieters]

Für die Textgenerierung hat ein aktiver OpenRouter-Schlüssel Vorrang. Ist keiner vorhanden, sucht Make Agent Fast nach einem aktiven Legacy-Schlüssel, der zum auf der Plattform konfigurierten Textanbieter passt, und danach in dieser Reihenfolge nach den anderen Legacy-Textschlüsseln (Anthropic, OpenAI, Gemini, xAI, DeepSeek). Existiert kein geeigneter BYOK-Schlüssel, wird der Plattformanbieter verwendet, sofern Tarif und Bereitstellung dies zulassen.

Sprachschlüssel sind anbieterspezifisch. Ein Speko-Schlüssel wird verwendet, wenn die Sprachverarbeitung über Speko läuft. Ein Legacy-Schlüssel von Deepgram wird nur verwendet, wenn der aktive Speech-to-Text-Anbieter Deepgram ist; ein Legacy-Schlüssel von ElevenLabs wird nur verwendet, wenn Text-to-Speech für ElevenLabs konfiguriert ist.

BYOK-Schlüssel ersetzen derzeit nicht die Zugangsdaten der Plattform für Wissens-Embeddings. Die Aufnahme und der Abruf von Wissen laufen weiterhin über den in der Bereitstellung konfigurierten Embedding-Anbieter.

## Abrechnung und Credits [#abrechnung-und-credits]

* Der externe Anbieter berechnet die KI-Token-Nutzung dem Konto, das den Schlüssel ausgestellt hat.
* Make Agent Fast berechnet weiterhin das Abonnement sowie eine pauschale Plattformgebühr für jede Aktion, die mit Ihrem Schlüssel ausgeführt wird: 1 Credit pro Chat-Antwort anstelle der tokenbasierten Berechnung. Die Gebühr deckt Retrieval, Orchestrierung und Hosting rund um den Aufruf ab und ist kein Prozentsatz Ihrer Token-Rechnung.
* Die Gebühr fällt pro Anbieteraufruf an. Sprachschritte, die die Plattform finanziert (zum Beispiel die Transkription, wenn Sie nur einen Textschlüssel haben), werden zum normalen Tarif berechnet, und Live-Anrufe werden immer zum Plattformtarif abgerechnet.
* Ist das Kontingent beim Anbieter erschöpft, kann eine Anfrage fehlschlagen, selbst wenn noch Make Agent Fast-Credits vorhanden sind.

Prüfen Sie sowohl **Nutzung & Credits** in Make Agent Fast als auch das eigene Nutzungs-Dashboard des Anbieters.

## Schlüsselstatus und Fehlerbehandlung [#schlüsselstatus-und-fehlerbehandlung]

| Status    | Bedeutung                                                     | Was zu tun ist                                                                                                                                         |
| --------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `active`  | Die Live-Validierung war erfolgreich                          | Testen Sie die betreffende Funktion und überwachen Sie die Nutzung beim Anbieter                                                                       |
| `invalid` | Der Anbieter hat den gespeicherten Schlüssel später abgelehnt | Prüfen Sie Abrechnung, Einschränkungen, Kontingent und Widerrufsstatus beim Anbieter; speichern Sie dann einen Ersatzschlüssel (OpenRouter oder Speko) |
| `revoked` | Der Schlüssel ist in Make Agent Fast deaktiviert              | Speichern Sie einen neuen OpenRouter- oder Speko-Schlüssel, wenn die Funktion weiterhin BYOK verwenden soll                                            |

Wenn eine Anfrage fehlschlägt, weil ein Anbieter die Zugangsdaten oder das Kontingent ablehnt, kann Make Agent Fast den gespeicherten Schlüssel als ungültig markieren. Wenn Sie den Schlüssel beim Anbieter korrigieren, wird das gespeicherte Geheimnis dadurch weder offengelegt noch überschrieben; bei einem OpenRouter- oder Speko-Schlüssel prüfen Sie ihn mit **Verbindung testen** erneut oder speichern den funktionierenden Schlüssel noch einmal. Ein Legacy-Schlüssel, der ungültig wird, kann nicht durch einen anderen Legacy-Schlüssel ersetzt werden – stellen Sie diesen Anbieter stattdessen auf OpenRouter oder Speko um.

## Anbieterschlüssel rotieren [#anbieterschlüssel-rotieren]

1. Erstellen Sie einen neuen Anbieterschlüssel, ohne den alten zu löschen.
2. Speichern Sie den neuen Schlüssel in Make Agent Fast und stellen Sie sicher, dass er aktiv wird.
3. Testen Sie den Text-Chat oder Sprachnachrichten – je nachdem, was diesen Anbieter verwendet.
4. Widerrufen Sie den alten Schlüssel in der Konsole des Anbieters.
5. Prüfen Sie die Anbieterprotokolle auf unerwartete Nutzung des alten Schlüssels.

Wurde ein Schlüssel in der Versionsverwaltung oder im Browsercode offengelegt, widerrufen Sie ihn sofort beim Anbieter. Wenn Sie ihn nur in Make Agent Fast löschen, kann ein anderer Besitzer ihn weiterhin direkt beim Anbieter verwenden.

---

# Sicherheit

Source: /de/docs/account/security.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;Zugangsdaten&#x22;, description: &#x22;Schlüssel, OAuth-Secrets und Connector-Tokens verbleiben serverseitig.&#x22; },
{ icon: &#x22;embed&#x22;, title: &#x22;Allowlists für Einbettungen&#x22;, description: &#x22;Legen Sie fest, welche Origins das Widget Ihres Agents laden dürfen.&#x22; },
{ icon: &#x22;link&#x22;, title: &#x22;Webhooks&#x22;, description: &#x22;Prüfen Sie Signaturen, bevor Sie eingehenden Ereignissen vertrauen.&#x22; }
]"
/>

## Kontozugriff [#kontozugriff]

Verwenden Sie ein einzigartiges Passwort, schützen Sie das E-Mail-Konto, das Sie für die Wiederherstellung nutzen, beenden Sie Sitzungen, die Sie nicht kennen, und beschränken Sie den Zugriff auf Produktivwebsites.

Bestätigen Sie die E-Mail-Adresse Ihres Kontos über den Link, der nach der Registrierung versendet wird. Konten mit Passwort können auf der Anmeldeseite **Passwort vergessen** verwenden; nach einem erfolgreichen Zurücksetzen werden alle bestehenden Sitzungen beendet. In den **Kontoeinstellungen** können Sie ein lokales Passwort ändern, Google ausdrücklich verknüpfen (sofern aktiviert) und sich auf allen Geräten abmelden. OAuth-Konten ohne lokales Passwort haben kein Passwort, das geändert werden könnte, und bei einer normalen Anmeldung wird nie stillschweigend eine neue Identität verknüpft.

## Secrets [#secrets]

API-Schlüssel, Connector-Tokens, App-Secrets, Webhook-Secrets und Schlüssel von Sprachanbietern sind Zugangsdaten. Bewahren Sie sie in einem freigegebenen Secret-Manager auf, speichern Sie sie niemals im Client-Code und rotieren Sie sie nach einer Offenlegung.

## Minimale Berechtigungen [#minimale-berechtigungen]

Wählen Sie eng gefasste API-Scopes, dedizierte Apps auf externen Plattformen, präzise Origins für Einbettungen und getrennte Schlüssel für getrennte Systeme. Entfernen Sie nicht genutzte Zugangsdaten und Integrationen.

## Inhalte und Datenschutz [#inhalte-und-datenschutz]

Laden Sie nur Daten hoch, die der Agent verwenden darf. Testen Sie Ablehnungen und Eskalationspfade und wenden Sie Aufbewahrungsregeln auf Exporte von Gesprächen und Leads an.

## Meldung von Schwachstellen [#meldung-von-schwachstellen]

Wenn Sie eine vermutete Sicherheitslücke melden, geben Sie die betroffene URL oder Komponente, die Auswirkungen und die Schritte zur Reproduktion an, ohne auf Daten anderer Nutzer zuzugreifen.

---

# Fehlerbehebung

Source: /de/docs/account/troubleshooting.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Veröffentlichen&#x22;, icon: &#x22;globe&#x22; }, { label: &#x22;Einbetten&#x22;, icon: &#x22;embed&#x22; }, { label: &#x22;Connectors&#x22;, icon: &#x22;connectors&#x22; }]" />

## Mit einem reproduzierbaren Fall beginnen [#mit-einem-reproduzierbaren-fall-beginnen]

Halten Sie vor jeder Änderung an den Einstellungen Folgendes fest:

* Den Workspace bzw. die Website, die öffentliche Route oder den API-Endpunkt sowie die genaue Uhrzeit mit Zeitzone.
* Erwartetes und tatsächliches Ergebnis.
* Browser/Gerät oder externer Provider-Channel.
* Ob der Fehler die Vorschau des Owners, die übrig gebliebene gehostete Demoseite, die Einbettung, einen Connector und/oder die API betrifft.
* Unbedenklichen Status-/Fehlertext, die `x-request-id` der Antwort, den letzten Fehler des Connectors oder die Zustellungsereignis-ID des Providers.
* Den Zeitpunkt, zu dem zuletzt alles funktionierte, und die kleinste letzte Änderung.

Geben Sie keine API-/Provider-/Connector-Zugangsdaten im Klartext, keine Webhook-Secrets, keine privaten Kundendaten, keine vollständigen Authorization-Header und keine unnötigen Gesprächsinhalte an.

## Änderungen an der Website erscheinen nicht [#änderungen-an-der-website-erscheinen-nicht]

1. Prüfen Sie, ob die Dashboard-URL zur vorgesehenen Website und zum richtigen Workspace gehört.
2. Prüfen Sie, ob die Speicheraktion Erfolg gemeldet hat.
3. Anweisungen und indexiertes Wissen gelten ohne erneute Veröffentlichung für neue Gespräche. Wenn das Widget selbst ausgeblendet ist, aktivieren Sie es wieder über das Menü **Put it live** auf der Agent-Seite → **Website widget** (oder über die Karte **On your website** auf dem Tab **Overview**).
4. Änderungen an den **Display**-Einstellungen (und am Branding-Badge) werden automatisch gespeichert und aktualisieren die Live-Einbettung bereits – überspringen Sie die erneute Veröffentlichung und öffnen Sie ein privates Fenster.
5. Öffnen Sie eine echte Einbettung (oder einen übrig gebliebenen gehosteten Slug, falls Sie noch einen haben) in einem privaten Fenster.
6. Wenn nur eine Social-Vorschau veraltet ist, verwenden Sie den Cache bzw. Debugger der jeweiligen Plattform.

Die Veröffentlichung zurückzuziehen und Bearbeiten sind zwei verschiedene Dinge. Ein verbundener Messaging-Connector kann weiterhin antworten, auch wenn die Einbettung deaktiviert ist.

## Die Antwort des Agents ist schwach oder falsch [#die-antwort-des-agents-ist-schwach-oder-falsch]

Stellen Sie dieselbe Frage im Tester für Owner und in einem neuen öffentlichen Gespräch. Prüfen Sie, ob die relevante Wissensquelle indexiert wurde, eine eindeutige Antwort enthält, aktuell ist und keiner anderen Quelle widerspricht. Prüfen Sie die Sprach- und Persona-Regeln auf eine Grenze, die die Antwort verhindert.

Wenn die Quelle keine Antwort enthält, verbessern Sie das Fallback-/Eskalationsverhalten, statt den Agent anzuweisen zu raten. Nutzen Sie [Wissensquellen](/de/docs/build/knowledge), um ein Abnahme-Set aus direkten Fragen, Umformulierungen und Grenzfällen zu erstellen.

## Der Launcher der Einbettung fehlt oder wird blockiert [#der-launcher-der-einbettung-fehlt-oder-wird-blockiert]

Prüfen Sie, ob die Website veröffentlicht und die Einbettung aktiviert ist, ob das Skript den exakten Site-Slug enthält und ob der endgültige übergeordnete Origin des Browsers – einschließlich Schema, Hostname und Port – in der Allowlist steht. Untersuchen Sie in den DevTools die Anfrage an `embed.js`, CSP-Fehler, den Status des Consent-Managers, die iframe-Anfrage und das Vorhandensein genau eines `data-maf-embed`-Roots.

Wenn Text funktioniert, das Mikrofon aber nicht, prüfen Sie HTTPS, die Browserberechtigung, die allow-Berechtigung des iframes und die Permissions Policy des Hosts. Folgen Sie der vollständigen [Übersicht zur Einbettung](/de/docs/embed/overview) und [Sicherheit und CSP](/de/docs/embed/security).

## Sprache funktioniert nicht [#sprache-funktioniert-nicht]

Grenzen Sie den fehlerhaften Modus ein: Sprachnachricht, Live-Anruf oder Connector-Sprache. Ein funktionierender Textpfad belegt nur, dass der Schlüssel für das Sprachmodell in Ordnung ist.

Prüfen Sie die Schlüssel für Transkription, TTS und Echtzeit-Provider unabhängig voneinander; prüfen Sie anschließend den Anspruch laut Tarif, das Credit-Guthaben, das Kontingent an Live-Minuten, die Browserberechtigung und die konfigurierten Sprachen. Testen Sie eine kurze, saubere Aufnahme, bevor Sie eine lange oder verrauschte Datei untersuchen.

## Der Connector empfängt keine Nachrichten [#der-connector-empfängt-keine-nachrichten]

Nutzen Sie die Kanalanleitung und vergleichen Sie beide Seiten. Prüfen Sie, ob der Connector aktiviert ist, die Zugangsdaten weiterhin validiert werden, die Webhook-/Interaktions-/Skill-URL beim Provider die aktuelle ist, das erforderliche Ereignis bzw. die erforderliche Page, Nummer oder der erforderliche Block abonniert ist, der App-Modus den Testnutzer einschließt und die Zustellung über öffentliches HTTPS gelingt.

Eine erfolgreiche Webhook-Verifizierung belegt weder das Abonnement der Laufzeitereignisse noch die Berechtigungen für ausgehende Nachrichten. Vergleichen Sie die Zustellungsprotokolle des Providers mit **Last message** und dem gespeicherten Fehler des Connectors. Testen Sie zuerst Text, dann Sprache.

## Eigene Domains werden nicht angeboten [#eigene-domains-werden-nicht-angeboten]

Wir verkaufen keine Kundendomains und verbinden sie auch nicht. Platzieren Sie den Agent per [Einbettung](/de/docs/embed/overview) auf der Website, die Sie bereits haben. Übrig gebliebene Ereignisse des Polar-Domain-Add-ons werden ignoriert oder storniert und erzeugen niemals Credits.

## API-Anfrage schlägt fehl [#api-anfrage-schlägt-fehl]

Notieren Sie Methode, versionierten Pfad, Status, stabilen Fehlercode, die `x-request-id` der Antwort und relevante Rate-Limit-Header. Ordnen Sie den Fehler dann ein:

| Status | Wahrscheinlichste Maßnahme                                                                                              |
| ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | JSON-/Formularstruktur oder Validierungsdetails korrigieren; nicht unverändert wiederholen                              |
| `401`  | Gültige, nicht abgelaufene und nicht widerrufene MAF-Zugangsdaten verwenden; niemals einen Provider-Schlüssel verwenden |
| `403`  | Erforderlichen Scope hinzufügen oder Zugriff auf Tarif/Ressource wiederherstellen                                       |
| `404`  | Prüfen, ob die ID zum authentifizierten Workspace gehört und der Pfad korrekt ist                                       |
| `409`  | Zustandskonflikt beheben oder denselben Idempotency-Key mit derselben Payload erneut senden                             |
| `415`  | Den dokumentierten Content-Type senden                                                                                  |
| `429`  | `retry-after`-/Reset-Header mit Jitter beachten; keine Busy-Loop verwenden                                              |
| `500`  | Sichere/idempotente Anfrage wiederholen und Request-ID sowie Zeitpunkt aufbewahren                                      |

Nutzen Sie [Zugangsdaten und Token](/de/docs/api/credentials), [Scopes und Fehler](/de/docs/api/scopes-errors) und [Rate Limits](/de/docs/api/rate-limits). Beheben Sie einen API-Fehler niemals, indem Sie Server-Zugangsdaten in Browsercode verlagern.

## Abrechnung oder Nutzung wirkt falsch [#abrechnung-oder-nutzung-wirkt-falsch]

Unterscheiden Sie zwischen Plattformzugang, monatlichen Credits, gekauften Credits, Anzahl der Websites, Live-Minuten, API-Rate, Messaging-Channels (Operate+) und BYOK/Team (Scale). Eine Aufladung ändert nur die Credits. Die Gebühren des BYOK-Providers sind von der Abrechnung von Make Agent Fast getrennt.

Bei unerwarteter Nutzung sollten Sie vor der Untersuchung die wahrscheinliche Quelle eindämmen: einen Connector deaktivieren, einen Schlüssel widerrufen, einen unbeabsichtigten Einbettungs-Origin entfernen oder eine API-Wiederholungsschleife stoppen. Bewahren Sie Zeitraum sowie Request-/Provider-IDs auf, ohne Secrets preiszugeben.

## Sichere Support-Details sammeln [#sichere-support-details-sammeln]

Wenn Sie weiterhin blockiert sind, nutzen Sie das Feedback-Element in der passendsten Anleitung oder kontaktieren Sie den Support über das Dashboard und geben Sie Folgendes an:

* Kennung von Website/Workspace und betroffene Funktion.
* Exakten Zeitstempel/Zeitzone und reproduzierbare Schritte.
* Erwartetes und tatsächliches Ergebnis.
* Öffentliche URL ohne Secrets, sofern relevant.
* HTTP-Status, stabilen Fehlercode, `x-request-id` oder Provider-Ereignis-ID.
* Geschwärzten Screenshot oder minimale Payload ohne Secrets und personenbezogene Daten.

Geben Sie an, was Sie bereits geprüft haben. So vermeiden Sie wiederholte Einrichtungstipps und machen die Fehlergrenze klar.

---

# Authentifizierung

Source: /de/docs/api/authentication.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;API-Schlüssel&#x22;, description: &#x22;Bearer-Zugangsdaten mit eingeschränkten Scopes für ein Konto und einen Server unter Ihrer Kontrolle.&#x22; },
{ icon: &#x22;account&#x22;, title: &#x22;OAuth&#x22;, description: &#x22;Geprüfte Autorisierung für Anwendungen, die mehrere Kundenkonten verbinden.&#x22; },
{ icon: &#x22;layers&#x22;, title: &#x22;Minimale Berechtigungen&#x22;, description: &#x22;Jede Operation benennt den genauen Lese- oder Schreib-Scope, den sie benötigt.&#x22; }
]"
/>

Verwenden Sie einen API-Schlüssel für Ihr eigenes Backend oder für Automatisierungen. Verwenden Sie OAuth, wenn Ihre Anwendung andere Make Agent Fast-Nutzer um Zugriff bittet. Beide Arten von Zugangsdaten rufen dieselben `/api/v1`-Ressourcen auf und unterliegen denselben Scopes, Tarifberechtigungen, Mandantentrennungen und Ratenbegrenzungen.

## API-Schlüssel [#api-schlüssel]

Zum Erstellen und Verwenden eines öffentlichen API-Schlüssels ist ein aktiver kostenpflichtiger Tarif erforderlich.

1. Öffnen Sie **Dashboard → Einstellungen → Entwickler**.
2. Geben Sie einen Namen ein, der den Dienst und die Umgebung identifiziert, zum Beispiel `Production lead export`.
3. Wählen Sie die minimalen Scopes aus, die der Dienst benötigt.
4. Wählen Sie eine Gültigkeitsdauer: 30 Tage, 90 Tage, ein Jahr oder unbegrenzt.
5. Erstellen Sie den Schlüssel und kopieren Sie den Wert `maf_live_...` sofort.

Make Agent Fast speichert einen SHA-256-Hash statt eines wiederherstellbaren Klartexts. Das Dashboard zeigt später ein sicheres Präfix, die Scopes, das Ablaufdatum, den Zeitpunkt der letzten Verwendung und den Sperrstatus an.

```http
Authorization: Bearer maf_live_...
```

Senden Sie den Header aus Servercode:

```bash
curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

Fehlende Zugangsdaten liefern `401 authentication_required`. Ungültige, abgelaufene oder widerrufene Schlüssel liefern `401 invalid_api_key`. Ein Schlüssel, dessen Konto keinen aktiven kostenpflichtigen Tarif mehr hat, liefert `403 subscription_required`.

### Schlüssel rotieren oder widerrufen [#schlüssel-rotieren-oder-widerrufen]

Erstellen Sie einen Ersatz, bevor Sie den alten Schlüssel widerrufen. Stellen Sie den Ersatzschlüssel bereit, senden Sie eine echte Anfrage, prüfen Sie deren `x-request-id` und klicken Sie dann beim alten Schlüssel auf **Widerrufen**. Der Widerruf wirkt sofort und kann nicht rückgängig gemacht werden.

In den **Entwickler**-Einstellungen können Sie mit **Bearbeiten** den Namen und die Scopes eines aktiven Schlüssels ändern; die Änderung gilt sofort für denselben Schlüssel. Das Ablaufdatum und das Token lassen sich nicht ändern – erstellen Sie für ein neues Ablaufdatum oder ein rotiertes Token einen Ersatzschlüssel.

## OAuth-Anwendungen [#oauth-anwendungen]

OAuth ist für Software gedacht, die Konten verbindet, die anderen Make Agent Fast-Nutzern gehören. Es verwendet den Autorisierungscode-Flow mit PKCE (`S256`) und gibt kein Client Secret aus und benötigt auch keines. Die Client-ID ist öffentlich; Autorisierungscodes, Access Tokens, Refresh Tokens und der PKCE-Verifier sind vertraulich.

### 1. Anwendung registrieren [#1-anwendung-registrieren]

Öffnen Sie **Dashboard → Einstellungen → Entwickler → OAuth-Anwendungen**. Fügen Sie Folgendes hinzu:

* Einen Anwendungsnamen mit 2 bis 100 Zeichen.
* Zwischen 1 und 10 exakte Redirect-URLs.
* Die maximalen Scopes, die Ihre Anwendung anfordern darf.

Redirect-URLs in der Produktion müssen HTTPS verwenden und dürfen weder Zugangsdaten noch Fragmente enthalten. Der vollständige URI muss bei der Autorisierung und beim Token-Austausch mit einem registrierten Wert übereinstimmen. Neu eingereichte Anwendungen haben den Status `pending`; die Autorisierung funktioniert erst, nachdem die Anwendung geprüft und als `approved` markiert wurde.

Der Plattformbetreiber prüft ausstehende Client-IDs mit dem protokollierten
`oauth:review`-Workflow. Bewahren Sie die nach dem Einreichen angezeigte Client-ID auf; ihr Status ist
auf der Seite „Entwickler“ sichtbar, und bei abgelehnten Anwendungen wird die Entscheidung der Prüfung
angezeigt, bevor sie erneut eingereicht werden können.

### 2. PKCE-Werte generieren [#2-pkce-werte-generieren]

Generieren Sie für jeden Autorisierungsversuch einen neuen Verifier und bewahren Sie ihn zusammen mit `state` in derselben geschützten, kurzlebigen Sitzung auf.

```ts
import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");
```

Der Verifier muss 43–128 URL-sichere PKCE-Zeichen enthalten. Es wird ausschließlich `code_challenge_method=S256` akzeptiert.

### 3. Nutzer zur Zustimmung weiterleiten [#3-nutzer-zur-zustimmung-weiterleiten]

```text
https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256
```

Der Nutzer meldet sich an, prüft die angeforderten Scopes und erlaubt oder verweigert den Zugriff. Bei Erfolg leitet Make Agent Fast mit `code` und dem ursprünglichen `state` auf den exakten registrierten URI weiter. Bei Ablehnung wird `error=access_denied` gesendet, zusammen mit dem ursprünglichen `state`, sofern einer übergeben wurde.

Lehnen Sie den Callback ab, wenn `state` nicht exakt mit dem für diese Browsersitzung gespeicherten Wert übereinstimmt.

### 4. Autorisierungscode austauschen [#4-autorisierungscode-austauschen]

Der Autorisierungscode läuft nach 10 Minuten ab und kann nur einmal verwendet werden.

```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"
```

```json
{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}
```

Das Access Token ist eine Stunde gültig. Das Refresh Token ist bis zu 90 Tage gültig, sofern es nicht vorher rotiert oder widerrufen wird.

### 5. Refresh Token rotieren [#5-refresh-token-rotieren]

Jede erfolgreiche Aktualisierung widerruft sowohl das übermittelte Refresh Token als auch das zugehörige vorherige Access Token und gibt ein neues Paar zurück. Speichern Sie das neue Paar atomar, bevor Sie den Zustand der vorherigen Antwort verwerfen.

```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"
```

Die erneute Verwendung eines Autorisierungscodes oder eines rotierten Refresh Tokens liefert `invalid_grant`. Der OAuth-Token-Endpunkt gibt Antworten im OAuth-Stil `{ "error", "error_description" }` zurück statt des öffentlichen API-Fehlerformats und erlaubt 30 Token-Anfragen pro Aufrufer-IP-Adresse und Minute.

## Verwenden Sie niemals Management-Anfragen im Browsercode zur Authentifizierung [#verwenden-sie-niemals-management-anfragen-im-browsercode-zur-authentifizierung]

Legen Sie keinen geheimen API-Schlüssel, kein Access Token und kein Refresh Token in React-Client-Komponenten, statischem JavaScript, mobilem Web, Webflow, Framer, Wix oder Shopify Liquid ab. Verwenden Sie Ihr authentifiziertes Backend. Die öffentliche Website-Einbettung verwendet einen nicht geheimen Site-Slug und eine Origin-Allowlist, keine Zugangsdaten der Management-API.

Siehe [Zugangsdaten und Tokens](/de/docs/api/credentials), [Scopes und Fehler](/de/docs/api/scopes-errors) und [API-Schnellstart](/de/docs/api/quickstart).

---

# Zugangsdaten und Tokens

Source: /de/docs/api/credentials.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;Server-Zugangsdaten&#x22;, description: &#x22;API-Schlüssel und OAuth-Tokens autorisieren den Zugriff auf die öffentliche API.&#x22; },
{ icon: &#x22;connectors&#x22;, title: &#x22;Channel-Zugangsdaten&#x22;, description: &#x22;Bot-Tokens und App-Secrets verbinden externe Messaging-Anbieter.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;Anbieterschlüssel&#x22;, description: &#x22;BYOK-Zugangsdaten bezahlen KI-Anbieter über Ihr eigenes Anbieterkonto.&#x22; }
]"
/>

Make Agent Fast verwendet mehrere Arten von Zugangsdaten. Sie sind nicht austauschbar. Bevor Sie einen Wert kopieren, klären Sie, welches System ihn ausgestellt hat, welches System ihn erhält und ob er unbedenklich in einem Browser sichtbar sein darf.

## Übersicht der Zugangsdaten [#übersicht-der-zugangsdaten]

| Zugangsdaten                                       | Erstellt in                                           | Verwendet von                         | Geheim? | Typisches Format oder typischer Wert           |
| -------------------------------------------------- | ----------------------------------------------------- | ------------------------------------- | ------- | ---------------------------------------------- |
| Slug der veröffentlichten Website                  | Website-Dashboard                                     | Embed-Loader der Website              | Nein    | `my-agent`                                     |
| Make Agent Fast API-Schlüssel                      | **Einstellungen → Entwickler**                        | Ihr Backend oder Ihre Automatisierung | Ja      | `maf_live_...`                                 |
| OAuth-Client-ID                                    | **Einstellungen → Entwickler**                        | Anwendung mit mehreren Konten         | Nein    | `maf_app_...`                                  |
| OAuth-Zugriffstoken                                | OAuth-Token-Endpunkt                                  | Das Backend Ihrer Anwendung           | Ja      | Bearer-Token, Gültigkeit eine Stunde           |
| OAuth-Refresh-Token                                | OAuth-Token-Endpunkt                                  | Ihr sicherer Token-Speicher           | Ja      | `maf_refresh_...`, wird bei Verwendung rotiert |
| API-Schlüssel eines KI-Anbieters (optional, Scale) | OpenRouter (Text) oder Speko (Sprache)                | Make Agent Fast Backend               | Ja      | `sk-or-...` oder `sk_speko_...`                |
| Connector-Token oder App-Secret                    | Telegram, Meta, Discord oder Kakao                    | Make Agent Fast Connector-Dienst      | Ja      | Anbieterspezifisch                             |
| Webhook-Signaturgeheimnis                          | Erstellung des Webhook-Endpunkts der öffentlichen API | Ihr Webhook-Empfänger                 | Ja      | `whsec_...`                                    |

<Callout title="Das Website-Embed verwendet keinen API-Schlüssel">
  Der Embed-Loader benötigt einen öffentlichen Website-Slug und eine zugelassene Website-Origin. Fügen Sie dem Script-Tag niemals einen Make Agent Fast API-Schlüssel, Anbieterschlüssel, Connector-Token oder ein Webhook-Geheimnis hinzu.
</Callout>

## Die richtige Autorisierungsmethode wählen [#die-richtige-autorisierungsmethode-wählen]

Verwenden Sie einen **Make Agent Fast API-Schlüssel** für einen Server, den Sie kontrollieren, und ein einzelnes Make Agent Fast Konto. Wählen Sie nur die Scopes, die dieser Server benötigt.

Verwenden Sie **OAuth Authorization Code mit PKCE**, wenn Ihr Produkt Konten anderer Make Agent Fast Nutzer verbindet. OAuth-Anwendungen müssen geprüft werden, bevor die Autorisierung in der Produktion erfolgreich ist.

Verwenden Sie einen **KI-Anbieterschlüssel** nur dann, wenn Make Agent Fast diesen KI-Anbieter über Ihr Anbieterkonto aufrufen soll. Ein Anbieterschlüssel autorisiert nicht die öffentliche Make Agent Fast API.

Verwenden Sie **Connector-Zugangsdaten** nur im passenden Connector-Formular oder in der passenden Connector-API-Anfrage. Ein Telegram-Bot-Token kann weder Discord noch Meta noch Make Agent Fast API-Anfragen autorisieren.

## Geheimnisse sicher speichern [#geheimnisse-sicher-speichern]

Legen Sie Geheimnisse für die lokale Entwicklung in einer ignorierten Umgebungsdatei oder in Ihrer Shell-Umgebung ab:

```bash
export MAF_API_KEY="maf_live_..."
```

Verwenden Sie für das Deployment den verschlüsselten Secret-Manager Ihres Hosting-Anbieters. Legen Sie Geheimnisse nicht ab in:

* Git-Commits, Issue-Beschreibungen, Screenshots, Analytics-Eigenschaften oder Support-Nachrichten.
* `NEXT_PUBLIC_*`, `VITE_*` oder anderen Variablen, die in Browser-JavaScript eingebunden werden.
* Webflow, Framer, Wix, Shopify Liquid, WordPress HTML oder einem Mobile-Web-Bundle.
* Query-Strings. URLs werden häufig im Browserverlauf, in Proxys und in Logs aufbewahrt.

Führen Sie API-Aufrufe über Ihr authentifiziertes Backend aus. Der Browser sollte Ihr Backend aufrufen, und Ihr Backend sollte das Geheimnis anfügen.

```ts
const response = await fetch("https://makeagent.fast/api/v1/sites", {
  headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
});
```

## Regeln für einmalig angezeigte Geheimnisse [#regeln-für-einmalig-angezeigte-geheimnisse]

API-Schlüssel, Webhook-Signaturgeheimnisse und neu ausgestellte OAuth-Refresh-Tokens müssen kopiert werden, wenn sie angezeigt werden. Der vollständige Klartextwert kann später nicht wiederhergestellt werden. Wenn er verloren geht, erstellen Sie einen Ersatz, anstatt den Support zu bitten, ihn offenzulegen.

Zugangsdaten für KI-Anbieter und Connectors werden vor der Speicherung verschlüsselt und nicht über List-APIs zurückgegeben. Das Dashboard zeigt möglicherweise eine Bezeichnung, ein Präfix, die letzten vier Zeichen, den Validierungsstatus oder den Zeitpunkt der letzten Verwendung an, damit Sie Zugangsdaten identifizieren können, ohne sie preiszugeben.

## Checkliste für die Rotation [#checkliste-für-die-rotation]

1. Erstellen Sie den Ersatz mit denselben minimalen Scopes oder Anbieterberechtigungen.
2. Aktualisieren Sie jeweils ein Deployment oder einen Empfänger nach dem anderen.
3. Prüfen Sie, dass eine echte Anfrage erfolgreich ist, und notieren Sie deren `x-request-id`.
4. Widerrufen Sie die alten Zugangsdaten.
5. Bestätigen Sie, dass alte Anfragen mit `401 invalid_api_key` oder dem entsprechenden Fehler des Anbieters fehlschlagen.

Speichern Sie bei OAuth das neue Refresh-Token, das jede Refresh-Antwort zurückgibt, bevor Sie das vorherige Token verwerfen. Betreiben Sie bei der Rotation von Webhook-Geheimnissen alte und neue Endpunkte parallel, bis alle Sender und Empfänger das neue Geheimnis verwenden.

## Wenn ein Geheimnis offengelegt wurde [#wenn-ein-geheimnis-offengelegt-wurde]

Widerrufen oder rotieren Sie es sofort. Es genügt nicht, es aus dem letzten Git-Commit zu entfernen, da es in der Historie, in Caches, Logs oder Forks verbleiben kann. Prüfen Sie die Aktivitäten sowohl bei Make Agent Fast als auch beim ausstellenden Anbieter und ersetzen Sie anschließend alle Zugangsdaten, die am selben Speicherort oder in derselben Deployment-Umgebung abgelegt waren.

Lesen Sie weiter bei [Authentifizierung](/de/docs/api/authentication), [Scopes und Fehler](/de/docs/api/scopes-errors) oder [KI-Anbieterschlüssel](/de/docs/account/provider-keys).

---

# API-Übersicht

Source: /de/docs/api/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/api/authentication&#x22;, label: &#x22;Authentifizierung&#x22;, icon: &#x22;shield&#x22; },
{ href: &#x22;/de/docs/api/quickstart&#x22;, label: &#x22;Schnellstart&#x22;, icon: &#x22;bolt&#x22; },
{ href: &#x22;/de/docs/api/reference&#x22;, label: &#x22;Referenz&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/api/webhooks&#x22;, label: &#x22;Webhooks&#x22;, icon: &#x22;link&#x22; },
{ href: &#x22;/de/docs/api/sdks&#x22;, label: &#x22;SDKs&#x22;, icon: &#x22;code&#x22; }
]"
/>

Die öffentliche API nutzt ressourcenorientiertes JSON über HTTPS unter `/api/v1`. Sie ist in den kostenpflichtigen Tarifen verfügbar und verwendet dieselben Berechtigungen für Websites, Credits und Funktionen wie das Dashboard.

## Was Sie automatisieren können [#was-sie-automatisieren-können]

* Websites und Veröffentlichungsstatus
* Agent-Konfiguration, FAQs, Produkte und Wissen
* Konversationen (einschließlich Antworten des Owners, Pausieren und Fortsetzen), Leads, Analysen, Benachrichtigungen und Broadcasts
* Lead-Erstellung und Einwilligung, Opportunity-Pipelines, CRM-Ergebnisse und Wiederherstellung der Synchronisierung
* Connectors, Monetarisierung, Tickets, Team, Nutzung und Kontoinformationen
* Signierte Webhook-Abonnements für unterstützte Ereignisse

Sensible Aktionen nutzen explizite Aktions-Endpunkte statt uneingeschränkter Datenbankänderungen. Connector-Secrets werden beim Schreiben akzeptiert, aber nie zurückgegeben.

Dies ist eine **Verwaltungs- und Synchronisierungs-API**. Sie kann Leads erstellen und aktualisieren,
sie in eine Opportunity-Pipeline aufnehmen, quellenbezogene gewonnene bzw. verlorene CRM-Ergebnisse
importieren, fehlgeschlagene Ergebnis-Importe erneut versuchen und im Namen des Unternehmens auf einen Besucher antworten,
wobei der Agent in dieser Konversation pausiert und fortgesetzt werden kann. Das Senden von Nachrichten als Besucher
bleibt eine Widget-Funktion; Analysen und Nutzung sind weiterhin schreibgeschützt. Benutzerdefinierte Domains wurden
entfernt, und die `/domains`-Routen geben `409` zurück.

## Sicher starten [#sicher-starten]

Erstellen Sie im Dashboard einen Schlüssel mit eingeschränktem Geltungsbereich, rufen Sie den Endpunkt für das aktuelle Konto auf und entwickeln Sie zunächst gegen eine Testsite, bevor Sie Produktionsinhalte anfassen.

```bash
curl https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer maf_live_YOUR_KEY"
```

Weitere Informationen finden Sie unter [Authentifizierung](/de/docs/api/authentication), [API-Schnellstart](/de/docs/api/quickstart) und in der [API-Referenz](/de/docs/api/reference).

---

# API-Schnellstart

Source: /de/docs/api/quickstart.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;10 Minuten&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Nur Server&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;REST&#x22;, icon: &#x22;code&#x22; }]" />

Dieser Schnellstart prüft, ob sich ein Backend authentifizieren und Ihr Konto lesen kann. Sie benötigen einen aktiven kostenpflichtigen Tarif, ein Terminal mit `curl` und Zugriff auf **Dashboard → Einstellungen → Entwickler**.

Die aktuelle v1-API verwaltet und synchronisiert Ressourcen. Sie ist kein Transportweg für benutzerdefinierte Chats: Sie können keine Nachrichten als Besucher senden. Leads können erstellt, aktualisiert und akzeptiert werden (`leads:write`), und ein Owner kann auf eine Konversation antworten sowie sie pausieren oder fortsetzen (`conversations:write`).

## 1. Einen Schlüssel mit minimalen Berechtigungen erstellen [#1-einen-schlüssel-mit-minimalen-berechtigungen-erstellen]

Erstellen Sie einen Schlüssel mit dem Namen `Local API quickstart`, wählen Sie `account:read` und `sites:read` aus und legen Sie ein kurzes Ablaufdatum fest. Kopieren Sie den Klartextschlüssel sofort; er wird nicht noch einmal angezeigt.

Verwenden Sie keinen Schlüssel eines KI-Anbieters, etwa von OpenRouter oder Speko. Die öffentliche API erfordert einen Make-Agent-Fast-Schlüssel, der mit `maf_live_` beginnt.

## 2. Für dieses Terminal speichern [#2-für-dieses-terminal-speichern]

```bash
export MAF_API_KEY="maf_live_..."
```

Prüfen Sie, ob die Variable existiert, ohne das Geheimnis auszugeben:

```bash
test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"
```

Committen Sie den Schlüssel nicht in `.env`, in Beispiele mit Shell-Verlauf, Test-Fixtures oder ein Browser-Bundle. Verwenden Sie für bereitgestellten Code den Secret Manager Ihres Hosts.

## 3. Das Konto abfragen [#3-das-konto-abfragen]

```bash
curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

Erwarteter Status: `200 OK`. Der Body enthält `data.id`, Informationen zu Tarif und Berechtigungen sowie eine Wallet-Zusammenfassung. Die Antwort enthält außerdem `x-request-id`; bewahren Sie diesen Wert auf, wenn Sie eine fehlgeschlagene Anfrage melden.

```json
{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}
```

Felder können hinzukommen, ohne dass sich der Pfad `/v1` ändert. Ignorieren Sie unbekannte Felder, anstatt die Antwort abzulehnen.

## 4. Websites auflisten [#4-websites-auflisten]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

Antworten für Sammlungen verwenden dieses Format:

```json
{
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

Wenn `has_more` den Wert true hat, senden Sie den exakten Wert von `next_cursor` als Query-Parameter `cursor` der nächsten Anfrage. Dekodieren oder konstruieren Sie Cursor nicht selbst.

## 5. Einen strukturierten Fehler behandeln [#5-einen-strukturierten-fehler-behandeln]

Entfernen Sie vorübergehend den Authorization-Header und wiederholen Sie `/me`. Die Antwort sollte `401` mit einem stabilen Code lauten:

```json
{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}
```

Produktionscode sollte anhand von `error.code` verzweigen und nicht `message` vergleichen. Protokollieren Sie die Operation, den HTTP-Status und die Request-ID, jedoch nicht den Schlüssel.

## 6. Den ersten Schreibzugriff sicher durchführen [#6-den-ersten-schreibzugriff-sicher-durchführen]

Erstellen Sie einen separaten Schlüssel, der zusätzlich `sites:write`, `agents:write` und `knowledge:write` enthält; erweitern Sie nicht den Lese-Schlüssel des Schnellstarts. Folgen Sie den [API-Rezepten](/de/docs/api/recipes), um eine Website zu erstellen, fundiertes Wissen hinzuzufügen und sie mit expliziten Idempotenzschlüsseln zu veröffentlichen.

## Häufige Fehler bei der ersten Anfrage [#häufige-fehler-bei-der-ersten-anfrage]

| Ergebnis                      | Ursache                                                                                  | Lösung                                                                       |
| ----------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `401 authentication_required` | Header fehlt oder hat nicht das Format `Bearer TOKEN`                                    | Fügen Sie den exakten Authorization-Header aus dem Servercode hinzu          |
| `401 invalid_api_key`         | Tippfehler, abgelaufener Schlüssel, widerrufener Schlüssel oder falscher Zugangsdatentyp | Erstellen und kopieren Sie einen neuen Make-Agent-Fast-API-Schlüssel         |
| `403 subscription_required`   | Kein aktiver kostenpflichtiger Tarif                                                     | Stellen Sie das Abonnement des Kontos wieder her                             |
| `403 insufficient_scope`      | Der Schlüssel enthält nicht den Scope der Operation                                      | Erstellen Sie einen Ersatzschlüssel mit dem minimal fehlenden Scope          |
| `403 account_paused`          | Der API-Zugriff wurde für dieses Konto pausiert                                          | Setzen Sie den API-Zugriff fort oder wenden Sie sich an den Kontoinhaber     |
| `429 rate_limit_exceeded`     | Das Einminuten-Kontingent des Schlüssels ist ausgeschöpft                                | Warten Sie die Zeit aus `Retry-After` ab und reduzieren Sie die Parallelität |

Fahren Sie fort mit [Scopes und Fehler](/de/docs/api/scopes-errors), der [API-Referenz](/de/docs/api/reference) und den [Rate Limits](/de/docs/api/rate-limits).

---

# Ratenlimits

Source: /de/docs/api/rate-limits.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Pro Schlüssel&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Eine Minute&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Retry-After&#x22;, icon: &#x22;code&#x22; }]" />

Die öffentliche API wendet auf jeden API-Schlüssel und jedes OAuth-Zugriffstoken ein gleitendes Anfragekontingent von einer Minute an. Das Erstellen weiterer Schlüssel, um ein Limit zu umgehen, wird nicht unterstützt und kann zu Einschränkungen von Zugangsdaten oder Konten führen.

## Tariflimits [#tariflimits]

| Aktiver Tarif | Anfragen pro Schlüssel und Minute |
| ------------- | --------------------------------: |
| Launch        |                               120 |
| Operate       |                               600 |
| Scale         |                             1.800 |

Zugangsdaten, deren Konto keinen aktiven kostenpflichtigen Tarif hat, erhalten `403 subscription_required`, bevor Ratenlimit-Kapazität zugewiesen wird. Make Agent Fast kann für ungewöhnlich aufwendige Vorgänge niedrigere endpunktspezifische Limits einführen; in diesem Fall werden sie in der Endpunkt-Referenz ausdrücklich genannt.

## Eine Antwort bei überschrittenem Ratenlimit [#eine-antwort-bei-überschrittenem-ratenlimit]

Ist das Kontingent erschöpft, gibt die API `429 rate_limit_exceeded` zurück, und zwar mit:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-Request-Id: 6c0b2f2e-...
Content-Type: application/json
```

`Retry-After` gibt die Mindestanzahl an Sekunden an, die Sie warten müssen. Jede authentifizierte
Antwort enthält außerdem `X-RateLimit-Limit`, `X-RateLimit-Remaining` und
`X-RateLimit-Reset` (ein Unix-Zeitstempel), sodass Anwendungen ihre Anfragen drosseln können, bevor ein
`429` auftritt.

## Wiederholungslogik implementieren [#wiederholungslogik-implementieren]

Verwenden Sie exponentielles Backoff mit zufälligem Jitter, berücksichtigen Sie einen größeren `Retry-After`-Wert und begrenzen Sie die Gesamtzahl der Versuche.

```ts
async function requestWithRetry(url: string, init: RequestInit, attempts = 4) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, init);
    if (response.status !== 429 && response.status < 500) return response;

    if (attempt === attempts - 1) return response;
    const retryAfter = Number(response.headers.get("retry-after") ?? 0) * 1_000;
    const exponential = 500 * 2 ** attempt;
    const jitter = Math.random() * 250;
    await new Promise((resolve) =>
      setTimeout(resolve, Math.max(retryAfter, exponential + jitter)),
    );
  }
  throw new Error("unreachable");
}
```

Verwenden Sie bei `POST`, `PATCH` und `DELETE` bei jeder Wiederholung nach einem Netzwerk- oder Serverfehler denselben gültigen `Idempotency-Key`. Ein neuer Idempotency-Key kann dazu führen, dass ein bereits abgeschlossener Seiteneffekt erneut ausgeführt wird.

## Anfragevolumen reduzieren [#anfragevolumen-reduzieren]

* Cachen Sie Lesezugriffe auf Konto-, Website- und Konfigurationsdaten, die nicht in Echtzeit aktuell sein müssen.
* Fordern Sie bis zu `100` Datensätze pro Seite an, statt wiederholt sehr kleine Seiten abzurufen.
* Verarbeiten Sie Webhook-Ereignisse, statt Conversations, Leads oder Broadcasts per Polling abzufragen.
* Begrenzen Sie die Worker-Parallelität pro API-Schlüssel; ein Burst aus vielen Serverless-Aufrufen teilt sich dasselbe Kontingent.
* Verwenden Sie separate Schlüssel für separate Dienste, um Isolation und Nachvollziehbarkeit zu erreichen – nicht, um die Kapazität einer einzelnen Workload zu vervielfachen.

## Tabelle: Wiederholen oder nicht wiederholen [#tabelle-wiederholen-oder-nicht-wiederholen]

| Antwort                           | Wiederholen? | Bedingung                                                                                                                  |
| --------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `429`                             | Ja           | Warten Sie auf `Retry-After`, fügen Sie Jitter hinzu und begrenzen Sie die Versuche                                        |
| `500`                             | Manchmal     | Sichere Lesezugriffe oder Änderungen, die durch denselben Idempotency-Key geschützt sind                                   |
| `409` (Verarbeitungskonflikt)     | Ja           | Warten Sie auf den Header `Retry-After: 2` und behalten Sie denselben Idempotency-Key bei                                  |
| Sonstige `409`                    | Nicht sofort | Lesen Sie den aktuellen Zustand der Ressource und lösen Sie den Konflikt auf                                               |
| `503` `outcome_unknown`           | Nein         | Die Änderung wurde möglicherweise abgeschlossen; prüfen Sie die Ressource, bevor Sie einen neuen Idempotency-Key verwenden |
| `400`, `401`, `403`, `404`, `415` | Nein         | Korrigieren Sie zuerst Eingabe, Zugangsdaten, Berechtigung, Pfad oder Inhaltstyp                                           |

Wenn eine dauerhafte Workload ihr Tarifkontingent berechtigterweise überschreitet, reduzieren Sie das Polling, bündeln Sie Aufgaben oder wenden Sie sich mit repräsentativen Anfrage-IDs und dem erwarteten Datenverkehr an den Support, anstatt eine unbegrenzte Wiederholungsschleife einzubauen.

---

# API-Rezepte

Source: /de/docs/api/recipes.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Erstellen&#x22;, icon: &#x22;site&#x22; }, { label: &#x22;Fundieren&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;Veröffentlichen&#x22;, icon: &#x22;globe&#x22; }]" />

Diese Rezepte verwenden rohes REST und funktionieren daher, bevor ein öffentliches SDK installiert ist. Legen Sie `MAF_API_KEY` in der Server-Umgebung fest und ersetzen Sie die IDs, die in früheren Schritten zurückgegeben wurden.

## Rezept: Einen fundierten Agent erstellen und veröffentlichen [#rezept-einen-fundierten-agent-erstellen-und-veröffentlichen]

Erstellen Sie einen API-Schlüssel mit `sites:write`, `agents:write` und `knowledge:write`. Fügen Sie `sites:read` hinzu, wenn die Automatisierung auch Websites auflistet oder überprüft.

### 1. Die Website erstellen [#1-die-website-erstellen]

```bash
curl --fail-with-body https://makeagent.fast/api/v1/sites \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-site-2026-01" \
  -d '{
    "title": "Acme support",
    "slug": "acme-support",
    "type": "business",
    "template": "minimal",
    "content": {
      "headline": "Ask Acme support"
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'
```

Eine erfolgreiche Antwort lautet `201 Created`, enthält die Website unter `data` und gibt ihren kanonischen Ressourcenpfad im `Location`-Header zurück. Speichern Sie `data.id` als `SITE_ID`.

### 2. Den Agent und die Embed-Richtlinie konfigurieren [#2-den-agent-und-die-embed-richtlinie-konfigurieren]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-agent-2026-01" \
  -d '{
    "display_name": "Acme guide",
    "persona_mode": "assistant",
    "instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
    "languages": ["en"],
    "embed_enabled": true,
    "allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
  }'
```

Erlaubte Origins sind exakte Origins: Schema, Hostname und optional ein Port. Geben Sie keinen Pfad und keinen abschließenden Platzhalter an.

### 3. Eine Text-Quelle hinzufügen [#3-eine-text-quelle-hinzufügen]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-returns-2026-01" \
  -d '{
    "name": "Returns policy 2026-01",
    "text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
  }'
```

Eingefügter Text muss zwischen 5 und 200.000 Zeichen lang sein. Derselbe Endpunkt kann auch eine Website mit `{ "url", "max_pages", "refresh_hours" }` crawlen (`max_pages` bis zu 40) oder `{ "kind": "youtube" | "podcast" | "feed", "url" }` importieren. Diese Medien-Quellen erfordern Operate oder Scale und liefern bei Launch `409` zurück. Datei-Uploads sind weiterhin nur im Dashboard möglich.

### 4. Ein strukturiertes FAQ hinzufügen [#4-ein-strukturiertes-faq-hinzufügen]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
  -d '{
    "question": "How long do I have to return an order?",
    "answer": "You may request a return within 30 days of delivery.",
    "approved": true
  }'
```

### 5. Veröffentlichen [#5-veröffentlichen]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-publish-2026-01" \
  -d '{"published": true}'
```

Die Antwort sollte `{"data":{"id":"...","status":"published"}}` enthalten. Öffnen Sie ein echtes Embed und stellen Sie eine Frage, deren Antwort in der Quelle steht. Die Veröffentlichung belegt, dass sich der Zustand des Agents geändert hat; sie belegt nicht, dass die Qualität der Quelle oder der Embed-Origin korrekt ist.

## Rezept: Leads sicher paginieren [#rezept-leads-sicher-paginieren]

Verwenden Sie einen Schlüssel mit `leads:read`. Behandeln Sie `next_cursor` als opak und kodieren Sie ihn per URL-Encoding.

```ts
const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
  });
  if (!response.ok) throw await response.json();

  const page = await response.json();
  for (const lead of page.data) await exportLead(lead);
  cursor = page.next_cursor;
} while (cursor);
```

Dekodieren, bearbeiten oder sortieren Sie einen Cursor nicht und verwenden Sie ihn nicht für eine andere Collection.

## Rezept: Ein Embed bei einem Vorfall deaktivieren [#rezept-ein-embed-bei-einem-vorfall-deaktivieren]

Verwenden Sie `agents:write` und behalten Sie bei Netzwerk-Wiederholungen denselben Idempotency-Key bei:

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-07-embed-off" \
  -d '{"embed_enabled": false}'
```

Prüfen Sie nach der erfolgreichen Antwort, dass sich der Launcher auf einem erlaubten Host nicht mehr initialisiert. Aktivieren Sie ihn mit einem neuen Schlüssel für die Vorfallbehebung wieder, nachdem Sie das Problem mit dem Origin, dem Inhalt oder den Zugangsdaten behoben haben.

## Checkliste für die Produktion [#checkliste-für-die-produktion]

* Verwenden Sie pro Dienst und Umgebung einen eigenen Schlüssel.
* Speichern Sie Ressourcen-IDs und Idempotency-Keys, bevor Sie eine Mutation senden.
* Legen Sie Timeouts für Verbindungsaufbau und Antwort fest.
* Beachten Sie `Retry-After` und begrenzen Sie die Anzahl der Wiederholungen.
* Protokollieren Sie Operationsname, HTTP-Status und Request-ID, ohne Secrets oder personenbezogene Daten zu protokollieren.
* Testen Sie mit einer Nicht-Produktions-Website, bevor Sie Schreibberechtigungen für die Produktion vergeben.

---

# API-Referenz

Source: /de/docs/api/reference.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;v1&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;123 Operationen&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;JSON&#x22;, icon: &#x22;book&#x22; }]" />

Der maßgebliche maschinenlesbare Vertrag ist das [OpenAPI JSON](/api/openapi.json). Diese Seite ist der menschenlesbare Operationsindex und erklärt die Regeln, die für jeden Endpunkt gelten.

## Basis-URL und Version [#basis-url-und-version]

```text
https://makeagent.fast/api/v1
```

Die Hauptversion ist Teil des Pfads. Zusätzliche Felder können ohne Änderung der Hauptversion hinzukommen. Ignorieren Sie daher unbekannte Felder in Antworten. Alle Management-Anfragen verwenden HTTPS sowie einen Bearer-API-Schlüssel oder ein OAuth-Zugriffstoken.

## Gemeinsame Header [#gemeinsame-header]

```http
Authorization: Bearer maf_live_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: your-stable-operation-key
```

`Content-Type` ist für JSON-Bodys bei `POST` und `PATCH` erforderlich, auch bei `{}`. `Idempotency-Key` ist optional, wird aber für jedes `POST`, `PATCH` und `DELETE` dringend empfohlen.

## Konto und Websites [#konto-und-websites]

| Methode  | Pfad                         | Scope          | Zweck                                                                                                                                                               |
| -------- | ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/me`                        | `account:read` | Konto, Tarif, Berechtigungen und Wallet-Übersicht lesen                                                                                                             |
| `GET`    | `/sites`                     | `sites:read`   | Eigene Websites auflisten                                                                                                                                           |
| `POST`   | `/sites`                     | `sites:write`  | Eine Website und ihren Standard-Agent erstellen                                                                                                                     |
| `GET`    | `/sites/{site_id}`           | `sites:read`   | Eine eigene Website abrufen                                                                                                                                         |
| `PATCH`  | `/sites/{site_id}`           | `sites:write`  | Unkritische Website-Felder aktualisieren                                                                                                                            |
| `DELETE` | `/sites/{site_id}`           | `sites:write`  | Die Website und abhängige Ressourcen löschen                                                                                                                        |
| `POST`   | `/sites/{site_id}/publish`   | `sites:write`  | Mit `{ "published": boolean }` veröffentlichen oder die Veröffentlichung aufheben                                                                                   |
| `GET`    | `/sites/{site_id}/agent`     | `agents:read`  | Agent-Einstellungen lesen                                                                                                                                           |
| `PATCH`  | `/sites/{site_id}/agent`     | `agents:write` | Persona-Modus, Zweck, Anzeigenamen, Anweisungen, Stimme, Sprachen, Modell, Erscheinungsbild, Einbettungsrahmen, Badge, Einbettungsstatus oder Origins aktualisieren |
| `GET`    | `/sites/{site_id}/billing`   | `account:read` | Tarif, Abrechnungszeitraum, Wallet, Add-ons und die Abrechnungslinks im Dashboard lesen                                                                             |
| `PATCH`  | `/sites/{site_id}/workspace` | `team:write`   | Das Unternehmen umbenennen, dem der Agent gehört                                                                                                                    |
| `PATCH`  | `/sites/{site_id}/retention` | `team:write`   | Festlegen, wie lange Unterhaltungen aufbewahrt werden                                                                                                               |

Zum Erstellen einer Website sind `title` und `content.headline` erforderlich. Optionale Felder sind `slug`, `type`, `template`, zusätzliche Inhalte, `persona_mode` sowie ein bis vier Sprachen aus `en`, `ko`, `uz` und `ru`.

`PATCH /agent` führt `model`, `appearance`, `embed_chrome` und `badge_hidden` durch dieselben Tarifprüfungen wie das Dashboard; `badge_hidden: true` erfordert einen berechtigten Tarif oder das Badge-Add-on.

## Installation und Website-Widget [#installation-und-website-widget]

| Methode | Pfad                             | Scope          | Zweck                                                                                   |
| ------- | -------------------------------- | -------------- | --------------------------------------------------------------------------------------- |
| `GET`   | `/sites/{site_id}/install`       | `agents:read`  | Installationsziel, Einbettungsstatus, erlaubte Origins und Installationsnachweise lesen |
| `PATCH` | `/sites/{site_id}/install`       | `agents:write` | Die Seite festlegen, auf der das Widget installiert werden soll                         |
| `POST`  | `/sites/{site_id}/install/check` | `agents:write` | Prüfen, ob das Einbettungs-Snippet auf der Zielseite live ist                           |

## Wissen und FAQs [#wissen-und-faqs]

| Methode            | Pfad                                                           | Scope                                | Zweck                                                                                                                      |
| ------------------ | -------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `GET`              | `/sites/{site_id}/knowledge`                                   | `knowledge:read`                     | Wissensquellen auflisten                                                                                                   |
| `POST`             | `/sites/{site_id}/knowledge`                                   | `knowledge:write`                    | Eingefügten Text aufnehmen, eine Website crawlen oder eine YouTube-, Podcast- oder Feed-Quelle importieren                 |
| `PATCH`            | `/sites/{site_id}/knowledge/{source_id}`                       | `knowledge:write`                    | `refresh_hours` oder den `approval_status` des Buyer-Packs festlegen                                                       |
| `POST`             | `/sites/{site_id}/knowledge/{source_id}/recrawl`               | `knowledge:write`                    | Erneutes Einlesen einer abgerufenen Quelle in die Warteschlange stellen; gibt `202` zurück                                 |
| `DELETE`           | `/sites/{site_id}/knowledge/{source_id}`                       | `knowledge:write`                    | Eine Quelle aus dem künftigen Abruf entfernen                                                                              |
| `GET`              | `/sites/{site_id}/faqs`                                        | `knowledge:read`                     | Strukturierte FAQs auflisten                                                                                               |
| `POST`             | `/sites/{site_id}/faqs`                                        | `knowledge:write`                    | `{ "question", "answer", "approved" }` erstellen                                                                           |
| `POST`             | `/sites/{site_id}/faqs/generate`                               | `knowledge:write`                    | FAQs aus dem Wissen des Agents entwerfen                                                                                   |
| `POST`             | `/sites/{site_id}/faqs/approve-all`                            | `knowledge:write`                    | Jede FAQ im Entwurfsstatus freigeben und veröffentlichen                                                                   |
| `PATCH`            | `/sites/{site_id}/faqs/{faq_id}`                               | `knowledge:write`                    | Frage, Antwort oder Freigabestatus aktualisieren                                                                           |
| `DELETE`           | `/sites/{site_id}/faqs/{faq_id}`                               | `knowledge:write`                    | Eine FAQ löschen                                                                                                           |
| `GET` / `PATCH`    | `/sites/{site_id}/fact-sheet`                                  | `knowledge:read` / `knowledge:write` | Das extrahierte Faktenblatt des Unternehmens lesen oder Fakten korrigieren, die bei der Extraktion falsch erkannt wurden   |
| `POST`             | `/sites/{site_id}/fact-sheet/reextract`                        | `knowledge:write`                    | Die Website erneut einlesen und das Faktenblatt neu erstellen                                                              |
| `POST`             | `/sites/{site_id}/qa`                                          | `knowledge:write`                    | Kuratierte Frage-Antwort-Paare veröffentlichen                                                                             |
| `POST`             | `/sites/{site_id}/answers/revise`                              | `knowledge:write`                    | Dem Agent die Antwort beibringen, die er hätte geben sollen                                                                |
| `GET`              | `/sites/{site_id}/knowledge-connections`                       | `knowledge:read`                     | Wissensverbindungen zu Notion, Drive und MCP auflisten                                                                     |
| `GET`              | `/sites/{site_id}/knowledge-connections/connect-links`         | `knowledge:read`                     | Die Dashboard-URLs abrufen, die eine Notion- oder Drive-Verbindung starten                                                 |
| `PATCH` / `DELETE` | `/sites/{site_id}/knowledge-connections/{connection_id}`       | `knowledge:write`                    | Synchronisierungsintervall, ausgewählte Elemente oder Importwerkzeug festlegen; oder die Verbindung trennen und bereinigen |
| `GET`              | `/sites/{site_id}/knowledge-connections/{connection_id}/items` | `knowledge:read`                     | Die Seiten, Datenbanken oder Dateien auflisten, die eine Verbindung importieren kann                                       |
| `POST`             | `/sites/{site_id}/knowledge-connections/{connection_id}/sync`  | `knowledge:write`                    | Eine Synchronisierung einer Wissensverbindung in die Warteschlange stellen                                                 |

`POST /knowledge` akzeptiert drei Bodys: `{ "name", "text" }` mit 5 bis 200.000 Zeichen; `{ "url", "max_pages", "refresh_hours" }`, um eine Website zu crawlen (`max_pages` 1–40, `refresh_hours` 1–8.760 oder `null`); sowie `{ "kind": "youtube" | "podcast" | "feed", "url", "refresh_hours" }`. YouTube-, Podcast- und Feed-Quellen erfordern Operate oder Scale; bei Launch geben sie `409 conflict` zurück. Der Datei-Upload bleibt ein Dashboard-Workflow.

## Unterhaltungen, Leads, Analysen und Nutzung [#unterhaltungen-leads-analysen-und-nutzung]

| Methode | Pfad                                                      | Scope                 | Zweck                                                                                   |
| ------- | --------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------- |
| `GET`   | `/sites/{site_id}/conversations`                          | `conversations:read`  | Unterhaltungsverläufe auflisten                                                         |
| `GET`   | `/sites/{site_id}/conversations/{conversation_id}`        | `conversations:read`  | Einen Verlauf und paginierte Nachrichten abrufen                                        |
| `POST`  | `/sites/{site_id}/conversations/{conversation_id}/reply`  | `conversations:write` | Einem Besucher im Namen des Unternehmens antworten                                      |
| `POST`  | `/sites/{site_id}/conversations/{conversation_id}/pause`  | `conversations:write` | Den Agent in dieser Unterhaltung pausieren und sie übernehmen                           |
| `POST`  | `/sites/{site_id}/conversations/{conversation_id}/resume` | `conversations:write` | Die Unterhaltung an den Agent zurückgeben                                               |
| `GET`   | `/sites/{site_id}/leads`                                  | `leads:read`          | Erfasste Leads auflisten                                                                |
| `POST`  | `/sites/{site_id}/leads`                                  | `leads:write`         | Einen kanonischen Lead mit ausdrücklicher Einwilligung und Kontaktpräferenzen erstellen |
| `GET`   | `/sites/{site_id}/leads/{lead_id}`                        | `leads:read`          | Einen Lead abrufen                                                                      |
| `PATCH` | `/sites/{site_id}/leads/{lead_id}`                        | `leads:write`         | Einen Lead aktualisieren, qualifizieren oder seine Kontaktrichtlinie ändern             |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/accept`                 | `leads:write`         | Einen Lead in die Opportunity-Pipeline übernehmen                                       |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/followup`               | `leads:write`         | Die Folgenachricht an einen Lead senden                                                 |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/followup/draft`         | `leads:write`         | Die Folgenachricht neu entwerfen, ohne sie zu senden                                    |
| `GET`   | `/sites/{site_id}/analytics`                              | `analytics:read`      | Analyseereignisse auflisten                                                             |
| `GET`   | `/sites/{site_id}/report`                                 | `analytics:read`      | Den aggregierten Analysebericht lesen                                                   |
| `POST`  | `/sites/{site_id}/report/unanswered-faq`                  | `knowledge:write`     | Eine unbeantwortete Frage als neue FAQ beantworten                                      |
| `GET`   | `/sites/{site_id}/usage`                                  | `usage:read`          | Gemessene Nutzungsereignisse auflisten                                                  |

Diese Ereignis- und Aktivitätssammlungen akzeptieren `limit` und `cursor`. Zurückgegebene Datensätze können personenbezogene Daten enthalten; speichern und exportieren Sie sie gemäß Ihren Datenschutzpflichten.

Antworten des Owners werden unterstützt: `reply`, `pause` und `resume` übernehmen einen Web-Verlauf oder einen Chat auf Telegram, WhatsApp, Messenger oder Instagram auf dieselbe Weise wie das Dashboard. Das Senden von Nachrichten als Besucher ist keine öffentliche API-Operation.
Die Änderung von Leads wird unterstützt; setzen Sie `consent_status: granted` nur, wenn Ihr System
über einen belastbaren Einwilligungsnachweis verfügt. Unbekannte Einwilligungen werden von Broadcasts ausgeschlossen.

## Opportunity-Pipeline und CRM-Ergebnisse [#opportunity-pipeline-und-crm-ergebnisse]

| Methode         | Pfad                                                                                                          | Scope                              | Zweck                                                                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/stages`                                                                            | `pipeline:read` / `pipeline:write` | Phasen auflisten oder konfigurieren                                                                                                         |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/accounts`                                                                          | `pipeline:read` / `pipeline:write` | Geschäftskonten auflisten oder erstellen                                                                                                    |
| `GET`           | `/sites/{site_id}/pipeline/accounts/{account_id}`                                                             | `pipeline:read`                    | Ein Geschäftskonto abrufen                                                                                                                  |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/opportunities`                                                                     | `pipeline:read` / `pipeline:write` | Opportunities auflisten oder erstellen                                                                                                      |
| `GET` / `PATCH` | `/sites/{site_id}/pipeline/opportunities/{opportunity_id}`                                                    | `pipeline:read` / `pipeline:write` | Aktivitäten lesen oder Zuweisung, Wert, Phase, nächste Aktion und menschliche Antwort aktualisieren                                         |
| `POST`          | `/sites/{site_id}/pipeline/outcomes`                                                                          | `pipeline:write`                   | Ein aus dem CRM stammendes Ergebnis (gewonnen oder verloren) idempotent importieren                                                         |
| `GET`           | `/sites/{site_id}/pipeline/sync-records`                                                                      | `pipeline:read`                    | Synchronisierungsstatus, Versuche und Fehler auflisten                                                                                      |
| `POST`          | `/sites/{site_id}/pipeline/sync-records/{sync_record_id}/retry`                                               | `pipeline:write`                   | Ein fehlgeschlagenes Ergebnis anhand seiner gespeicherten Nutzdaten erneut versuchen                                                        |
| `GET` / `PATCH` | `/sites/{site_id}/pipeline-workflow`                                                                          | `pipeline:read` / `pipeline:write` | Die Vertriebsantwort-Richtlinie lesen oder aktualisieren                                                                                    |
| `GET` / `POST`  | `/sites/{site_id}/pilots`                                                                                     | `pipeline:read` / `pipeline:write` | Geführte Pilotprojekte auflisten oder starten                                                                                               |
| `GET`           | `/sites/{site_id}/pilots/{pilot_id}`                                                                          | `pipeline:read`                    | Ein Pilotprojekt, seine Phase, Zählwerte und Arbeitsliste lesen                                                                             |
| `POST`          | `/sites/{site_id}/pilots/{pilot_id}/setup`, `/start`, `/stop`, `/review`, `/decision`, `/complete`, `/delete` | `pipeline:write`                   | Ein Pilotprojekt durch Einrichtung, Messung, Review, Entscheidung und Abschluss führen oder es samt Nachweisen löschen (sieben Operationen) |
| `POST`          | `/sites/{site_id}/pilots/{pilot_id}/outcomes`, `/bookings`                                                    | `pipeline:write`                   | Ein Lead-Ergebnis oder ein Buchungsergebnis erfassen (zwei Operationen)                                                                     |
| `POST`          | `/sites/{site_id}/pilots/{pilot_id}/report/approve`, `/report/revoke`                                         | `pipeline:write`                   | Den teilbaren Pilotbericht freigeben oder die Freigabe widerrufen (zwei Operationen)                                                        |
| `GET` / `POST`  | `/sites/{site_id}/buyer-packs`                                                                                | `pipeline:read` / `pipeline:write` | Buyer-Packs auflisten oder eines aus freigegebenen Quellen erstellen                                                                        |
| `PATCH`         | `/sites/{site_id}/buyer-packs/{pack_id}`                                                                      | `pipeline:write`                   | Titel, Zielgruppe, Zusammenfassung, Quellen und Abschnitte eines Packs ersetzen                                                             |
| `POST`          | `/sites/{site_id}/buyer-packs/{pack_id}/approve`, `/revoke`                                                   | `pipeline:write`                   | Den Freigabelink des Packs aktivieren oder deaktivieren (zwei Operationen)                                                                  |

Der angegebene CRM-`provider`, die externe ID und der Idempotenzschlüssel bleiben im Audit-Trail
erhalten. Ein Retry übernimmt nur einen fehlgeschlagenen Datensatz und macht aus einem laufenden
externen Schreibvorgang niemals einen fälschlichen Erfolg.

## Connectors [#connectors]

| Methode  | Pfad                                          | Scope              | Zweck                                                                                                                      |
| -------- | --------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/sites/{site_id}/connectors`                 | `connectors:read`  | Connector-Status ohne Geheimnisse auflisten                                                                                |
| `POST`   | `/sites/{site_id}/connectors`                 | `connectors:write` | Einen Kanal verbinden: Zugangsdaten live validieren, den Webhook bereitstellen und die Einrichtungs-Checkliste zurückgeben |
| `PATCH`  | `/sites/{site_id}/connectors/{connector_id}`  | `connectors:write` | `status` oder `reply_with_voice` festlegen                                                                                 |
| `DELETE` | `/sites/{site_id}/connectors/{connector_id}`  | `connectors:write` | Einen Connector deprovisionieren und entfernen                                                                             |
| `POST`   | `/sites/{site_id}/concierge`                  | `connectors:write` | Die Plattform bitten, einen Messaging-Kanal für Sie zu verbinden                                                           |
| `GET`    | `/sites/{site_id}/domains`                    | `domains:read`     | Entfernt – gibt `409` zurück. Eigene Domains werden nicht angeboten                                                        |
| `POST`   | `/sites/{site_id}/domains`                    | `domains:write`    | Entfernt – gibt `409` zurück                                                                                               |
| `PATCH`  | `/sites/{site_id}/domains/{domain_id}`        | `domains:write`    | Entfernt – gibt `409` zurück                                                                                               |
| `POST`   | `/sites/{site_id}/domains/{domain_id}/verify` | `domains:write`    | Entfernt – gibt `409` zurück                                                                                               |
| `DELETE` | `/sites/{site_id}/domains/{domain_id}`        | `domains:write`    | Entfernt – gibt `409` zurück                                                                                               |

Die Erstellung eines Connectors verwendet einen nach Kanal unterschiedenen Body. Die Felder für Zugangsdaten unterscheiden sich bei `telegram`, `whatsapp`, `messenger`, `instagram`, `discord` und `kakao`; verwenden Sie die passende Connector-Anleitung, bevor Sie Geheimnisse senden.

## Broadcasts, Benachrichtigungen und Monetarisierung [#broadcasts-benachrichtigungen-und-monetarisierung]

| Methode  | Pfad                                                  | Scope                 | Zweck                                                                     |
| -------- | ----------------------------------------------------- | --------------------- | ------------------------------------------------------------------------- |
| `GET`    | `/sites/{site_id}/broadcasts`                         | `broadcasts:read`     | Broadcasts auflisten                                                      |
| `POST`   | `/sites/{site_id}/broadcasts`                         | `broadcasts:write`    | Einen Kakao-Broadcast-Entwurf erstellen                                   |
| `POST`   | `/sites/{site_id}/broadcasts/{broadcast_id}/send`     | `broadcasts:write`    | Einen vorhandenen Entwurf in die Warteschlange stellen; gibt `202` zurück |
| `GET`    | `/sites/{site_id}/notifications`                      | `notifications:read`  | Owner-Benachrichtigungen auflisten                                        |
| `POST`   | `/sites/{site_id}/notifications/read-all`             | `notifications:write` | Jede Owner-Benachrichtigung für diesen Agent als gelesen markieren        |
| `PATCH`  | `/sites/{site_id}/notifications/{notification_id}`    | `notifications:write` | Mit `{ "read": boolean }` als gelesen oder ungelesen markieren            |
| `GET`    | `/sites/{site_id}/alerts`                             | `notifications:read`  | Den Status des Alarmkanals des Owners und seinen Dashboard-Link lesen     |
| `GET`    | `/sites/{site_id}/monetization/products`              | `monetization:read`   | Website-Produkte auflisten                                                |
| `POST`   | `/sites/{site_id}/monetization/products`              | `monetization:write`  | Ein Produkt vom Typ `access`, `consult`, `tip` oder `digital` erstellen   |
| `PATCH`  | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write`  | Produktfelder und aktiven Status aktualisieren                            |
| `DELETE` | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write`  | Ein Produkt löschen                                                       |

Die Erstellung von Broadcasts akzeptiert derzeit nur den Kanal `kakao`. Das Einreihen in die Warteschlange schlägt mit `409 conflict` fehl, wenn es keine erreichbaren Empfänger gibt oder der Broadcast kein Entwurf mehr ist.

## Aktionen, Tickets und Team [#aktionen-tickets-und-team]

| Methode            | Pfad                                                | Scope                          | Zweck                                                                                               |
| ------------------ | --------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
| `GET` / `PATCH`    | `/sites/{site_id}/actions`                          | `agents:read` / `agents:write` | Prozeduren, den öffentlichen Webhook, den Buchungslink und Support-Tickets lesen oder konfigurieren |
| `GET`              | `/sites/{site_id}/tickets`                          | `tickets:read`                 | Support-Tickets auflisten                                                                           |
| `GET`              | `/sites/{site_id}/tickets/{ticket_id}`              | `tickets:read`                 | Ein Ticket und seine Nachrichten lesen                                                              |
| `PATCH`            | `/sites/{site_id}/tickets/{ticket_id}`              | `tickets:write`                | Status, Priorität und optional die zuständige Person festlegen                                      |
| `POST`             | `/sites/{site_id}/tickets/{ticket_id}/messages`     | `tickets:write`                | Eine interne Notiz hinzufügen oder mit `internal: false` dem Kunden per E-Mail antworten            |
| `GET`              | `/sites/{site_id}/team`                             | `team:read`                    | Mitglieder, Einladungen und zulässige Audit-Ereignisse lesen                                        |
| `POST`             | `/sites/{site_id}/team/invitations`                 | `team:write`                   | Einen Einladungslink erstellen, ohne eine E-Mail zu senden                                          |
| `DELETE`           | `/sites/{site_id}/team/invitations/{invitation_id}` | `team:write`                   | Eine ausstehende Einladung widerrufen                                                               |
| `PATCH` / `DELETE` | `/sites/{site_id}/team/members/{membership_id}`     | `team:write`                   | Die Rolle eines Mitglieds, das nicht Owner ist, ändern oder das Mitglied entfernen                  |

## Entwickler-Webhooks und Einrichtungswerkzeuge [#entwickler-webhooks-und-einrichtungswerkzeuge]

| Methode  | Pfad                               | Scope                          | Zweck                                                                                                                                                                                  |
| -------- | ---------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/webhook-endpoints`               | `webhooks:read`                | Endpunktstatus ohne Signaturgeheimnisse auflisten                                                                                                                                      |
| `POST`   | `/webhook-endpoints`               | `webhooks:write`               | Eine öffentliche HTTPS-URL registrieren und ihr Signaturgeheimnis einmalig anzeigen                                                                                                    |
| `DELETE` | `/webhook-endpoints/{endpoint_id}` | `webhooks:write`               | Einen Endpunkt löschen und die künftige Zustellung stoppen                                                                                                                             |
| `GET`    | `/setup/tools`                     | Beliebige gültige Zugangsdaten | Einrichtungswerkzeuge für API-, MCP- und GitHub-Integrationen ermitteln                                                                                                                |
| `POST`   | `/setup/tools/{tool_name}`         | Werkzeugspezifisch             | Ein Einrichtungswerkzeug ausführen; Plattformanfragen benötigen die Scopes ihrer Endpunkte, die GitHub-Prüfung verwendet `integrations:read`, die PR-Vorbereitung `integrations:write` |

Webhook-URLs müssen HTTPS verwenden, dürfen keine Zugangsdaten und keinen benutzerdefinierten Port enthalten und müssen ausschließlich auf öffentliche IP-Adressen auflösen.

## Paginierung [#paginierung]

Paginierte Sammlungen akzeptieren `limit` von `1` bis `100`; der Standardwert ist `50`. Verwenden Sie den zurückgegebenen undurchsichtigen `next_cursor` nur mit derselben Sammlung und denselben Filtern.

```json
{
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

Einige kleine Konfigurationssammlungen geben dieselbe Hülle mit `has_more: false` zurück und benötigen keinen Cursor.

## Idempotenz [#idempotenz]

Ein Idempotenzschlüssel muss 8 bis 200 Zeichen enthalten: Buchstaben, Ziffern sowie `.`, `_`, `:` und `-`. Ergebnisse werden 24 Stunden lang aufbewahrt und gelten für den Inhaber der Zugangsdaten.

* Gleicher Schlüssel und gleiche Methode, gleicher Pfad, gleiche Query und gleicher Body: gibt die gespeicherte Antwort mit `x-idempotent-replayed: true` zurück.
* Gleicher Schlüssel mit anderer Eingabe: gibt `409 conflict` zurück.
* Gleicher Schlüssel, während die erste Anfrage noch verarbeitet wird: gibt `409 conflict` und `Retry-After: 2` zurück.

Speichern Sie den Schlüssel, bevor Sie die Mutation senden, und verwenden Sie ihn nur für Wiederholungen derselben logischen Operation erneut.

## Antworten und Fehler [#antworten-und-fehler]

Erfolgreiche Antworten verpacken ihre Ressource in `data`. Erstellungsoperationen geben normalerweise `201` zurück; in die Warteschlange gestellte Broadcast-Sendungen geben `202` zurück; andere erfolgreiche Operationen geben `200` zurück. Jede Antwort enthält `x-request-id` und verwendet für API-Daten `Cache-Control: no-store`.

Die vollständige Tabelle der Fehlercodes finden Sie unter [Scopes und Fehler](/de/docs/api/scopes-errors), kopierbare Workflows unter [API-Rezepte](/de/docs/api/recipes).

## MCP-Clients [#mcp-clients]

Verbinden Sie einen Streamable-HTTP-MCP-Client mit `https://makeagent.fast/api/mcp`. Clients, die OAuth Discovery unterstützen, öffnen den Browser für Anmeldung und Einwilligung. Prüfen Sie vor der Freigabe die Identität des Clients, das Unternehmen und die angeforderten Scopes. Die erste Freigabe fragt die Scopes ab, die die Tools verwenden (`sites:read`, `sites:write`, `agents:write`, `analytics:read`, `conversations:read`, `conversations:write`, `leads:read`, `leads:write`, `knowledge:write`); bei Zugangsdaten, denen einer dieser Scopes fehlt, wird erneut um Autorisierung gebeten. Ein aktiver Tarif ist erforderlich.

Für Clients mit manuell konfigurierten Zugangsdaten erstellen Sie in den [Entwicklereinstellungen](/dashboard/settings/developer) einen API-Schlüssel mit begrenzten Scopes und übergeben ihn als Header `Authorization: Bearer ...`. Halten Sie Zugangsdaten aus der Versionsverwaltung und aus Browsercode heraus. API-Schlüssel oder OAuth-Berechtigungen widerrufen Sie in den Entwicklereinstellungen.

Lese-Tools: `list_agents`, `get_agent`, `get_report`, `list_unanswered_questions`, `list_conversations`, `get_conversation`, `list_leads`. Schreib-Tools: `create_agent_from_website`, `create_agent_from_notes`, `test_agent`, `add_knowledge`, `save_answer`, `reply_to_customer`, `update_lead`, `set_website_widget`. Jedes Agent-Tool erwartet eine `agent_id` aus `list_agents`. `test_agent` verbraucht Credits wie eine normale Antwort; `reply_to_customer` sendet eine Nachricht an den Kunden und pausiert den Agent in dieser Unterhaltung; `set_website_widget` schaltet das Website-Chat-Widget ein oder aus; Messaging-Kanäle werden im Dashboard verwaltet. Clients mit aktivierten MCP Apps (standardmäßig die authentifizierte Claude-Verbindung) erhalten außerdem `list_pending_approvals`, `list_action_runs` und `decide_approval`, womit eine vom Kunden bestätigte Änderung genehmigt oder abgelehnt wird; andere Clients sehen nur die 15 oben genannten Tools. Für die Einrichtungs- und GitHub-Integrationstools verwenden Sie den In-App-Einrichtungsassistenten oder `/api/v1/setup/tools`.

Unterstützte Protokollrevisionen sind `2026-07-28`, `2025-11-25` und `2025-06-18`. Der Transport liefert JSON; ältere SSE-Varianten oder Server-Sitzungen werden nicht angeboten. MCP-OAuth-Tokens autorisieren nur `/api/mcp`, nicht direkte REST-Anfragen. OAuth-Zugriffstokens sind eine Stunde gültig; Refresh-Zugangsdaten werden rotiert und laufen nach 90 Tagen ab. Manuell erstellte API-Schlüssel verwenden ihr konfiguriertes Ablaufdatum.

---

# Scopes und Fehler

Source: /de/docs/api/scopes-errors.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;33 Scopes&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Stabile Codes&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;Request-IDs&#x22;, icon: &#x22;link&#x22; }]" />

Jede Operation der öffentlichen API erfordert einen expliziten Scope. Ein gültiger Zugangsschlüssel ohne diesen Scope erhält `403 insufficient_scope`; er wird nie stillschweigend auf einen umfassenderen Zugriff erweitert.

## Scope-Referenz [#scope-referenz]

| Scope                 | Erlaubt                                                                                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account:read`        | Das authentifizierte Konto, den Tarif, die Berechtigungen und die Guthabenübersicht lesen                                                            |
| `tickets:read`        | Support-Tickets und deren Nachrichten lesen                                                                                                          |
| `tickets:write`       | Tickets aktualisieren, Team-Mitglieder zuweisen und interne Notizen oder Antworten an Kunden hinzufügen                                              |
| `team:read`           | Team-Mitglieder, ausstehende Einladungen und zulässige Audit-Ereignisse lesen                                                                        |
| `team:write`          | Einladungen erstellen oder widerrufen und Rollen von Team-Mitgliedern (außer Owner) verwalten                                                        |
| `integrations:read`   | Autorisierte GitHub-App-Installationen und Repositories einsehen                                                                                     |
| `integrations:write`  | Integrationsänderungen vorbereiten und Entwurfs-Pull-Requests erstellen                                                                              |
| `sites:read`          | Sites auflisten und abrufen                                                                                                                          |
| `sites:write`         | Sites erstellen, aktualisieren, veröffentlichen, depublizieren und löschen                                                                           |
| `agents:read`         | Agent-Einstellungen lesen                                                                                                                            |
| `agents:write`        | Verhalten, Sprache, Stimme und Einbettungseinstellungen des Agents aktualisieren                                                                     |
| `knowledge:read`      | Sources und FAQs auflisten                                                                                                                           |
| `knowledge:write`     | Sources und FAQs erstellen, aktualisieren und löschen                                                                                                |
| `conversations:read`  | Konversationen auflisten und deren Nachrichten abrufen                                                                                               |
| `conversations:write` | Eine Konversation übernehmen: als Unternehmen auf einen Besucher antworten, den Agent in dieser Konversation pausieren und sie wieder zurückgeben    |
| `leads:read`          | Erfasste Leads auflisten                                                                                                                             |
| `leads:write`         | Leads erstellen, aktualisieren, qualifizieren und in die Opportunity-Pipeline übernehmen                                                             |
| `pipeline:read`       | Phasen, Accounts, Opportunities, Aktivitäten, Attribution und den CRM-Synchronisierungsstatus lesen                                                  |
| `pipeline:write`      | Phasen konfigurieren; Opportunities und Accounts erstellen oder aktualisieren; CRM-Ergebnisse importieren oder erneut versuchen                      |
| `analytics:read`      | Analyseereignisse einer Site lesen                                                                                                                   |
| `connectors:read`     | Den Status von Connectors auflisten, ohne Geheimnisse zurückzugeben                                                                                  |
| `connectors:write`    | Connectors erstellen, aktualisieren, aktivieren, deaktivieren und entfernen                                                                          |
| `domains:read`        | Entfernt. Nur aus Kompatibilitätsgründen beibehalten; jede `/domains`-Route gibt `409` zurück, da keine benutzerdefinierten Domains angeboten werden |
| `domains:write`       | Entfernt. Nur aus Kompatibilitätsgründen beibehalten; jede `/domains`-Route gibt `409` zurück                                                        |
| `broadcasts:read`     | Broadcasts und deren Zustellstatus auflisten                                                                                                         |
| `broadcasts:write`    | Entwürfe erstellen und den Versand eines Broadcasts in die Warteschlange stellen                                                                     |
| `notifications:read`  | Benachrichtigungen für Owner auflisten                                                                                                               |
| `notifications:write` | Benachrichtigungen als gelesen oder ungelesen markieren                                                                                              |
| `monetization:read`   | Monetarisierungsprodukte auflisten                                                                                                                   |
| `monetization:write`  | Produkte erstellen, aktualisieren, aktivieren, deaktivieren und löschen                                                                              |
| `usage:read`          | Gemessene Nutzungsereignisse lesen                                                                                                                   |
| `webhooks:read`       | Webhook-Endpunkte und deren Zustellstatus auflisten                                                                                                  |
| `webhooks:write`      | Webhook-Endpunkte erstellen und löschen                                                                                                              |

Verwenden Sie für Reporting-Jobs Lese-Scopes. Fügen Sie einen Schreib-Scope nur hinzu, wenn die Integration diese Änderung tatsächlich durchführt. Ein Lead-Export benötigt beispielsweise normalerweise `sites:read` und `leads:read`, nicht jedoch `sites:write` oder `agents:write`.

## Scope-Fehler [#scope-fehler]

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}
```

Fügen Sie den fehlenden Scope dem Schlüssel unter **Einstellungen → Entwickler → Bearbeiten** hinzu, oder erstellen Sie einen Ersatzschlüssel und aktualisieren Sie das Server-Secret. Beim Bearbeiten werden Name und Scopes des Schlüssels direkt geändert; Ablaufdatum und Token bleiben gleich. Über OAuth ausgestellte Schlüssel können nicht bearbeitet werden; verbinden Sie die Anwendung erneut, um die erteilten Berechtigungen zu ändern.

## Fehlerstruktur [#fehlerstruktur]

Alle API-Fehler verwenden dieselbe Struktur auf oberster Ebene:

```ts
type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};
```

Verzweigen Sie anhand von `error.code`, nicht anhand der englischen `message`. Meldungen können ohne Versionswechsel verbessert werden. Protokollieren Sie `error.request_id` und den Response-Header `x-request-id` zusammen mit Operationsname, Status und Wiederholungsversuch – protokollieren Sie jedoch niemals den Authorization-Header oder geheime Anfragedaten.

## Referenz zu Status und Codes [#referenz-zu-status-und-codes]

| HTTP  | Stabiler Code             | Bedeutung                                                                                                                        | Übliche Reaktion                                                                                                                                  |
| ----- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_request`         | Die Validierung ist fehlgeschlagen oder ein Feld wird nicht unterstützt                                                          | Korrigieren Sie die Felder in `details`; wiederholen Sie die Anfrage nicht mit unveränderten Eingaben                                             |
| `400` | `invalid_json`            | Der Body ist kein JSON-Objekt oder enthält ungültiges JSON                                                                       | Serialisieren Sie genau ein gültiges JSON-Objekt                                                                                                  |
| `401` | `authentication_required` | Der Bearer-Header fehlt                                                                                                          | Hängen Sie einen serverseitigen Zugangsschlüssel an                                                                                               |
| `401` | `invalid_api_key`         | Der Schlüssel ist ungültig, abgelaufen oder widerrufen, oder sein Owner existiert nicht mehr                                     | Ersetzen oder rotieren Sie den Schlüssel                                                                                                          |
| `403` | `subscription_required`   | Der Owner hat keinen aktiven kostenpflichtigen Tarif                                                                             | Stellen Sie das Abonnement wieder her, bevor Sie es erneut versuchen                                                                              |
| `403` | `insufficient_scope`      | Dem Zugangsschlüssel fehlt der Scope der Operation                                                                               | Erstellen Sie einen Ersatzschlüssel mit minimalen Berechtigungen                                                                                  |
| `403` | `account_paused`          | Der API-Zugriff für das Konto ist pausiert                                                                                       | Setzen Sie den API-Zugriff fort oder wenden Sie sich an den Kontoinhaber                                                                          |
| `404` | `not_found`               | Endpunkt oder eigene Ressource wurde nicht gefunden                                                                              | Prüfen Sie den Pfad und die zum Mandanten gehörende ID                                                                                            |
| `409` | `conflict`                | Der aktuelle Zustand der Ressource verhindert die Aktion                                                                         | Lesen Sie den aktuellen Zustand, bevor Sie es erneut versuchen                                                                                    |
| `413` | `payload_too_large`       | Der JSON-Body überschreitet das Anfragelimit von 256 KB                                                                          | Senden Sie einen kleineren Body; teilen Sie große Inhalte auf mehrere Anfragen auf                                                                |
| `415` | `invalid_request`         | Der Body der Mutation ist nicht `application/json`                                                                               | Senden Sie `Content-Type: application/json`                                                                                                       |
| `429` | `rate_limit_exceeded`     | Das Ein-Minuten-Kontingent des Tarifs für den Schlüssel ist aufgebraucht                                                         | Warten Sie die Zeit aus `Retry-After` ab und wenden Sie Jitter an                                                                                 |
| `500` | `internal_error`          | Die Anfrage konnte nicht abgeschlossen werden                                                                                    | Wiederholen Sie sichere oder idempotente Operationen und melden Sie die Request-ID                                                                |
| `503` | `outcome_unknown`         | Eine Mutation wurde möglicherweise abgeschlossen, aber ihr Ergebnis konnte nicht erfasst werden; `details.retryable` ist `false` | Nicht wiederholen. Lesen Sie die Ressource, um zu prüfen, ob die Änderung erfolgt ist; derselbe Idempotency-Key liefert weiterhin dieses Ergebnis |

Ressourcen außerhalb des Kontos des Zugangsschlüssel-Owners können `404` zurückgeben, damit nicht offengelegt wird, ob die ID eines anderen Mandanten existiert.

## Validierungsdetails [#validierungsdetails]

Die Feldvalidierung gibt Pfade zurück, die Sie neben Ihren eigenen Formularfeldern anzeigen können:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}
```

Bodys von Mutationen müssen JSON-Objekte sein. Arrays, leere Bodys, Formulardaten und JSON, das mit einem Text-Content-Type gesendet wird, werden abgelehnt.

## Entscheidungen zu Wiederholungen [#entscheidungen-zu-wiederholungen]

* Wiederholen Sie `429` nach der in `Retry-After` angegebenen Anzahl von Sekunden.
* Wiederholen Sie `500` nur bei sicheren Lesevorgängen oder bei Schreibvorgängen, die mit demselben `Idempotency-Key` geschützt sind.
* Wiederholen Sie das `409` der laufenden Idempotenzprüfung nach dem Header `Retry-After: 2`.
* Wiederholen Sie `503 outcome_unknown` niemals blind. Prüfen Sie zuerst die Ressource; verwenden Sie einen neuen Idempotency-Key erst, nachdem Sie bestätigt haben, dass die Änderung nicht erfolgt ist.
* Wiederholen Sie `400`, `401`, `403`, `404`, `413` oder einen Zustandskonflikt nicht, bevor sich die Ursache geändert hat.

Informationen zum Backoff-Verhalten finden Sie unter [Rate limits](/de/docs/api/rate-limits), den erforderlichen Scope für jede Operation unter [API reference](/de/docs/api/reference).

---

# SDK-Status

Source: /de/docs/api/sdks.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;REST verfügbar&#x22;, icon: &#x22;globe&#x22; }, { label: &#x22;OpenAPI&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;SDK-Preview&#x22;, icon: &#x22;bolt&#x22; }]" />

Die versionierte REST API ist derzeit die unterstützte öffentliche Integrationsschnittstelle. Der Quellcode für JavaScript-, Python- und Framework-Clients liegt im Produkt-Repository vor, die Pakete sind aber aktuell weder auf npm noch auf PyPI veröffentlicht.

## Verfügbarkeit [#verfügbarkeit]

| Client                          | Status                                 | Verwendung                                                                                                     |
| ------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| REST über HTTPS                 | **Verfügbar**                          | Rufen Sie `https://makeagent.fast/api/v1` von einem beliebigen serverseitigen HTTP-Client aus auf              |
| OpenAPI-Dokument                | **Verfügbar**                          | Laden Sie [/api/openapi.json](/api/openapi.json) herunter und prüfen Sie es, bevor Sie einen Client generieren |
| `@make-agent-fast/sdk`          | **Quellcode-Preview – nicht auf npm**  | Fügen Sie diesen Import erst dann zu einem Produktivprojekt hinzu, wenn hier ein Registry-Release verlinkt ist |
| Python-Paket `makeagentfast`    | **Quellcode-Preview – nicht auf PyPI** | Verwenden Sie `requests`, `httpx` oder die Python-Standardbibliothek, bis hier ein PyPI-Release verlinkt ist   |
| React-, Vue- und Svelte-Adapter | **Quellcode-Preview – nicht auf npm**  | Verwenden Sie bevorzugt das dokumentierte Script-Loader-Muster für das jeweilige Framework                     |
| Web Component                   | **Quellcode-Preview – nicht auf npm**  | Verwenden Sie bevorzugt den Standard-Loader `embed.js`                                                         |

<Callout title="Ein Quellcode-Ordner ist kein Paket-Release" tone="warning">
  Führen Sie `npm install @make-agent-fast/sdk` oder `pip install makeagentfast` nicht allein auf Grundlage eines Import-Beispiels aus. Diese Seite enthält die Registry-URL, die Version, Hinweise zur Integritätsprüfung und den Installationsbefehl, sobald ein öffentliches Paket veröffentlicht wird.
</Callout>

## JavaScript ohne SDK [#javascript-ohne-sdk]

```ts
const response = await fetch("https://makeagent.fast/api/v1/sites?limit=100", {
  headers: {
    Authorization: `Bearer ${process.env.MAF_API_KEY}`,
    Accept: "application/json",
  },
});

const body = await response.json();
if (!response.ok) {
  console.error(body.error.code, body.error.request_id);
  throw new Error(`Make Agent Fast request failed (${response.status})`);
}

for (const site of body.data) console.log(site.id, site.title);
```

Bewahren Sie den API-Schlüssel ausschließlich auf dem Server auf. Ein Browser-Bundle mit React, Vue oder Svelte sollte Ihr eigenes Backend aufrufen oder den öffentlichen Embed-Loader einbinden; es sollte die Management-API nicht mit einem Secret aufrufen.

## Python ohne SDK [#python-ohne-sdk]

```python
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://makeagent.fast/api/v1/sites?limit=100",
    headers={
        "Authorization": f"Bearer {os.environ['MAF_API_KEY']}",
        "Accept": "application/json",
    },
)

with urllib.request.urlopen(request, timeout=20) as response:
    payload = json.load(response)

for site in payload["data"]:
    print(site["id"], site["title"])
```

Fangen Sie in der Produktion `urllib.error.HTTPError` ab und werten Sie den JSON-Body mit dem [stabilen Fehler-Envelope](/de/docs/api/scopes-errors) aus.

## Generierte Clients [#generierte-clients]

Die Generierung aus OpenAPI ist nur dann sinnvoll, wenn das Dokument die Operationen und Schemas enthält, auf die Ihre Anwendung angewiesen ist. Fixieren Sie die heruntergeladene Spezifikation, generieren Sie in ein überprüfbares Verzeichnis und prüfen Sie vor jedem Upgrade jeden Diff.

```bash
curl --fail-with-body https://makeagent.fast/api/openapi.json \
  --output make-agent-fast.openapi.json
```

Generieren und deployen Sie einen Client nicht automatisch von der Live-URL aus neu. Ein neues, additives Feld sollte einen Client nicht beschädigen, aber das Verhalten des Generators und die generierten Methodennamen können sich dennoch ändern.

## Was ein öffentlicher SDK-Release enthalten muss [#was-ein-öffentlicher-sdk-release-enthalten-muss]

Bevor ein Preview-Client als verfügbar gekennzeichnet wird, muss er Folgendes bieten:

* Eine öffentliche Registry-Seite und eine unveränderliche semantische Version.
* Anleitungen zu Installation, Upgrade und unterstützten Laufzeitumgebungen.
* Typisierte Request- und Response-Modelle, die aus dem vollständigen API-Vertrag generiert wurden.
* Strukturierte Fehler, die den HTTP-Status und die Request-ID beibehalten.
* Paginierungs-Helfer, die Cursor als opak behandeln.
* Explizite Unterstützung von Idempotency-Keys für Mutationen.
* CI-Tests gegen den aktuellen `/api/v1`-Vertrag und ein veröffentlichtes Changelog.

Solange diese Bedingungen nicht erfüllt sind, verwenden Sie die REST-Beispiele im [API-Schnellstart](/de/docs/api/quickstart) und in den [API-Rezepten](/de/docs/api/recipes).

---

# Webhooks

Source: /de/docs/api/webhooks.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;HMAC-SHA256&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Mindestens einmal&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;8 Versuche&#x22;, icon: &#x22;layers&#x22; }]" />

Developer-Webhooks senden Ereignisse Ihres Kontos an Ihren Server, sodass Sie keine Abfragen (Polling) durchführen müssen. Die Zustellung erfolgt mindestens einmal: Ereignisse können doppelt, verzögert oder in falscher Reihenfolge eintreffen.

## Endpunkt registrieren [#endpunkt-registrieren]

Erstellen Sie einen Schlüssel mit `webhooks:write` und registrieren Sie anschließend einen öffentlichen HTTPS-Empfänger sowie die kleinstmögliche Menge an Ereignissen, die Sie benötigen.

```bash
curl --fail-with-body https://makeagent.fast/api/v1/webhook-endpoints \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-production-v1" \
  -d '{
    "url": "https://api.example.com/webhooks/make-agent-fast",
    "events": ["lead.created", "conversation.started"]
  }'
```

Die URL muss HTTPS verwenden, darf keinen Benutzernamen, kein Passwort, kein Fragment und keinen benutzerdefinierten Port enthalten und muss ausschließlich zu öffentlichen IP-Adressen aufgelöst werden. Weiterleitungen werden bei der Zustellung nicht verfolgt.

Die `201`-Antwort zeigt ein Signing Secret im Format `whsec_...` nur einmal an. Speichern Sie es im Secret Manager des Empfängers, bevor Sie die Antwort schließen. Wenn Sie Endpunkte später auflisten, werden URL, Ereignisse, Status, letzte Zustellung und letzter Fehler zurückgegeben – jedoch nicht das Secret.

## Ereignistypen [#ereignistypen]

| Ereignis                       | Wird ausgelöst, wenn                                                                                |
| ------------------------------ | --------------------------------------------------------------------------------------------------- |
| `site.published`               | Eine Website veröffentlicht wird                                                                    |
| `site.unpublished`             | Eine Website in den Entwurfsstatus zurückversetzt wird                                              |
| `lead.created`                 | Der Agent einen neuen Lead erfasst                                                                  |
| `lead.qualified`               | Der Agent einen Lead qualifiziert oder ein Lead in die Vertriebspipeline aufgenommen wird           |
| `booking.requested`            | Ein Besucher einen Termin anfragt oder bucht                                                        |
| `handoff.requested`            | Der Agent eine Konversation an eine Person übergibt (Handoff)                                       |
| `opportunity.created`          | Ein Lead zu einer Opportunity in der Pipeline wird                                                  |
| `opportunity.updated`          | Sich Zuweisung, Wert, nächste Aktion oder andere Felder einer Opportunity ändern                    |
| `opportunity.stage_changed`    | Eine Opportunity in eine andere Phase wechselt                                                      |
| `opportunity.won`              | Eine Opportunity als gewonnen abgeschlossen wird                                                    |
| `opportunity.lost`             | Eine Opportunity als verloren abgeschlossen wird                                                    |
| `conversation.started`         | Ein neuer Konversationsverlauf beginnt                                                              |
| `conversation.message.created` | Einer Konversation eine Nachricht hinzugefügt wird                                                  |
| `knowledge.ready`              | Eine Wissensquelle die Verarbeitung abgeschlossen hat                                               |
| `broadcast.sent`               | Ein Broadcast seinen Versandablauf abgeschlossen hat                                                |
| `domain.activated`             | Eingestellt – benutzerdefinierte Domains werden nicht angeboten; dieses Ereignis wird nie ausgelöst |

## Anfrageformat [#anfrageformat]

Make Agent Fast sendet `POST` mit `Content-Type: application/json`, `User-Agent: MakeAgentFast-Webhooks/1.0` und diesen Headern:

```http
maf-event-id: evt_...
maf-event-type: lead.created
maf-signature: t=1784210566,v1=HEX_HMAC_SHA256
```

Der JSON-Body hat eine stabile Hülle (Envelope). Die Felder innerhalb von `data` hängen vom Ereignis ab und können um zusätzliche Felder erweitert werden.

```json
{
  "id": "evt_2c34...",
  "type": "lead.created",
  "created_at": "2026-07-16T10:02:46.000Z",
  "data": {
    "site_id": "SITE_ID",
    "lead_id": "LEAD_ID"
  }
}
```

Verwenden Sie die `id` aus dem Body oder `maf-event-id` als Schlüssel zur Deduplizierung. Verwenden Sie weder den Zustellzeitpunkt noch eine generierte Datenbank-ID.

## Signatur in Node.js überprüfen [#signatur-in-nodejs-überprüfen]

Lesen Sie die exakten Rohbytes, bevor Sie das JSON parsen. Der signierte Wert ist `TIMESTAMP + "." + RAW_BODY`.

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody: Buffer, header: string, secret: string) {
  const values = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const timestamp = values.t;
  const supplied = values.v1;
  if (!timestamp || !supplied || !/^[a-f0-9]{64}$/.test(supplied)) return false;

  const age = Math.abs(Date.now() / 1_000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(supplied, "hex"));
}
```

Weisen Sie fehlerhafte Signaturen sowie Zeitstempel zurück, die älter sind als Ihr akzeptiertes Replay-Fenster; fünf Minuten sind ein sinnvoller Standardwert. Vergleichen Sie Bytes fester Länge in konstanter Zeit.

## Signatur in Python überprüfen [#signatur-in-python-überprüfen]

```python
import hashlib
import hmac
import time

def verify_webhook(raw_body: bytes, header: str, secret: str) -> bool:
    values = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    timestamp = values.get("t", "")
    supplied = values.get("v1", "")
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
    except ValueError:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, supplied)
```

Parsen und verarbeiten Sie das JSON erst, nachdem die Signaturprüfung erfolgreich war.

## Bestätigen und verarbeiten [#bestätigen-und-verarbeiten]

1. Überprüfen Sie Signatur und Zeitstempel.
2. Fügen Sie die Ereignis-ID in eine Tabelle mit einer Unique-Constraint ein.
3. Existiert sie bereits, geben Sie `204` zurück, ohne den Seiteneffekt zu wiederholen.
4. Committen Sie das Ereignis oder stellen Sie Ihren internen Job in die Warteschlange.
5. Geben Sie zügig eine `2xx`-Antwort zurück.

Der Sender von Make Agent Fast bricht nach 10 Sekunden mit einem Timeout ab. Nur `2xx` gilt als erfolgreich, und Weiterleitungen werden nicht verfolgt.

## Wiederholungsverhalten [#wiederholungsverhalten]

Fehlgeschlagene Zustellungen werden für bis zu acht Versuche in die Warteschlange gestellt. Das Backoff beginnt bei etwa zwei Sekunden, verdoppelt sich mit Jitter und ist auf eine Stunde begrenzt; der tatsächliche Zustellzeitpunkt kann später liegen, wenn die Worker ausgelastet sind. Da Wiederholungen die auslösende Anfrage überdauern und in falscher Reihenfolge eintreffen können, sollten Sie sich nie darauf verlassen, dass ein Ereignis unmittelbar vor einem anderen eintrifft.

Geben Sie nur dann eine Nicht-2xx-Antwort zurück, wenn Make Agent Fast die Zustellung wiederholen soll. Bei einer dauerhaft nicht unterstützten Ereignisversion oder einem gelöschten Ziel sollten Sie das Ereignis akzeptieren und protokollieren oder den Endpunkt entfernen, anstatt endlose temporäre Fehler zu erzeugen.

## Signing Secret rotieren [#signing-secret-rotieren]

Signing Secrets können weder erneut angezeigt noch bearbeitet werden. So rotieren Sie sicher:

1. Erstellen Sie einen zweiten Endpunkt, der auf einen temporären oder versionierten Empfängerpfad verweist.
2. Speichern Sie das dabei neu angezeigte Secret.
3. Akzeptieren und deduplizieren Sie Ereignisse von beiden Endpunkten.
4. Prüfen Sie, ob der neue Endpunkt gültige Zustellungen erhält.
5. Löschen Sie den alten Endpunkt mit `DELETE /webhook-endpoints/{endpoint_id}`.

Bleibt die Empfänger-URL gleich, sorgen Sie dafür, dass die empfangende Anwendung während der Überlappung beide Secrets akzeptiert, und verwenden Sie Ereignis-IDs, um doppelte Seiteneffekte zu vermeiden.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                       | Prüfen                                                                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Keine Zustellungen            | Endpunktstatus, ausgewählte Ereignisse, öffentliches DNS, HTTPS-Zertifikat und ob das Ereignis tatsächlich eingetreten ist      |
| Signatur stimmt nicht überein | Zugriff auf den Rohbody, exakte Verkettung `timestamp.body`, korrektes Secret des Endpunkts und Body-Veränderungen durch Proxys |
| Wiederholte Zustellungen      | Rückgabecode, 10-Sekunden-Timeout, interne Ausnahmen und Eindeutigkeit der Ereignis-ID                                          |
| Fehler bei privaten Adressen  | DNS-Einträge dürfen ausschließlich zu öffentlichen Adressen aufgelöst werden; localhost und interne Bereiche werden abgelehnt   |
| Fehler bei Weiterleitung      | Registrieren Sie direkt die finale HTTPS-URL; Weiterleitungen werden nicht verfolgt                                             |

Fügen Sie einer Support-Nachricht niemals das Signing Secret, den Bearer-Schlüssel oder die vollständigen Besucherdaten bei. Geben Sie stattdessen die Endpunkt-ID, die Ereignis-ID, den Zeitpunkt des Fehlers und bereinigte Empfänger-Logs an.

---

# Darstellung

Source: /de/docs/build/appearance.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Theme&#x22;, icon: &#x22;spark&#x22; }, { label: &#x22;Chat&#x22;, icon: &#x22;chat&#x22; }, { label: &#x22;Live-Anruf&#x22;, icon: &#x22;voice&#x22; }]" />

Das Erscheinungsbild des Widgets gestaltet den **Chat** und den **Live-Anruf** der Besucher gemeinsam – Farben, Theme, Ecken, Schatten, Glaseffekt und Schriftarten. Eine gehostete Marketingseite wird dadurch nicht erstellt. Neue Agents gehen als Embed auf Ihrer bestehenden Website live.

Öffnen Sie die Seite **Agent** des Agents und wählen Sie den Tab **Darstellung**. Jede Einstellung gilt für beide Oberflächen, und die Live-Vorschau neben dem Tab zeigt das echte Widget.

<TutorialVideo episode="ep02" start="108" />

## Änderungen gehen automatisch live [#änderungen-gehen-automatisch-live]

Es gibt keine Schaltfläche „Speichern“. Texte und Schieberegler werden nach einer kurzen Pause gespeichert; Schalter, Voreinstellungen und Auswahlfelder werden sofort gespeichert, und neben dem Steuerelement erscheint ein Hinweis **Gespeichert**. Jeder Speichervorgang aktualisiert den Agent und lädt das Embed (sowie eine eventuell noch vorhandene gehostete Seite) neu, sodass Besucher die Änderung sehen, ohne dass Sie erneut veröffentlichen müssen. Prüfen Sie das Ergebnis in einem privaten Fenster auf einem echten Embed.

Das Ein- und Ausblenden des Badges bei Operate und Scale nutzt dieselbe Live-Aktualisierung.

## Website übernehmen vs. Hell oder Dunkel [#website-übernehmen-vs-hell-oder-dunkel]

Für das **Agent-Theme** stehen drei Optionen zur Auswahl:

| Auswahl                | Wirkung                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Website übernehmen** | Folgt dem hellen oder dunklen Modus des jeweiligen Besuchers (zuerst die Host-Seite, dann das Betriebssystem). Standard. |
| **Hell**               | Legt Chat und Live-Anruf fest auf die helle Palette fest.                                                                |
| **Dunkel**             | Legt Chat und Live-Anruf fest auf die dunkle Palette fest.                                                               |

**Website übernehmen** entspricht `auto`. Ein festes Hell oder Dunkel gilt für Chat und Live-Anruf bei jedem Besucher. Bearbeiten Sie die helle und die dunkle Palette getrennt; der Schalter in der Vorschau ändert nur, welche Palette Sie gerade bearbeiten.

Bei einem Embed kann der Loader weiterhin `data-theme="light"` oder `data-theme="dark"` als Überschreibung der Host-Seite übergeben. Siehe [Embed-Übersicht](/de/docs/embed/overview).

## Farben, Voreinstellungen und Schrift [#farben-voreinstellungen-und-schrift]

* **Voreinstellungen** – Sharp, Soft, Glass, Minimal – legen Ecken, Schatten, Rahmen und Glaseffekt gemeinsam fest.
* **Primärfarbe** – Besucherblasen, Akzente im Anruf und Hauptaktionen. **Auto (Website-Akzent)** übernimmt den Akzent der erfassten Marke, der für das Widget verwendet wird.
* Passen Sie Sekundärfarbe, Hintergrund, Panel-Oberfläche, Ecken, Schatten, Rahmen, Glaseffekt und Schriftart individuell an.
* **Website angleichen** bei der Schriftart greift, wenn der Agent auf einer externen Website eingebettet ist; **Widget-Standard** behält die Schriftart des Widgets bei.

Sorgen Sie für ausreichenden Kontrast und achten Sie darauf, dass interaktive Zustände unterscheidbar bleiben. Prüfen Sie die Vorschau in Desktop- und schmalen Breiten, auch mit koreanischen und englischen Beschriftungen.

## Live-Gespräch in der Vorschau der Darstellung [#live-gespräch-in-der-vorschau-der-darstellung]

Die Vorschau neben dem Tab **Darstellung** zeigt das echte Widget. Chat und Live-Anruf erscheinen daher mit der gewählten hellen oder dunklen Palette und derselben Besucheroberfläche wie im Embed. Ein Gespräch mit dem Agent an dieser Stelle ist weiterhin ein Test durch den Owner – siehe [Sprache und Live-Anrufe](/de/docs/build/voice).

## Branding-Badge [#branding-badge]

Das Entfernen des Badges ist bei Operate und Scale verfügbar. Launch-Websites behalten das Empfehlungs-Badge von Make Agent Fast. Wenn Sie die Badge-Einstellung (**„Made with“-Badge anzeigen**) ändern, wird ebenfalls das Live-Embed aktualisiert, ohne dass Sie erneut veröffentlichen müssen.

---

# Buchung mit Cal.com

Source: /de/docs/build/cal-com.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/build/change-actions&#x22;, label: &#x22;Bestätigungen und Belege&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/operate/conversations&#x22;, label: &#x22;Konversationen&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Kalender verbinden [#kalender-verbinden]

Öffnen Sie **Agent → Aktionen → Cal.com**. Geben Sie einen Cal.com-API-Schlüssel ein, der mit `cal_` beginnt, die positive numerische Termintyp-ID und eine IANA-Zeitzone wie `Asia/Seoul`. Wählen Sie **Verbindung speichern**. Jeder Agent hat seine eigene Verbindung. Der Schlüssel wird auf dem Server verschlüsselt; das Dashboard zeigt nur die letzten vier Zeichen an. Lassen Sie das Schlüsselfeld beim Aktualisieren einer bestehenden Verbindung leer, um den vorhandenen Schlüssel beizubehalten.

Wählen Sie **Verbindung testen**, um mit den eingegebenen Einstellungen bis zu drei bevorstehende Zeitfenster der nächsten sieben Tage abzurufen. Dieser Test speichert die Verbindung nicht und erstellt keine Buchung. Keine Zeitfenster können einfach bedeuten, dass der Termintyp in diesem Zeitraum keine Verfügbarkeit hat. Wenn der Test fehlschlägt, prüfen Sie in Cal.com den Schlüssel, den Termintyp und den Zeitplan. Wenn Sie die Verbindung entfernen, werden keine neuen Cal.com-Buchungen mehr vorgenommen; bestehende Buchungen werden dadurch nicht storniert.

Zahlungen werden nicht unterstützt. [Google Calendar](/de/docs/build/google-calendar) ist eine separate Option, die noch nicht allgemein verfügbar ist.

## Vom Zeitfenster zur Buchung [#vom-zeitfenster-zur-buchung]

1. Der Agent ruft `find_slots` auf, um die tatsächliche zukünftige Verfügbarkeit abzufragen. Er zeigt bis zu acht Zeiten in der konfigurierten Zeitzone an. Der Standardzeitraum reicht von heute bis sieben Tage später; die maximale Zeitspanne beträgt 14 Tage. Steht nur eine einzige Zeit zur Verfügung, wird sie allein angezeigt.
2. Der Kunde wählt eine Zeit und gibt Name, E-Mail-Adresse und optional eine Notiz an. Der Agent prüft erneut, ob die Zeit frei ist und ob sie in dieser Konversation angeboten wurde. Angebote für Zeitfenster laufen nach 15 Minuten ab.
3. Eine Bestätigungskarte zeigt Datum, Uhrzeit, Zeitzone und die Angaben zum Teilnehmer. Der Kunde muss auf **Bestätigen** tippen. Eine Chatnachricht oder die bloße Auswahl einer Zeit bucht noch nichts. Der Vorschlag läuft nach 15 Minuten ab und reserviert das Zeitfenster nicht.
4. Erst nach der Bestätigung fordert der Adapter die Cal.com-Buchung an. Das Ergebnis `accepted` von Cal.com wird zu `done`, wobei die Buchungs-UID als Referenz dient. `pending` oder `awaiting_host` bleibt ausstehend; bei Ablehnung oder Stornierung wird die Buchung als fehlgeschlagen markiert.

Buchungsvorschläge sind in Messaging-Kanälen nur im privaten Chat möglich. Die Probe ruft Cal.com nicht auf und erstellt keine Buchung. Ohne Cal.com-Verbindung bleibt der bestehende Ablauf für Buchungsanfragen verfügbar; er belegt jedoch keine Kalenderreservierung. Wenn Sie Schlüssel, Termintyp oder Zeitzone ändern, wird das Ausführungsziel eines Vorschlags ungültig. Beginnen Sie daher nach Änderungen an der Verbindung von vorn.

## Wenn ein Zeitfenster vergeben ist oder das Ergebnis unklar ist [#wenn-ein-zeitfenster-vergeben-ist-oder-das-ergebnis-unklar-ist]

Ein anderer Kunde kann sich ein Zeitfenster sichern, bevor die Bestätigung abgeschlossen ist. Wenn die Zeit nicht mehr frei ist, meldet der Agent, dass sie nicht verfügbar ist; lehnt Cal.com die Buchung bei der Erstellung ab, zeigt der Beleg einen Fehlschlag an. Bitten Sie um neue Zeiten und bestätigen Sie einen neuen Vorschlag. Der Beleg über den Fehlschlag fügt nicht automatisch neue Auswahlmöglichkeiten hinzu.

Eine Zeitüberschreitung im Netzwerk ist weder ein Beweis für einen Fehlschlag noch für einen Erfolg. Der Beleg zeigt ein unbekanntes Ergebnis an, während der Dienst erneut prüft. Der Create-Endpunkt von Cal.com hat keinen dokumentierten Vertrag für Idempotenzschlüssel. Deshalb speichert der Adapter die Run-ID in `metadata.maf_run` und sucht über alle Status und Seiten hinweg nach dieser Buchung, bevor er die Erstellung erneut versucht. Eine unvollständige Suche erlaubt niemals eine weitere Create-Anfrage. Das verringert das Risiko von Duplikaten, ist aber keine vom Anbieter gestützte Exactly-once-Garantie. Prüfen Sie nach ausgeschöpften Wiederholungsversuchen Cal.com, bevor Sie eine weitere Buchung vornehmen.

Die Freigabe durch den Host in Cal.com ist von der Freigabe durch den Owner bei benutzerdefinierten Änderungsaktionen zu unterscheiden. Eine ausstehende Cal.com-Buchung wird von dieser Integration nicht automatisch aktualisiert; prüfen Sie ihren endgültigen Status in Cal.com. Das Web-Widget kann den gespeicherten Beleg des Durchlaufs abfragen, und unterstützte private Kanäle erhalten verzögerte Belege im Rahmen ihrer Servicefenster. Siehe [Zustellung von Belegen](/de/docs/build/change-actions#customer-confirmation-and-receipts).

## API-Versionen und Release-Prüfungen [#api-versionen-und-release-prüfungen]

Der Adapter sendet Bearer-Authentifizierung und die folgenden endpunktspezifischen `cal-api-version`-Werte, die am **13.10.2026** anhand der offiziellen Dokumentation überprüft wurden:

| Vorgang            | Version      | Referenz                                                                                                |
| ------------------ | ------------ | ------------------------------------------------------------------------------------------------------- |
| Zeitfenster lesen  | `2024-09-04` | [GET /v2/slots](https://cal.com/docs/api-reference/v2/slots/get-available-time-slots-for-an-event-type) |
| Buchung erstellen  | `2026-02-25` | [POST /v2/bookings](https://cal.com/docs/api-reference/v2/bookings/create-a-booking)                    |
| Buchung abgleichen | `2026-05-01` | [GET /v2/bookings](https://cal.com/docs/api-reference/v2/bookings/get-all-bookings)                     |

Testen Sie vor dem Einsatz mit Kunden eine kontrollierte Buchung, prüfen Sie die UID in Cal.com, probieren Sie ein vergebenes Zeitfenster aus und kontrollieren Sie die Belege in jedem vorgesehenen Kanal. Ein erfolgreicher Verbindungstest belegt nur das Lesen von Zeitfenstern, nicht eine echte Buchung oder die Produktionsreife.

---

# Änderungsaktionen

Source: /de/docs/build/change-actions.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/build/lookups&#x22;, label: &#x22;Schreibgeschützte Abfragen&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/build/cal-com&#x22;, label: &#x22;Cal.com-Buchung&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: &#x22;Angemeldete Kunden&#x22;, icon: &#x22;shield&#x22; }
]"
/>

<TutorialVideo episode="ep06" start="134" />

## Eine Änderung definieren [#eine-änderung-definieren]

Verwenden Sie eine Änderungsaktion, um einen Datensatz in Ihrem eigenen System zu aktualisieren, beispielsweise um eine Bestellung zu stornieren. Öffnen Sie **Agent → Aktionen**, konfigurieren Sie Ihr Agent-Secret unter **Angemeldete Kunden** und fügen Sie dann eine **Änderungsaktion** hinzu: einen eindeutigen Namen, eine Beschreibung, wann sie verwendet werden soll, einen öffentlichen HTTPS-Endpunkt und deklarierte String-Eingaben. Ein Name wie `cancel_order` wird zum Modell-Tool `change_cancel_order`. Bestehende Änderungen werden automatisch gespeichert; warten Sie auf die Speicheranzeige.

Lassen Sie **Angemeldeten Kunden erforderlich** für private Datensätze aktiviert. Ihr Endpunkt muss den angeforderten Datensatz trotzdem anhand der verifizierten Kunden-ID autorisieren. Ein im Chat eingegebener Name, eine E-Mail-Adresse oder eine Bestell-ID ist kein Identitätsnachweis. Wenn Sie diese Einstellung deaktivieren, kann `customer` null sein: Erlauben Sie dann nur Änderungen, die für anonyme Besucher geeignet sind. Zahlungen liegen außerhalb des Umfangs dieser Funktion.

## Freigabe durch den Owner wählen [#freigabe-durch-den-owner-wählen]

Die Bestätigung durch den Kunden ist in jedem Modus erforderlich:

| Modus                           | Nach der Bestätigung durch den Kunden                                                                                                                                             |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keine Freigabe (`none`)         | Ausführung ohne separate Entscheidung des Owners.                                                                                                                                 |
| Immer freigeben (`always`)      | Auf den Owner warten.                                                                                                                                                             |
| Über einem Limit (`over_limit`) | Warten, wenn eine deklarierte numerische Eingabe strikt größer als das Limit ist; bei Gleichheit ist keine Freigabe erforderlich. Ungültige numerische Eingaben werden abgelehnt. |

Prüfen Sie wartende Anfragen unter **Agent → Aktionen → Freigaben**. Der Website-Owner kann sie genehmigen oder ablehnen. Wenn private Telegram-Benachrichtigungen für den Owner verknüpft sind, enthält die Benachrichtigung zusätzlich die Schaltflächen **Genehmigen / Ablehnen**. Nur der private Chat des verknüpften Owners kann sie verwenden; abgelaufene oder wiederholte Tipps können keine erneute Ausführung auslösen. Die Freigabe läuft 24 Stunden nach der Bestätigung durch den Kunden ab. Der Kunde erhält das Ergebnis, einschließlich Ablehnung oder Ablauf. Die letzten Ausführungen zeigen Status, Zeitstempel, Referenz und Kunden-ID.

## Was Ihr Endpunkt empfängt [#was-ihr-endpunkt-empfängt]

Wenn das Modell die Änderung vorschlägt, wird keine Anfrage gesendet. Nach der Bestätigung durch den Kunden und einer eventuell erforderlichen Freigabe durch den Owner sendet Make Agent Fast Folgendes:

```http
POST /agent/cancel-order HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
x-maf-idempotency-key: c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b
```

```json
{
  "version": 1,
  "action": "cancel_order",
  "runId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}
```

`action` enthält das Präfix `change_` nicht. Beide IDs und der Idempotenz-Header bleiben bei Wiederholungen gleich. `input` enthält nur deklarierte, getrimmte Strings; `customer` ist null oder das verifizierte Objekt mit `id` und optional `email`/`name`.

Verwenden Sie den [Signaturprüfer für Abfragen](/de/docs/build/lookups#verify-the-signature): HMAC-SHA256 mit Ihrem Agent-Secret über `"maf-webhook-v1:" + timestamp + "." + rawBody`, in Kleinbuchstaben-Hex mit dem Präfix `v1=`. Prüfen Sie vor dem Schreiben die ursprünglichen Bytes, die Aktualität des Zeitstempels, die erwartete Site bzw. Aktion und die Zugehörigkeit des Datensatzes zum Kunden. **Deduplizieren Sie `x-maf-idempotency-key` atomar zusammen mit Ihrer Änderung und speichern Sie das Ergebnis.** Eine wiederholte Anfrage muss das gespeicherte Ergebnis zurückgeben, ohne den Datensatz erneut zu ändern. Die Sperrmechanismen der Plattform können die Deduplizierung in Ihrem System nicht ersetzen.

## Ein Ergebnis zurückgeben [#ein-ergebnis-zurückgeben]

Geben Sie 2xx-JSON mit dem erforderlichen Feld `status` (`done`, `pending` oder `failed`) und den optionalen Feldern `message`, `reference` und `card` zurück:

```json
{
  "status": "done",
  "message": "Order cancelled.",
  "reference": "A128",
  "card": {
    "kind": "status",
    "title": "Order A128",
    "fields": [{ "label": "Order", "value": "A128" }]
  }
}
```

Die optionale Statuskarte erfordert `title` und `fields`; `kind: "status"` ist optional. Sie unterstützt `status: { label, tone }`, `reference`, `asOf` und `link: { label, url }`, wie bei [Abfragen](/de/docs/build/lookups#return-a-response). Mögliche Tonalitäten sind `neutral`, `success`, `warning` oder `danger`; Links müssen sichere HTTPS-URLs sein. Unbekannte Schemafelder werden abgelehnt. Halten Sie Texte kurz und schlicht. Das äußere `status` bestimmt das Ergebnis; die Formulierung der Karte kann ein ausstehendes Ergebnis nicht in einen Erfolg verwandeln.

Verwenden Sie `done` erst, wenn die Änderung abgeschlossen ist, `pending`, wenn sie noch in Bearbeitung ist, und `failed` bei einem bekannten Fehler. Zeitüberschreitungen, Netzwerkfehler, 5xx-Antworten und ungültige Antworten gelten als ungewiss (`unknown`). Der Abgleich versucht es nach einer Minute und dann nach fünf Minuten erneut, mit höchstens drei Ausführungsversuchen und demselben Schlüssel; die Warteschlangenplanung kann diese Zeiten verzögern. HTTP 4xx schlägt ohne Wiederholung fehl. Bei erschöpfter Ungewissheit schlägt die Ausführung fehl und der Owner wird benachrichtigt; das beweist jedoch nicht, dass Ihr System keine Änderung vorgenommen hat. Prüfen Sie den Vorgang, bevor Sie eine weitere Ausführung starten. `pending` löst keine weitere Ausführung aus.

## Einen signierten finalen Callback senden [#einen-signierten-finalen-callback-senden]

Sobald ein `pending`- oder `unknown`-Lauf geklärt ist, senden Sie per POST eine finale Antwort an `https://makeagent.fast/api/agent/actions/RUN_ID/callback`. Senden Sie denselben Antwortvertrag mit `status: "done"` oder `"failed"`; `pending` wird hier nicht akzeptiert.

Callback-Vertrag aktualisiert am 2026-10-14: Signieren Sie `maf-callback-v1:` + runId + `:` + timestamp + `.` + rawBody. Wenn der Body `runId` enthält, muss es mit der Run-ID im Pfad übereinstimmen; bei Abweichung wird 400 zurückgegeben. Signaturen für einen anderen Lauf oder im vorherigen ungebundenen Format liefern 403.

```js
import { createHmac } from "node:crypto";

const body = JSON.stringify({ status: "done", reference: "A128" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", agentSecret)
  .update(`maf-callback-v1:${runId}:${timestamp}.${body}`)
  .digest("hex");
const response = await fetch(
  `https://makeagent.fast/api/agent/actions/${encodeURIComponent(runId)}/callback`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-maf-timestamp": timestamp,
      "x-maf-signature": `v1=${signature}`,
    },
    body,
  },
);
```

Verwenden Sie Ihr serverseitig gespeichertes Agent-Secret und die Run-ID aus der ursprünglichen Anfrage. Der Callback verwendet **`maf-callback-v1:`**, nicht den Namensraum der ausgehenden Anfrage. Die Zeitabweichung muss innerhalb von fünf Minuten liegen. Ungültige Signaturen liefern 403, ungültige Bodys 400; ein bereits abgeschlossener oder inkompatibler Lauf liefert 409. Ein wiederholter Callback überschreibt das Endergebnis nicht. Rotieren Sie dieses Secret zusammen mit Ihrer Identitäts- und Endpunkt-Signaturkonfiguration.

## Kundenbestätigung und Belege [#kundenbestätigung-und-belege]

Der Kunde prüft die exakten Eingaben und tippt im Vorschlag auf **Bestätigen** oder **Abbrechen**. Ein Vorschlag läuft nach 15 Minuten ab; ein neuer Vorschlag für dieselbe Aktion bzw. Unterhaltung ersetzt den alten. Die Bestätigung verwendet ein Token, das an diesen Lauf, diese Site und diesen Besucher gebunden ist. Die Eingabe von „Ja“ oder ein Klick auf eine generische Bestätigungskarte autorisiert die Änderung nicht. Schaltflächen in der Probe sind inaktiv und rufen Ihren Endpunkt nicht auf.

Im Web fragt das geöffnete Widget nicht abgeschlossene Belege ab, zunächst alle fünf Sekunden und danach alle 30 Sekunden, bis zu 24 Stunden lang. Ein Beleg kann folgende Zustände anzeigen: angefordert, wartet auf Owner, läuft, ausstehend, unbekanntes Ergebnis wird geprüft, erledigt, fehlgeschlagen, abgelehnt, abgebrochen oder abgelaufen. Nur `done` bestätigt den Abschluss.

Vorschläge in Channels funktionieren **nur in privaten Chats**, nie in Gruppen oder Kanälen. Verzögerte Belege nutzen die dauerhafte Outbox: Gewöhnliche Telegram-Bot-DMs werden unterstützt; WhatsApp, Messenger, Instagram und Telegram Business erfordern eine erfasste eingehende Nachricht innerhalb von 24 Stunden, die beim Senden erneut geprüft wird. Verzögerte Zustellung ist für Telegram-Gastanfragen, Discord und KakaoTalk nicht verfügbar. Geschlossene Zeitfenster und deaktivierte Verbindungen können die Zustellung verhindern; der Ausführungsverlauf erfasst das Ergebnis dennoch.

## Limits und Tests [#limits-und-tests]

| Element                                              | Limit                                                                                                              |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Änderungsaktionen                                    | 5 pro Agent; Namen sind über Änderungen und Abfragen hinweg eindeutig                                              |
| Namen                                                | Aktion: `^[a-z][a-z0-9_]{2,39}$`; Eingabe: `^[a-z][a-z0-9_]{1,31}$`; reservierte Aktionsnamen sind nicht verfügbar |
| Beschreibungen                                       | 300 Zeichen                                                                                                        |
| Eingaben                                             | 3 deklarierte Strings, jeweils höchstens 200 Zeichen                                                               |
| Endpunkt                                             | Öffentliches HTTPS, bis zu 500 Zeichen, keine URL-Zugangsdaten, keine privaten Adressen, keine Weiterleitungen     |
| Ausführungs-Timeout / Antwort / Callback-Body        | 8 Sekunden / 32 KiB / 32 KiB                                                                                       |
| Statuskarte: Titel / Feldbezeichnung / Wert / Felder | 80 / 40 / 200 Zeichen / 8 Felder                                                                                   |
| Ablauf von Vorschlag / Freigabe                      | 15 Minuten / 24 Stunden nach der Bestätigung                                                                       |

Verwenden Sie einen kontrollierten Endpunkt, um Bestätigung, Abbruch, Freigabe, Timeout, die Behandlung doppelter Schlüssel und finale Callbacks zu prüfen. Kontrollieren Sie dessen Datensätze, nicht nur den Belegtext. Die Probe beweist, dass kein externer Schreibzugriff erfolgt; sie ist kein Test der Endpunktausführung. Testen Sie jeden vorgesehenen privaten Channel, bevor Sie sich auf Belege verlassen.

---

# Agent erstellen

Source: /de/docs/build/create-agent.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/build/persona&#x22;, label: &#x22;Persona&#x22;, icon: &#x22;account&#x22; },
{ href: &#x22;/de/docs/build/knowledge&#x22;, label: &#x22;Wissen&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/build/voice&#x22;, label: &#x22;Stimme&#x22;, icon: &#x22;voice&#x22; },
{ href: &#x22;/de/docs/build/appearance&#x22;, label: &#x22;Look&#x22;, icon: &#x22;spark&#x22; }
]"
/>

Der erste Agent entsteht aus einer **Website-URL**. Wir durchsuchen die öffentlichen Seiten, die wir erreichen können, erstellen daraus einen Agent-Entwurf (einschließlich des Widget-Stils auf Basis dieser Fakten) und halten ihn bis zum letzten Onboarding-Schritt von Ihrer Website fern. Chat-to-Build ist deaktiviert. Es gibt keine Funktion zum Generieren einer Website und keinen Section-Builder.

<TutorialVideo episode="ep01" start="14" />

## URL einfügen [#url-einfügen]

Fügen Sie auf der Startseite die URL ein und fahren Sie fort. Bei der Registrierung und beim Login bleibt `next=/onboarding/launch?url=…` erhalten, sodass Sie die URL nicht erneut einfügen müssen. Über `/try` können Besucher eine URL einfügen und mit einem Entwurf mit Wasserzeichen chatten (nur Text, begrenzt), bevor sie ihn bei der Registrierung übernehmen.

Wenn Sie bereits Websites haben, erzeugt eine eingefügte URL dennoch einen **neuen**, unveröffentlichten Entwurf. Dieselbe URL, die bereits in Bearbeitung ist, wird fortgesetzt statt dupliziert. Eine abgeschlossene Erstwebsite wird nicht wiederverwendet.

Fügen Sie keine Passwörter, privaten Kundendaten oder Connector-Tokens in das URL-Feld ein.

## Auf dem Generierungsbildschirm warten [#auf-dem-generierungsbildschirm-warten]

Während der Entwurf erstellt wird, zeigt der Generierungsbildschirm den tatsächlichen Fortschritt von Einlesen, Zusammenstellung und Prüfung – keinen Schein-Spinner:

| Schritt                       | Was passiert                                                           |
| ----------------------------- | ---------------------------------------------------------------------- |
| **Website wird gelesen**      | Ruft öffentliche Seiten der URL ab                                     |
| **Agent wird erstellt**       | Stellt den Agent und den Widget-Stil aus den erfassten Fakten zusammen |
| **Antworten werden getestet** | Führt einen Selbsttest anhand dieses Wissens durch                     |

Die typische Wartezeit beträgt einige Sekunden; bei einer größeren Website kann es bis zu etwa einer Minute dauern. Ist das Crawling dürftig, nutzt der Entwurf trotzdem alles, was gefunden wurde. Nach der Prüfung können Sie Quellen hinzufügen.

Der Entwurf wird nie automatisch veröffentlicht. Neue Agents erhalten keine gehostete Marketing-Seite.

## Den Agent kennenlernen und live schalten [#den-agent-kennenlernen-und-live-schalten]

Nachdem der Entwurf erstellt wurde, zeigt das Onboarding zwei weitere Bildschirme:

* **Lernen Sie Ihren Agent kennen** – der echte Chat neben drei kurzen Prüfungen. Stellen Sie eine Frage, lesen Sie die Antwort und übernehmen oder korrigieren Sie sie. Die Textprobe verbraucht Credits; Kontaktanfragen und Aktionen werden simuliert.
* **Dort platzieren, wo Ihre Kunden sind** – der letzte Schritt. Er schaltet das Website-Widget für die eingefügte Website ein und aktiviert den **Agent-Link** (eine öffentliche Chat-Seite unter der eigenen Adresse Ihres Agents), damit Sie unter **Auf dem Smartphone testen** auf Ihrem Smartphone testen können. Fügen Sie den Installationscode in Ihre Website ein und klicken Sie dann auf **Meine Website prüfen**.

Anschließend öffnet sich der Agent auf seiner Seite **Agent**, dem ersten Eintrag in der Seitenleiste des Agents: die Tabs **Übersicht**, **Darstellung**, **Stimme** und **Aktionen** neben einer Live-Ansicht, die das echte Widget in der von Ihnen gewählten Ecke zeigt. Stellen Sie ihm genau dort die Fragen, die ein Kunde stellen würde. Unter **Übersicht** bewertet **Antwortprüfung** → **Prüfung starten** die Antworten anhand Ihres Wissens.

Das Gespräch mit dem Agent im Dashboard ist ein Test durch den Owner. Es geht nicht live und zählt nicht zur Aktivierung.

Um das Widget später auf Ihrer Website zu platzieren, öffnen Sie auf der Agent-Seite **Live schalten** → **Website-Widget**. Falls das Widget noch nicht aktiv ist, wählen Sie **Einbettung aktivieren**. Sobald es aktiv ist, zeigt dasselbe Fenster den Installationscode, den Schalter **Auf meiner Website anzeigen** und **Erlaubte Website-Adressen**. Sie können das Widget jederzeit mit diesem Schalter oder über die Karte **Auf Ihrer Website** im Tab **Übersicht** ausblenden.

## Aktivierung [#aktivierung]

Nachdem Sie live sind, fügen Sie die Einbettung hinzu oder verbinden einen Channel. Die Website gilt als **aktiviert**, sobald das erste Besuchergespräch stattfindet oder der erste Lead erfasst wird. Testgespräche im Dashboard zählen nie.

## Nach dem ersten Entwurf bearbeiten [#nach-dem-ersten-entwurf-bearbeiten]

Es gibt kein Chat-to-Build. Aktualisieren Sie nach der Prüfung:

* Anweisungen im Tab **Übersicht** der Agent-Seite sowie **Stimme** und **Darstellung** in den danebenliegenden Tabs.
* **Wissen** auf einer eigenen Seite in der Seitenleiste des Agents.
* Änderungen unter **Darstellung** werden automatisch gespeichert und aktualisieren die Live-Einbettung ohne erneutes Veröffentlichen.

## Ohne Website-URL starten [#ohne-website-url-starten]

Wenn Sie das Formular auf der Startseite leer absenden, öffnet sich dennoch **Try**. Anonyme Besucher können dort eine URL einfügen und mit einem Entwurf chatten; übernehmen Sie ihn bei der Registrierung, um das Onboarding fortzusetzen. Eine eingefügte URL führt immer über den oben beschriebenen Generierungsbildschirm.

---

# FAQs und Produkte

Source: /de/docs/build/faqs-products.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;FAQs&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;Produkte&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;Wissen&#x22;, icon: &#x22;link&#x22; }]" />

## FAQs für verbindliche Antworten nutzen [#faqs-für-verbindliche-antworten-nutzen]

Legen Sie pro Anliegen eines Besuchers jeweils eine FAQ an. Formulieren Sie die Frage in der Sprache Ihrer Kunden und achten Sie darauf, dass die Antwort vollständig ist und nicht auf eine andere FAQ angewiesen ist.

## Produkte für Katalogdaten nutzen [#produkte-für-katalogdaten-nutzen]

Produkte eignen sich für ein benanntes Angebot mit Feldern wie Beschreibung, Preis, Verfügbarkeit oder Link. Halten Sie transaktionsrelevante Angaben aktuell und machen Sie keine Zusagen zu Lagerbestand oder Lieferung, sofern Ihre Quelle nicht zuverlässig aktualisiert wird.

## Duplikate vermeiden [#duplikate-vermeiden]

Pflegen Sie denselben Preis nicht gleichzeitig in einer Notiz, einer FAQ, einem Seitenabschnitt und einem Produkteintrag. Wählen Sie eine maßgebliche Quelle und verlinken Sie an anderer Stelle darauf oder verweisen Sie darauf.

## Verhalten gegenüber Kunden überprüfen [#verhalten-gegenüber-kunden-überprüfen]

Stellen Sie dem Agent nach jeder Änderung die FAQ in mehreren Formulierungen und prüfen Sie, ob Produktlink und Preis korrekt sind.

---

# Follow-ups und Erinnerungen

Source: /de/docs/build/follow-ups.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/build/page-actions&#x22;, label: &#x22;Seitenaktionen&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/build/lookups&#x22;, label: &#x22;Abfragen&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Im richtigen Moment Hilfe anbieten [#im-richtigen-moment-hilfe-anbieten]

Öffnen Sie **Agent → Aktionen → Follow-ups**. Fügen Sie bis zu fünf Regeln für einen Seitenaufruf, einen inaktiven Besucher, eine Exit-Intent-Situation, einen Formularfehler oder ein benutzerdefiniertes Ereignis hinzu. Wählen Sie ein Pfadmuster, optional eine Verzögerung, eine Nachricht mit bis zu 200 Zeichen und bis zu drei Schnellantworten. Die Einstellungen werden automatisch gespeichert. Die Vorschau zeigt die Nachricht, ohne einen Kunden zu kontaktieren oder Experimentdaten zu erzeugen.

Verwenden Sie `/pricing` für einen einzelnen Pfad, `/products/*` für ein Pfadsegment oder `/products/**` für verschachtelte Pfade. Abfrageparameter und Fragmente werden ausgeschlossen. Die Standardverzögerung bei Inaktivität beträgt 30 Sekunden, die Standard-Wartezeit bis zur erneuten Anzeige sieben Tage. Ein Trigger unterbricht weder eine Übernahme durch einen Mitarbeiter noch eine offene, aktive Unterhaltung, wiederholt sich nicht in derselben Sitzung und erscheint nach dem Schließen in dieser Sitzung nicht erneut.

Das Embed meldet Seitenaufrufe, Inaktivität und Exit Intent. Ihr Entwickler kann benutzerdefinierte Ereignisse mit `MakeAgentFast.track` melden; siehe [Seitenaktionen](/de/docs/build/page-actions). Die automatische Meldung von Formularfehlern ist deaktiviert, es sei denn, das Embed verwendet `data-auto-form-error="true"` oder `MakeAgentFastSettings.autoFormError = true`. Gemeldet wird die Formular-ID, niemals Feldwerte.

## Ergebnisse der Kontrollgruppe auswerten [#ergebnisse-der-kontrollgruppe-auswerten]

Standardmäßig werden 10 % der berechtigten Besucher einer stabilen Kontrollgruppe zugewiesen und sehen keine Nachricht. Die Zuweisung gilt pro Besucher und Regel; wiederholte Besuche blähen die Stichprobe nicht auf. Das Dashboard vergleicht die Konversionsraten berechtigter Besucher in der Nachrichten- und der Kontrollgruppe und zeigt den absoluten Uplift in Prozentpunkten.

Eine Konversion ist ein erfasster Lead, eine Buchung, eine abgeschlossene Aktion oder eine erfolgreiche Abfrage innerhalb von 24 Stunden nach einer berechtigten Ausspielung. Das Öffnen der Nachricht oder eine Antwort darauf werden separat ausgewiesen. Vom Browser gemeldete Ereignisse können keine Konversionen deklarieren. Bei weniger als 50 Besuchern pro Gruppe weist das Dashboard darauf hin, dass nicht genügend Daten vorliegen; ab diesem Schwellenwert zeigt es ein einfaches 95-%-Intervall. Kleine Unterschiede sind kein Beweis dafür, dass die Nachricht mehr Verkäufe verursacht hat.

## Einen Kunden benachrichtigen, wenn sich etwas ändert [#einen-kunden-benachrichtigen-wenn-sich-etwas-ändert]

Kunden können fragen: „Sagen Sie mir Bescheid, wenn ein Termin frei wird“ oder „Informieren Sie mich, wenn sich der Status meiner Bestellung ändert.“ Eine Beobachtung überwacht die Verfügbarkeit eines verbundenen Kalenders oder ein Feld bzw. einen Status in einer konfigurierten [Abfrage](/de/docs/build/lookups). Für Beobachtungen von Abfragen ist ein verifizierter, angemeldeter Kunde erforderlich. Beliebige Seiten werden nicht überwacht, und wiederkehrende Erinnerungen werden nicht geplant.

Der Agent schlägt eine Beobachtung mit Ziel und Enddatum vor. Der Kunde muss die Bestätigungsschaltfläche innerhalb von 15 Minuten antippen. Besucher der Website und von Live-Anrufen geben zusätzlich eine E-Mail-Adresse ein und setzen auf dem Bildschirm den Haken für die E-Mail-Einwilligung; ein getipptes oder gesprochenes „Ja“ genügt nicht. Die E-Mail enthält einen allgemeinen Hinweis und einen kurzlebigen Link zurück. Dieser Link meldet den Empfänger nicht an und gewährt keinen Zugriff auf Kundendatensätze.

Jeder Besucher kann drei aktive bzw. ausstehende Beobachtungen haben, pro Agent sind es maximal 50, und die maximale Dauer beträgt 14 Tage. Die Prüfungen beginnen nach 15 Minuten und werden dann auf eine Stunde und sechs Stunden gestreckt. Jede Beobachtung unternimmt einen Benachrichtigungsversuch und endet dann. Sie können sie über die Steuerelemente der Beobachtung oder die Follow-ups-Liste des Owners abbrechen. Eine Änderung der zugrunde liegenden Abfrage- oder Kalenderkonfiguration kann eine Beobachtung beenden. Eine Zustellung mit ungewissem Ergebnis wird nicht automatisch erneut gesendet.

## In Chats nachfassen und bei Unklarheiten bei Ihnen nachfragen [#in-chats-nachfassen-und-bei-unklarheiten-bei-ihnen-nachfragen]

Öffnen Sie **Agent → Aktionen → Follow-ups → Chat-Follow-ups**. Diese beiden Schalter gelten für Chats in Telegram, WhatsApp, Messenger und Instagram.

**Nachfassen, wenn ein Kunde nicht mehr antwortet** ist für Vertriebs-Agents standardmäßig aktiviert und für andere Agent-Typen deaktiviert. Wenn ein Kunde nach einer Antwort nicht mehr reagiert, liest der Agent den Chat erneut und sendet entweder eine kurze Nachricht, wartet etwas länger oder lässt den Kunden in Ruhe. Ein Vertriebs-Agent führt den Kunden in Richtung Kauf, ein Service-Agent prüft, ob das Problem gelöst wurde, und ein Buchungs-Agent bietet einen Termin an. Er verwendet nur Ihr freigegebenes Wissen und die Unterhaltung und hört auf, sobald der Kunde antwortet, ablehnt oder darum bittet, nicht mehr angeschrieben zu werden. Meta-Channels akzeptieren automatisierte Nachrichten nur innerhalb von 24 Stunden nach der letzten Nachricht des Kunden, daher erfolgt das Follow-up dort innerhalb dieses Tages; in einem Telegram-Bot-Chat sind bis zu zwei Follow-ups über einige Tage hinweg möglich. Jedes Follow-up wird wie eine Antwort abgerechnet.

**Bei mir nachfragen, wenn der Agent nicht antworten kann** ist standardmäßig aktiviert. Statt nach einer E-Mail-Adresse zu fragen, teilt der Agent dem Kunden mit, dass er sich beim Team erkundigt, und benachrichtigt Sie mit einem Link zur Unterhaltung. Antworten Sie dort oder speichern Sie die Antwort im Wissen, und der Agent sendet sie dem Kunden in dessen Sprache. Instagram und Messenger akzeptieren Ihre Antwort bis zu 24 Stunden nach der letzten Nachricht des Kunden bzw. bis zu 7 Tage, sobald Ihre Meta-App die Berechtigung „Human Agent“ besitzt.

## Zustellung und Verfügbarkeit [#zustellung-und-verfügbarkeit]

| Ziel                  | Aktuelle Einschränkung                                                                                                                         |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Website / Live-Anruf  | E-Mail mit ausdrücklicher Einwilligung; kein Hintergrund-Push des Widgets                                                                      |
| Telegram              | Bestehender privater Bot-Chat; ein privater Business-Chat erfordert zusätzlich ein offenes 24-Stunden-Fenster                                  |
| WhatsApp              | Freitext innerhalb von 24 Stunden nach der letzten Nachricht des Kunden; außerhalb davon ist eine genehmigte Utility-Vorlage erforderlich      |
| Messenger / Instagram | Nur innerhalb von 24 Stunden nach der letzten Nachricht des Kunden                                                                             |
| Discord / KakaoTalk   | Transport für Beobachtungen nicht verfügbar; die Kakao-Richtlinie verlangt außerdem eine AlimTalk-Vorlage und schließt 20:50–08:00 Uhr KST aus |

Kanalbeschränkungen werden bei der Zustellung erneut geprüft. Eine Beobachtung mit Einwilligung setzt sie nicht außer Kraft und garantiert keine zugestellte Nachricht.

---

# Google Calendar

Source: /de/docs/build/google-calendar.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/build/cal-com&#x22;, label: &#x22;Cal.com&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/build/follow-ups&#x22;, label: &#x22;Verfügbarkeitsbenachrichtigungen&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Verfügbarkeit der Integration [#verfügbarkeit-der-integration]

**Google Calendar ist noch nicht allgemein verfügbar.** Solange die Integration nicht aktiviert ist, zeigt **Agent → Aktionen → Google Calendar** „Demnächst verfügbar“ an, und die Verbindung ist nicht möglich. Eine Agent-Einstellung kann sie nicht aktivieren. [Cal.com](/de/docs/build/cal-com) bleibt als separate Option verfügbar.

## Kalender verbinden [#kalender-verbinden]

Sobald die Integration aktiviert ist, öffnen Sie den Bereich „Google Calendar“ und wählen **Verbinden**. Melden Sie sich bei Google an und prüfen Sie die angeforderten Berechtigungen für Kalenderereignisse und Frei/Besetzt-Verfügbarkeit. Diese Verbindung ist unabhängig von der Anmeldung bei Make Agent Fast. Der Server speichert das Refresh-Token verschlüsselt; weder das Dashboard noch der Agent erhalten es.

Angefordert werden die Scopes `calendar.events`, `calendar.freebusy` sowie die nicht sensiblen Scopes `openid` und `email`. Der Callback setzt eine verifizierte E-Mail-Adresse voraus und speichert sie verschlüsselt, damit `primary` derselben Kalender-ID zugeordnet werden kann wie die ausdrücklich angegebene E-Mail-Adresse. Es wird kein Profil-Scope angefordert. Ältere Verbindungen ohne verifizierte E-Mail-Adresse müssen vor einer Buchung getrennt und neu verbunden werden.

Ein Agent nutzt jeweils nur einen Kalenderanbieter. Trennen Sie einen bestehenden Anbieter, bevor Sie wechseln. Wählen Sie die Kalender-ID (`primary` für den Hauptkalender des verbundenen Kontos) und die zugehörige IANA-Zeitzone, zum Beispiel `Asia/Seoul`. Auf einen freigegebenen Kalender muss mit den Berechtigungen des verbundenen Kontos zugegriffen werden können. Beim Trennen wird die Google-Freigabe widerrufen und die Verbindung entfernt; bestehende Termine werden dabei nicht storniert.

## Arbeitszeiten festlegen [#arbeitszeiten-festlegen]

Neue Verbindungen haben keine Arbeitszeiten, daher werden keine Zeitfenster angeboten, bis Sie welche hinzufügen. Fügen Sie für jeden Arbeitstag Öffnungs- und Schließzeiten hinzu. Ein Tag ohne Eintrag gilt als geschlossen; mehrere sich nicht überschneidende Zeitfenster ermöglichen eine Mittagspause. Die Zeiten werden in der ausgewählten Zeitzone interpretiert. Die Einstellungen werden automatisch gespeichert.

| Einstellung               | Zulässiger Bereich                                         |
| ------------------------- | ---------------------------------------------------------- |
| Dauer eines Termins       | 5–240 Minuten                                              |
| Puffer um belegte Termine | 0–120 Minuten                                              |
| Mindestvorlaufzeit        | 0–43.200 Minuten                                           |
| Buchungszeitraum          | 1–90 Tage                                                  |
| Arbeitszeitfenster        | Bis zu 28 sich nicht überschneidende Zeitfenster pro Woche |

Die Verfügbarkeit ergibt sich aus den Arbeitszeiten abzüglich der belegten Zeiten des ausgewählten Kalenders, des Puffers, der Mindestvorlaufzeit und des Buchungszeitraums. Legen Sie die Zeiten in der für den Kalender vorgesehenen Zeitzone fest und prüfen Sie bei Bedarf die Umstellung zwischen Sommer- und Winterzeit. Wenn keine Zeitfenster angezeigt werden, liegt das eher an geschlossenen Zeiten oder belegten Terminen als an einem Verbindungsfehler.

## Von der Verfügbarkeit zur Buchung [#von-der-verfügbarkeit-zur-buchung]

Der Agent nutzt denselben Ablauf mit `find_slots` und `book_slot` wie bei Cal.com: Er bietet bis zu acht verfügbare Zeiten an, erfasst Name und E-Mail-Adresse sowie optional eine Anmerkung, prüft das gewählte Zeitfenster erneut und zeigt anschließend eine Bestätigungskarte an. Angebote und Vorschläge verfallen nach 15 Minuten; keines von beiden reserviert das Zeitfenster. Nur der Tipp des Kunden auf die Schaltfläche autorisiert die Buchung. Ein gesprochenes „Ja“ während eines Live-Anrufs kann sie nicht auslösen.

Nach der Bestätigung erhält Google ein Ereignis mit einer deterministischen ID, die an die Ausführung der Aktion gebunden ist, und versendet Einladungen an die Teilnehmer. Ein validiertes, bestätigtes Ereignis erzeugt einen abgeschlossenen Beleg; vorläufige Ereignisse bleiben ausstehend. Ist ein Zeitfenster bereits vergeben, fragen Sie neue Zeiten ab und lassen Sie erneut bestätigen. Bei einem unklaren Netzwerkergebnis erfolgt eine Prüfung anhand derselben Ereignis-ID; werten Sie ein Timeout nicht als Erfolg und legen Sie nicht blind eine weitere Buchung an. Konfigurationsänderungen machen ältere Angebote und Vorschläge ungültig.

Um benachrichtigt zu werden, wenn ein Termin frei wird, nutzen Sie eine [Beobachtung](/de/docs/build/follow-ups) mit Einwilligung. Prüfen Sie vor dem Einsatz mit Kunden eine echte Buchung und Einladung in Google, testen Sie ein bereits vergebenes Zeitfenster und kontrollieren Sie das Trennen und erneute Verbinden sowie den vorgesehenen Messaging-Channel.

---

# Wissensquellen

Source: /de/docs/build/knowledge.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;message&#x22;, title: &#x22;Einfügen&#x22;, description: &#x22;Vom Owner verfasste Fakten und Richtlinien mit bis zu 200.000 Zeichen.&#x22; },
{ icon: &#x22;link&#x22;, title: &#x22;URLs und Feeds&#x22;, description: &#x22;Öffentliche Seiten oder regelmäßig aktualisierte Website-Inhalte abrufen.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;Dateien&#x22;, description: &#x22;Text aus PDF-, Word-, Excel-, PowerPoint-, HWP-, OpenDocument-, RTF- und Textdateien extrahieren.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;Medien&#x22;, description: &#x22;Verfügbare YouTube-Untertitel nutzen oder unterstütztes Podcast-Audio transkribieren.&#x22; }
]"
/>

Wissen gibt dem Agent abrufbares Quellmaterial. Beim Hinzufügen einer Quelle wird reiner Text extrahiert, in Passagen unterteilt und in Embeddings umgewandelt; diese Passagen werden anschließend der aktuellen Website zugeordnet. Bei der Beantwortung ruft der Agent die relevanten Passagen ab, anstatt in jedem Prompt alle Quellen zu erhalten.

<TutorialVideo episode="ep01" start="168" />

## Den passenden Quellentyp wählen [#den-passenden-quellentyp-wählen]

| Quelle              | Am besten geeignet für                                                                                                                                                                                | Wichtiges Verhalten                                                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Text einfügen**   | Richtlinien, Kontaktdaten, kurze interne Notizen                                                                                                                                                      | 5–200.000 Zeichen; keine automatische Aktualisierung                                                                                     |
| **Von URL**         | Öffentliche Seiten, die an anderer Stelle gepflegt werden                                                                                                                                             | Standardmäßig eine Seite; optional Crawling von 5, 10, 20 oder 40 Seiten derselben Website                                               |
| **Datei hochladen** | PDF, Word (`.docx`, `.doc`), Excel (`.xlsx`, `.xls`), PowerPoint (`.pptx`), Hancom `.hwp` und `.hwpx`, OpenDocument (`.odt`, `.ods`, `.odp`), `.rtf`, `.txt`, `.md`, `.csv`, `.tsv`, `.json`, `.html` | Maximal 20 MB; passwortgeschützte und makrofähige Dateien werden abgelehnt; gescannte reine Bild-PDFs enthalten keinen auswählbaren Text |
| **YouTube**         | Öffentliche Videos mit nützlichem gesprochenem Inhalt                                                                                                                                                 | Operate oder Scale. Versucht zuerst Untertitel, dann verfügbare Transkription; nach bestem Bemühen                                       |
| **Podcast**         | Eine öffentliche Audio-URL einer Episode oder ein unterstützter Feed                                                                                                                                  | Operate oder Scale. Erfordert abrufbares Audio und einen verfügbaren Transkriptionsanbieter                                              |
| **Blog / RSS**      | Öffentliche RSS-/Atom-Updates von Blogs oder Podcasts                                                                                                                                                 | Operate oder Scale. Extrahiert verfügbare Feed-Einträge als Text; nach bestem Bemühen                                                    |

Verwenden Sie **FAQ und Produkte** für vorhersehbare Frage-Antwort- oder Katalogfelder, anstatt sie in einem langen Dokument zu vergraben. Siehe [FAQs und Produkte](/de/docs/build/faqs-products).

## Eine Quelle hinzufügen [#eine-quelle-hinzufügen]

1. Öffnen Sie in der Seitenleiste des Agents die Seite **Wissen** und wählen Sie **Quelle hinzufügen**.
2. Wählen Sie **Text einfügen**, **Von URL** oder **Datei hochladen**. **YouTube**, **Podcast** und **Blog / RSS** finden Sie unter **Weitere Quellentypen**; sie erfordern Operate oder Scale. Im Tarif Launch werden sie mit einem Schloss angezeigt.
3. Geben Sie den Inhalt ein oder wählen Sie eine Datei aus.
4. Wählen Sie bei **Von URL** die Option **Zu crawlende Seiten** (1, 5, 10, 20 oder 40). Legen Sie bei abgerufenen Quellen optional **Automatisch aktualisieren** auf **Täglich**, **Wöchentlich** oder **Nie** fest.
5. Wählen Sie **Zum Wissen hinzufügen** und warten Sie auf das Ergebnis, das die Anzahl der indexierten Chunks anzeigt.
6. Stellen Sie eine Frage, deren Antwort ausschließlich in der neuen Quelle steht.

Die Wissensaufnahme verbraucht Credits, da die Quellpassagen in Embeddings umgewandelt werden. Sie wird abgelehnt, wenn der Workspace keinen aktiven Zugang oder kein nutzbares Credit-Guthaben hat.

## Öffentliche Seiten sicher crawlen [#öffentliche-seiten-sicher-crawlen]

Der Crawler akzeptiert öffentliche HTTP-/HTTPS-Inhalte und blockiert unsichere Ziele in privaten Netzwerken. Beginnen Sie mit einer kanonischen Seite. Erhöhen Sie die Seitenzahl nur, wenn die verlinkten Seiten zum selben nützlichen Informationsbestand gehören; ein größerer Crawl kann Navigation, rechtliche Standardtexte, doppelten Text oder veraltete Archive hinzufügen, die den Abruf verschlechtern.

Die gewählte Anzahl ist ein Maximum, kein Versprechen. Robots-Verhalten, Authentifizierung, rein clientseitiges Rendering, Weiterleitungen, Inhaltstyp, Antwortgröße und Linkstruktur können die Zahl der abgerufenen Seiten verringern. Eine Seitenantwort ist auf 5 MB begrenzt und muss ausreichend extrahierbaren Text enthalten.

Fügen Sie für wichtige Fakten hinter einem Login eine freigegebene Zusammenfassung ein oder laden Sie einen bereinigten Export hoch, anstatt eine authentifizierte Seite zu crawlen.

## Dateien und Medien verwenden [#dateien-und-medien-verwenden]

Hochgeladene Dateien müssen extrahierbaren Text enthalten. Für ein gescanntes reines Bild-PDF wird keine OCR durchgeführt; wandeln Sie es vor dem Hochladen in durchsuchbaren Text um. Tabellenkalkulationen werden Blatt für Blatt gelesen, und Tabellenzeilen behalten ihre Zellen beieinander (`Coffee | 3000`); anderes Layout wird in Lesereihenfolge abgeflacht, halten Sie Tabellen daher einfach. Entfernen Sie das Passwort eines Dokuments, bevor Sie es hochladen, und speichern Sie makrofähige Office-Dateien (`.docm`, `.xlsm`, `.pptm`) zuvor als normale `.docx`-, `.xlsx`- oder `.pptx`-Dateien. Eine Datei, deren Inhalt nicht zur Dateiendung passt, wird abgelehnt.

Beim YouTube-Import werden bevorzugt verfügbare Untertitelspuren verwendet. Sind keine Untertitel verfügbar, hängt die Transkription vom Anbieter und vom Netzwerk ab. Podcast-Audio muss öffentlich abrufbar sein. Feed-Ergebnisse hängen davon ab, wie viel Artikel- oder Episodentext der Feed bereitstellt. Prüfen Sie nach jedem Medienimport den Quellentitel und die Anzahl der Chunks und testen Sie einen konkreten Fakt, anstatt anzunehmen, dass die gesamte Aufnahme erfasst wurde.

## Aktualisierung und Ersetzung planen [#aktualisierung-und-ersetzung-planen]

Tägliche und wöchentliche Zeitpläne sind für URL-, YouTube-, Podcast- und Feed-Quellen verfügbar. Das System ruft den gespeicherten Ursprung der Quelle erneut ab und ersetzt deren abrufbare Passagen, sobald ein geplanter Crawl erfolgreich ist. Die Quellenliste zeigt den Aktualisierungsintervall und den Zeitpunkt der letzten Aktualisierung.

Eingefügte und hochgeladene Quellen sind Momentaufnahmen. Um eine Quelle zu korrigieren oder zu ersetzen, löschen Sie sie und fügen Sie den aktualisierten Inhalt hinzu. Das Löschen einer Quelle entfernt ihre Passagen aus dem künftigen Abruf; bereits gesendete Nachrichten, die die alte Version zitiert oder zusammengefasst haben, werden dadurch nicht verändert.

Legen Sie für Preise, Richtlinien und Zeitpläne jeweils eine eindeutige maßgebliche Quelle fest. Wenn zwei aktive Quellen sich widersprechen, kann der Abruf beide Aussagen liefern. Entfernen Sie überholte Versionen, anstatt „neue“ Kopien daneben hinzuzufügen.

## Inhalte so schreiben, dass der Agent sie abrufen kann [#inhalte-so-schreiben-dass-der-agent-sie-abrufen-kann]

* Nennen Sie in jedem Abschnitt das Thema: „Kündigungsrichtlinie für den Pro-Tarif“ lässt sich besser abrufen als „Weitere Details“.
* Platzieren Sie die Antwort in einfacher Sprache nahe der zugehörigen Überschrift.
* Geben Sie Einheiten, Währung, Zeitzone, Gültigkeitsdatum und Ausnahmen an, wo sie relevant sind.
* Verwenden Sie stabile kanonische URLs und aussagekräftige Dateinamen.
* Trennen Sie öffentliche Informationen von internen Anweisungen oder privaten Datensätzen.
* Halten Sie das Persona-Verhalten in [Persona und Anweisungen](/de/docs/build/persona) fest, nicht im faktischen Quellenmaterial.

## Fundierte Antworten testen [#fundierte-antworten-testen]

Erstellen Sie vor der Veröffentlichung ein kleines Abnahme-Set:

1. Eine direkte Frage, deren Antwort in der Quelle ausdrücklich steht.
2. Eine Umformulierung mit anderen Worten.
3. Eine Grenzfrage, die die Quelle nicht beantwortet.
4. Ein kürzlich geänderter Fakt.
5. Eine Sprachvariante für jede konfigurierte Sprache des Agents.

Das richtige Ergebnis ist nicht immer eine selbstsichere Antwort. Wenn der Quelle ein Fakt fehlt, sollte der Agent seinen Fallback- bzw. Eskalationsanweisungen folgen, anstatt etwas zu erfinden. Prüfen Sie nach dem Launch unter **Unterhaltungen** wiederholte unbeantwortete Fragen und machen Sie aus validierten Antworten eine Quelle oder eine strukturierte FAQ.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                          | Prüfen                                                                                                                                              |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| URL meldet keinen nutzbaren Text                                 | Öffentlicher Zugriff, unterstützter Inhaltstyp, serverseitig gerenderter Text, Weiterleitungsziel und Seitengröße                                   |
| PDF meldet keinen auswählbaren Text                              | Ob es sich um einen Scan handelt; per OCR in ein durchsuchbares PDF oder eine Textdatei umwandeln bzw. exportieren                                  |
| Datei als passwortgeschützt oder nicht zum Typ passend abgelehnt | Passwort entfernen und die Datei im tatsächlichen Format erneut speichern, statt sie umzubenennen; makrofähige Office-Dateien ohne Makros speichern |
| YouTube-/Podcast-Import schlägt fehl                             | Öffentliche URL, Verfügbarkeit von Untertiteln bzw. Audio, API-Schlüssel des Transkriptionsanbieters und Abrufbeschränkungen                        |
| Korrekter Fakt wird ignoriert                                    | Verarbeitungsergebnis, Formulierung, widersprüchliche Quellen, Alter der Quelle und die genaue Testfrage                                            |
| Agent gibt zu viel preis                                         | Private Quelle sofort entfernen und die Grenzen der Persona sowie den Kontozugriff verschärfen                                                      |
| Alte Antwort bleibt bestehen                                     | Veraltete Quelle löschen bzw. ersetzen, auf die erneute Indexierung warten und eine neue Testunterhaltung starten                                   |

Laden Sie niemals Zugangsdaten, private Schlüssel, uneingeschränkte Kundenexporte, Gesundheitsdaten oder andere Inhalte hoch, die der öffentliche Agent unter keinen Umständen preisgeben darf.

---

# Lookups

Source: /de/docs/build/lookups.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/security&#x22;, label: &#x22;Angemeldete Kunden&#x22;, icon: &#x22;shield&#x22; },
{ href: &#x22;/de/docs/build/knowledge&#x22;, label: &#x22;Wissensquellen&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Wann Sie einen Lookup verwenden [#wann-sie-einen-lookup-verwenden]

Verwenden Sie einen Lookup für den aktuellen Bestellstatus, eine bestehende Buchung oder den Kontodatensatz eines Kunden. Stabile Richtlinien und Produktinformationen gehören in die [Wissensquellen](/de/docs/build/knowledge). Ein Lookup liest Ihr System aus; er darf einen Datensatz weder belasten, stornieren, reservieren noch anderweitig ändern. Allgemeine Auswahl- und Bestätigungskarten senden lediglich eine Nachricht des Besuchers. Für bestätigte Schreibvorgänge verwenden Sie [Änderungsaktionen](/de/docs/build/change-actions); für Kalenderreservierungen nutzen Sie [Buchung mit Cal.com](/de/docs/build/cal-com). Nur Bestätigungskarten, die an einen Ausführungslauf gebunden sind, autorisieren diese Vorgänge.

## Aktion konfigurieren [#aktion-konfigurieren]

Öffnen Sie **Agent → Aktionen**. Erstellen Sie das Secret unter **Angemeldete Kunden**, speichern Sie es auf Ihrem Server und implementieren Sie die [Kundenidentifikation](/de/docs/embed/security#identify-signed-in-customers). Fügen Sie unter **Lookups** einen Namen wie `order_status` hinzu, beschreiben Sie, wann der Agent ihn verwenden soll, und geben Sie Ihren öffentlichen HTTPS-Endpunkt ein. Deklarieren Sie nur die Eingaben, die Sie benötigen, zum Beispiel einen String `order_id`. Der Agent sieht das Tool als `lookup_order_status`.

Lassen Sie **Angemeldeter Kunde erforderlich** für private Datensätze aktiviert (Standardeinstellung). Ist die Option deaktiviert, können Anfragen `customer: null` enthalten; geben Sie dann nur Informationen zurück, die für einen anonymen Besucher geeignet sind. Eine im Chat genannte oder aus einem Foto extrahierte ID ist eine Eingabe, keine authentifizierte Identität.

Bestehende Felder werden automatisch gespeichert; warten Sie vor dem Testen auf die Speicheranzeige. Sie können einen Lookup aktivieren/deaktivieren, bearbeiten oder löschen. Das Panel setzt ein konfiguriertes Secret voraus. Diese Aktionen werden im Dashboard konfiguriert; Wave 1 bietet keine Verwaltung von Lookups über die öffentliche API.

## Die Anfrage, die Sie erhalten [#die-anfrage-die-sie-erhalten]

Make Agent Fast sendet einen JSON-POST an Ihre konfigurierte URL. Die folgenden Beispiele verwenden Platzhalterwerte für die Signatur:

```http
POST /agent/order-status HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
```

```json
{
  "version": 1,
  "action": "order_status",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}
```

`action` ist der konfigurierte Name ohne das Präfix `lookup_`. `requestId` identifiziert diesen Versuch; `siteId` identifiziert Ihre Website. `input` enthält nur deklarierte String-Parameter. `customer` ist entweder null oder das vom Server verifizierte Objekt `{ id, email?, name? }`; Eingaben des Besuchers oder des Modells können es nicht ersetzen. Der **Test** im Dashboard verwendet bewusst den Beispielkunden, den ein autorisierter Owner eingegeben hat.

## Signatur verifizieren [#signatur-verifizieren]

Die Signatur ist ein hexadezimaler HMAC-SHA256 in Kleinbuchstaben, berechnet mit Ihrem **Agent-Secret** und mit dem Präfix `v1=`. Signiert wird exakt `"maf-webhook-v1:" + timestamp + "." + rawBody`. Bewahren Sie die empfangenen Bytes unverändert auf; Parsen und erneutes Serialisieren von JSON vor der Signaturprüfung kann sie verändern. Diese Hilfsfunktion akzeptiert eine standardmäßige serverseitige `Request`, wendet ein Aktualitätsfenster von fünf Minuten an und prüft die Website-ID:

```js
import { createHmac, timingSafeEqual } from "node:crypto";

export async function verifyLookupRequest(request, expectedSiteId) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const timestamp = request.headers.get("x-maf-timestamp");
  const signature = request.headers.get("x-maf-signature");
  const now = Math.floor(Date.now() / 1000);
  if (!timestamp || !/^\d+$/.test(timestamp) ||
      !Number.isSafeInteger(Number(timestamp)) ||
      Math.abs(now - Number(timestamp)) > 300) {
    throw new Error("Invalid timestamp");
  }
  if (!signature || !/^v1=[a-f0-9]{64}$/.test(signature)) {
    throw new Error("Invalid signature");
  }
  const rawBody = Buffer.from(await request.arrayBuffer());
  const expected = createHmac("sha256", secret)
    .update(`maf-webhook-v1:${timestamp}.`)
    .update(rawBody)
    .digest();
  const actual = Buffer.from(signature.slice(3), "hex");
  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
    throw new Error("Invalid signature");
  }
  const body = JSON.parse(rawBody.toString("utf8"));
  if (body?.version !== 1 || body.siteId !== expectedSiteId) {
    throw new Error("Invalid lookup scope");
  }
  return body;
}
```

Rufen Sie die Funktion auf, bevor Ihr Body-Parser die Anfrage verarbeitet. Ihr Handler sollte Verifizierungsfehler ablehnen, die erwartete Aktion und die Struktur der Eingaben validieren und die Zugehörigkeit des Datensatzes anhand von `body.customer.id` prüfen, bevor er private Daten zurückgibt. Wählen Sie beispielsweise Bestellung A128 **aus den Bestellungen dieses Kunden** aus, nicht allein anhand der Bestell-ID. Verwenden Sie niemals `input.customer_id`, eine im Chat angegebene E-Mail-Adresse oder ein Foto als Autorisierung. Verlangen Sie für private Endpunkte einen Kunden, der nicht null ist. Begrenzen Sie die Größe eingehender Bodys auf Ihrem Server und protokollieren Sie `requestId` innerhalb des Aktualitätsfensters, wenn Sie Replay-Angriffe abweisen möchten; die Zeitstempelprüfung allein weist einen Replay innerhalb dieses Fensters nicht ab.

Verwenden Sie HTTPS und halten Sie diesen Endpunkt schreibgeschützt, auch wenn der Transport per POST erfolgt. Aktualisieren Sie nach einer Rotation des Agent-Secrets sowohl Ihren Server zur Identitätssignierung als auch Ihren Lookup-Verifizierer.

## Antwort zurückgeben [#antwort-zurückgeben]

Antworten Sie mit einem erfolgreichen 2xx-Status und JSON, das diesem Vertrag entspricht. Das erste Beispiel zeigt einen gefundenen Datensatz, das zweite ein normales Ergebnis ohne Treffer:

```json
{
  "found": true,
  "card": {
    "title": "Order #A128",
    "status": { "label": "Shipped", "tone": "success" },
    "fields": [{ "label": "Carrier", "value": "DHL" }],
    "reference": "A128",
    "asOf": "2026-10-12T09:00:00Z",
    "link": { "label": "Track", "url": "https://shop.example.com/orders/A128" }
  },
  "facts": { "order_id": "A128", "status": "shipped", "carrier": "DHL" }
}
```

```json
{ "found": false }
```

`found` ist erforderlich. Bei `found: true` geben Sie `card`, `facts` oder beides an. Eine Karte benötigt `title` und `fields` (ein leeres Array ist zulässig). Optionale Felder sind `status`, `reference`, `asOf` und `link`. Fügen Sie der Antwortkarte kein `kind` hinzu. Die Status-Tonalitäten sind `neutral`, `success`, `warning` und `danger`. Verwenden Sie für `asOf` einen ISO-Zeitstempel und für den Link eine HTTPS-URL ohne eingebettete Zugangsdaten. Ungültige optionale Links werden weggelassen.

`facts` ist ein flaches Objekt, dessen Werte Strings, endliche Zahlen, Booleans oder null sind; verschachtelte Objekte und Arrays werden abgelehnt. Unbekannte Felder im Antwort- bzw. Kartenschema werden abgelehnt. Geben Sie nur die Informationen zurück, die zur Beantwortung nötig sind: Das Modell erhält maskierte, begrenzte Daten, die als nicht vertrauenswürdig gekennzeichnet sind und keine Anweisungen darstellen. Karteninhalt ist reiner Text, kein HTML.

## Limits und Verhalten bei Fehlern [#limits-und-verhalten-bei-fehlern]

| Element                             | Limit                                                                                                                                        |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Lookups pro Agent                   | 5; eindeutige Namen und IDs                                                                                                                  |
| Name                                | `^[a-z][a-z0-9_]{2,39}$`; reservierte Aktionsnamen sind nicht verfügbar                                                                      |
| Beschreibung                        | 300 Zeichen                                                                                                                                  |
| Deklarierte Eingaben                | 3; eindeutige Namen gemäß `^[a-z][a-z0-9_]{1,31}$`                                                                                           |
| Beschreibungen / Werte der Eingaben | 300 / 200 Zeichen; Werte werden getrimmt                                                                                                     |
| Endpunkt                            | Öffentliches HTTPS, bis zu 500 Zeichen, keine Zugangsdaten; private/interne Adressen werden blockiert; Weiterleitungen werden nicht verfolgt |
| Timeout / Antwort-Body              | 8 Sekunden / 32 KiB (32.768 Bytes)                                                                                                           |
| Modelldaten                         | 2.000 Zeichen, getrennt von der Karte für den Besucher                                                                                       |
| Kartentitel / Labels / Feldwerte    | 80 / 40 / 200 Zeichen                                                                                                                        |
| Kartenfelder                        | 8; höchstens 3 Karten pro Agent-Zug                                                                                                          |

Fehlt die Kundenidentität, wird eine Anmeldewarnung angezeigt, ohne dass Ihr Endpunkt aufgerufen wird. Fehlen erforderliche Eingaben, fordert der Agent den Besucher dazu auf. `found: false` zeigt eine neutrale Karte ohne Treffer an. Timeouts, Nicht-2xx-Status, ungültiges JSON bzw. Schema oder zu große Antworten zeigen einen Fehlerstatus an und weisen das Modell an, nicht zu raten. Geben Sie für einen gewöhnlich fehlenden Datensatz `found: false` mit 2xx zurück, statt HTTP 404. Halten Sie wichtige Fakten knapp: Überlange Kartenstrings und Modelldaten werden gekürzt.

## Im Dashboard testen [#im-dashboard-testen]

1. Speichern Sie den Lookup und öffnen Sie **Test**. Geben Sie eine Beispiel-Kunden-ID, optional eine E-Mail-Adresse und alle erforderlichen Eingaben ein. Verwenden Sie ein Konto, das Sie kontrollieren.
2. Führen Sie den **Test** aus. Dabei wird eine echte signierte Anfrage gesendet, auch wenn der Lookup für Besucher deaktiviert ist; der gewöhnliche Probechat ruft den Endpunkt nie auf. Das Dashboard begrenzt Testversuche pro Owner.
3. Prüfen Sie die validierte Karte bzw. Zusammenfassung oder den Fehler, die Anfrage-ID, die Dauer und gegebenenfalls den HTTP-Status. Kontrollieren Sie die Logs Ihres Endpunkts, ohne Secrets oder Kunden-Tokens aufzuzeichnen.
4. Testen Sie die Fälle „gefunden“, „nicht gefunden“, „falsches Konto“, „fehlende Eingabe“ und „Timeout“. Testen Sie anschließend das echte Embed mit zwei authentifizierten Kunden; ein Beispiel im Dashboard belegt weder die Isolation der Browser-Identität noch die tatsächliche Tool-Auswahl durch das Modell.

Das Widget zeigt Statuskarten an; allgemeine Auswahl-/Bestätigungsantippen senden ihre Beschriftungen als Nachrichten. Bestätigungen für Änderungen und Buchungen, die an einen Ausführungslauf gebunden sind, nutzen stattdessen den geschützten Ausführungsablauf. Connectors passen Karten an native Text-/Kartenformate und Schaltflächen, Schnellantworten oder Listen an, mit Text-Fallback gemäß den Limits des jeweiligen Channels. Testen Sie jeden vorgesehenen Channel, bevor Sie sich auf die Zustellung verlassen.

---

# Eigene Tools (MCP)

Source: /de/docs/build/mcp-tools.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/build/change-actions&#x22;, label: &#x22;Bestätigungen und Freigaben&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: &#x22;Kundenidentität&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Verbinden und erkennen [#verbinden-und-erkennen]

Öffnen Sie **Agent → Aktionen → Ihre Tools (MCP)**. Verbinden Sie Ihren Remote-Server über dessen OAuth-Ablauf oder mit einem Bearer-Zugangsdatum, oder verwenden Sie eine bestehende MCP-Verbindung. Wählen Sie **Erkennen**, um den Tool-Katalog zu lesen. Prüfen Sie Beschreibung, Parameter und Annotationen jedes Tools, bevor Sie es aktivieren. Die Erkennung führt kein Tool aus; neu erkannte Tools sind deaktiviert.

Sie können drei Tool-Server konfigurieren und insgesamt 20 Tools aktivieren. Zugangsdaten bleiben serverseitig. Wenn Sie eine Tool-Zuordnung entfernen, wird diese Zuordnung beendet, die gemeinsame Wissensverbindung und deren OAuth-Berechtigung werden jedoch nicht widerrufen; verwalten Sie diese Verbindung separat. Der MCP-Server von Make Agent Fast für die Owner-Verwaltung kann nicht als Tool-Server für Kunden bereitgestellt werden. Wie Sie Ihre Agents aus Claude heraus verwalten, lesen Sie unter [Claude und ChatGPT verwenden](/de/docs/operate/ai-assistants).

## Lesen oder Schreiben festlegen [#lesen-oder-schreiben-festlegen]

| Wirkung   | Verhalten                                                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Lesen     | Ruft das Tool direkt auf und behandelt zurückgegebenen Text bzw. strukturierte Daten als nicht vertrauenswürdige Geschäftsdaten        |
| Schreiben | Erstellt einen Vorschlag; der Kunde muss die exakten Eingaben mit den Schaltflächen der Karte bestätigen, bevor die Ausführung erfolgt |

„Lesen“ ist nur verfügbar, wenn der Server `readOnlyHint: true` angibt und nicht `destructiveHint: true`, und Sie das Tool weiterhin als Lesezugriff klassifiziert lassen. Andernfalls behandeln Sie es als Schreibzugriff. Prüfen Sie, was der Server tatsächlich tut; Annotationen sind kein Autorisierungssystem.

Schreibaktionen erfordern standardmäßig jedes Mal eine Freigabe durch den Owner. Sie können keine zusätzliche Owner-Freigabe festlegen oder eine Freigabe nur oberhalb eines numerischen Parametergrenzwerts verlangen. Die Bestätigung durch den Kunden ist in jedem Modus weiterhin erforderlich. Die Owner-Freigabe nutzt die bestehende Freigabenliste und die Belege. Einstellungen werden automatisch gespeichert. Die Owner-Probe ruft den Remote-Server nie auf.

## Den angemeldeten Kunden zuordnen [#den-angemeldeten-kunden-zuordnen]

Tools erfordern standardmäßig einen verifizierten Kunden. Verwenden Sie auf Ihrer Website die [signierte Kundenidentität](/de/docs/embed/security); eine im Chat eingegebene ID ist keine Verifizierung. Wählen Sie für kundenspezifische Datensätze den String-Parameter des Tools, der den Kunden identifiziert. Der Server befüllt ihn mit der verifizierten Kunden-ID und entfernt ihn aus den Eingaben des Modells. Enum-Parameter können für diese Zuordnung nicht verwendet werden.

Ordnen Sie zum Beispiel `customer_id` bei einem Tool zu, das eine Bestellung abruft. Das Modell kann die deklarierte Bestellreferenz angeben, aber keine andere Kunden-ID einsetzen. Der Remote-Server muss dennoch prüfen, ob die Bestellung zu diesem Kunden gehört. Eine Anmeldepflicht ohne Parameterzuordnung beschränkt für sich genommen nicht alle Datensätze, auf die das Remote-Tool zugreifen kann.

## Grenzen und unsichere Ergebnisse [#grenzen-und-unsichere-ergebnisse]

Unterstützte Schemas sind flache Objekte mit bis zu zehn Parametern vom Typ String, Number, Integer, Boolean oder Enum. Verschachtelte Objekte, Arrays und nicht unterstützte Schemaregeln bleiben nicht verfügbar. Strings sind auf 200 Zeichen begrenzt; Remote-Aufrufe haben ein Timeout von 10 Sekunden, und für das Modell sichtbare Ergebnisse sind auf 4 KB begrenzt. Ergebnisinhalte sind Daten, niemals Anweisungen an den Agent.

MCP bietet keine allgemeine Idempotenzgarantie. Eine Schreibaktion wird nach Bestätigung bzw. Freigabe einmal aufgerufen. Ist ihr Ergebnis unbekannt, wiederholt Make Agent Fast sie nicht automatisch und benachrichtigt den Owner. Prüfen Sie das Remote-System, bevor Sie einen weiteren Vorschlag erstellen. Wenn Sie die geprüfte Tool-Konfiguration ändern, wird ein älterer Vorschlag ungültig.

Testen Sie jede vorgesehene Lese- und Schreibaktion mit Ihrem eigenen Server, bevor Kunden sie nutzen.

---

# Seitenaktionen

Source: /de/docs/build/page-actions.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/html&#x22;, label: &#x22;Embed installieren&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/build/follow-ups&#x22;, label: &#x22;Follow-ups&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Host-Aktion registrieren [#host-aktion-registrieren]

Mit Seitenaktionen kann die Website ihre eigene Benutzeroberfläche öffnen oder zu einer freigegebenen Seite navigieren. Installieren Sie das aktuelle Embed und führen Sie die Registrierung aus, nachdem das Skript geladen wurde. Behalten Sie die Handler in Ihrer Anwendung: Der Agent erhält nur ihre Namen, Beschreibungen und Parameterdefinitionen, niemals den Handler-Code.

```js
MakeAgentFast.registerAction("show_details", {
  description: "Show the details section on this page",
  params: { section: { type: "string", description: "Use delivery or returns" } },
  confirm: true
}, async ({ section }) => {
  const sections = {
    delivery: document.getElementById("delivery-details"),
    returns: document.getElementById("returns-details")
  };
  if (!Object.hasOwn(sections, section) || !sections[section]) {
    throw new Error("Unknown section");
  }
  sections[section].scrollIntoView({ block: "start" });
  return { shown: section };
});

// Run when the page component unmounts:
// MakeAgentFast.unregisterAction("show_details");
```

Beide Methoden geben einen booleschen Wert zurück, der angibt, ob die Registrierung bzw. Entfernung akzeptiert wurde. Namen bestehen aus Kleinbuchstaben, Ziffern und Unterstrichen, beginnen mit einem Buchstaben und umfassen 2–40 Zeichen. Es gibt neun benutzerdefinierte Registrierungsplätze sowie die integrierte Aktion `open_page`. Jede Definition erlaubt fünf String-Parameter; alle deklarierten Parameter sind erforderlich, mit Werten von bis zu 200 Zeichen. Beschreibungen sind auf 200 Zeichen begrenzt. Ein Handler darf innerhalb von 10 Sekunden einen String oder einen JSON-serialisierbaren Wert von bis zu 2 KB zurückgeben.

## Aktionen im Dashboard freigeben [#aktionen-im-dashboard-freigeben]

Öffnen Sie die installierte Website, damit sie ihre Aktionsnamen und Beschreibungen meldet, und öffnen Sie dann **Agent → Aktionen → Seitenaktionen**. Aktivieren Sie die Funktion und erlauben Sie jede gewünschte Aktion. Gemeldete Beschreibungen sind nicht vertrauenswürdige Website-Metadaten; die Erkennung gibt nichts frei. Die Einstellungen werden automatisch gespeichert.

Der Agent kann nur Aktionen vorschlagen, die aktuell registriert und zugleich erlaubt sind. Der Customer sieht vor der Ausführung eine Karte. Eine Bestätigung ist erforderlich, es sei denn, der Owner stuft die Aktion als sicher ein; `confirm: true` im Host-Code erfordert immer einen Tipp. `confirm: false` allein umgeht die Richtlinie des Owners nicht. Verwenden Sie den sicheren Modus nur für harmlose Änderungen an der Oberfläche.

Die integrierte Aktion `open_page` benötigt keinen Handler. Erlauben Sie sie im Dashboard; sie akzeptiert einen relativen Pfad oder eine HTTP(S)-URL innerhalb der erlaubten Website-Origins des Agents. Relative Pfade setzen zusätzlich voraus, dass die aktuelle Website-Origin erlaubt ist. Die Aktion kann nicht zu einem beliebigen externen Ziel navigieren.

## Ein Ereignis mit track melden [#ein-ereignis-mit-track-melden]

```js
MakeAgentFast.track("form_error", { formId: "contact" });
MakeAgentFast.track("checkout_help", { step: "delivery" });
```

Rufen Sie diese Methoden auf, nachdem das Embed geladen wurde und das entsprechende Ereignis tatsächlich eintritt. Konfigurieren Sie einen passenden Ereignisnamen in [Follow-ups](/de/docs/build/follow-ups). Die Namen folgen demselben Format mit 2–40 Zeichen; optionale Daten müssen ein JSON-Objekt von höchstens 1 KB sein. Senden Sie keine Feldwerte, Zugangsdaten oder Zahlungsdaten. Regeln werden anhand von Ereignis, Pfad und Verzögerung abgeglichen; Metadaten werden nicht gespeichert, nicht an das Modell gesendet und nicht als Conversion-Nachweis verwendet. Die Rückgabe `true` bedeutet, dass der Loader das Ereignis akzeptiert hat, nicht, dass eine Nachricht angezeigt wurde.

## Sicherheit und Überprüfung [#sicherheit-und-überprüfung]

Seitenaktionen funktionieren im Live-Website-Widget, nicht in Messaging-Channels, in der Owner-Probe oder in der Live-Sprachfunktion. Der Loader und der Frame prüfen Origin, Quelle, Slug und ausstehende Anfrage-IDs. Ergebnisse gelangen als nicht vertrauenswürdige Browserdaten zurück in den Chat und sind kein Beweis dafür, dass sich ein Datensatz auf dem Server geändert hat. Behalten Sie Authentifizierung und Autorisierung in Ihren eigenen Handlern bzw. Ihrem Backend; verwenden Sie für folgenreiche Schreibvorgänge im Geschäftsbetrieb [Änderungsaktionen](/de/docs/build/change-actions).

Ein Timeout bricht den Handler nicht ab und beweist nicht, dass nichts passiert ist. Wiederholen Sie eine unsichere Aktion nicht automatisch. Heben Sie die Registrierung von Handlern auf, wenn ihre Seitenkomponente den Bildschirm verlässt. Bereits zwischengespeicherte Embeds benötigen für diese API die aktuelle Loader-Version `20261014-page-actions`.

Diese API verarbeitet keine Zahlungen und stellt keinen Shopify-Connector bereit.

---

# Persona und Anweisungen

Source: /de/docs/build/persona.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Persona-Regeln&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Grenzen&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Sprachen&#x22;, icon: &#x22;globe&#x22; }]" />

## Identität und Wissen trennen [#identität-und-wissen-trennen]

Es gibt keine separate Persona-Seite. Verfassen Sie die Anweisungen für den Agent auf der Agent-Seite im Tab **Übersicht** unter **Anweisungen**; sie werden automatisch gespeichert.

Die Persona beschreibt, wer der Agent ist und wie er sich verhält. Wissen liefert die Fakten. Schreiben Sie „Sprich als Support-Assistent von Acme“ in die Persona; die aktuelle Garantiedauer gehört dagegen in eine Source.

## Reihenfolge der Anweisungen [#reihenfolge-der-anweisungen]

Verfassen Sie die Anweisungen in dieser Reihenfolge:

1. Identität und Rolle
2. Primäres Ziel der Besucher
3. Tonalität und Antwortlänge
4. Erforderliche Aktionen und Fragen
5. Unzulässige Aussagen und sensible Themen
6. Bedingungen für Eskalation und Lead-Erfassung

## Grenzen [#grenzen]

Legen Sie fest, wann der Agent sagen soll, dass er etwas nicht weiß, wann er eine Antwort belegen oder einschränken soll und wann er menschliche Hilfe anbieten soll. Weisen Sie ihn niemals an, Unsicherheit zu verbergen oder fehlende Daten zu erfinden.

## Änderungen testen [#änderungen-testen]

Änderungen an der Persona können sich auf jeden Channel auswirken. Testen Sie vor der Veröffentlichung einer größeren Änderung erneut häufige Fragen, Ablehnungen, die Lead-Erfassung und die unterstützten Sprachen.

---

# Sprach- und Live-Anrufe

Source: /de/docs/build/voice.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;Standardstimmen&#x22;, icon: &#x22;voice&#x22; },
{ label: &#x22;Sprachnachrichten&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Live-Anrufe&#x22;, icon: &#x22;bolt&#x22; }
]"
/>

## Die drei Interaktionsmodi im Überblick [#die-drei-interaktionsmodi-im-überblick]

| Modus                   | Erlebnis für Besucher                                                                     | Berechtigung und Nutzung                                                                                                                          |
| ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Text-Chat**           | Tippt eine Nachricht und erhält Text                                                      | Immer aktiviert; verbraucht normale KI-Credits                                                                                                    |
| **Sprachnachrichten**   | Nimmt eine Nachricht auf, wartet auf Transkription, Agent und TTS und erhält eine Antwort | In allen Tarifen enthalten; Transkription, Modell und Sprachverarbeitung verbrauchen Credits                                                      |
| **Live-Echtzeit-Anruf** | Führt ein gesprochenes Gespräch mit geringer Latenz                                       | Operate: 30 Min./Monat; Scale: 90 Min./Monat; Launch: nicht verfügbar; zusätzlich werden vorab Credits für das konfigurierte Anruflimit berechnet |

Text kann nicht deaktiviert werden. Die Schalter für Sprachnachrichten und Echtzeit steuern, welche zusätzlichen Funktionen Besucher nutzen dürfen. Ein gespeicherter Echtzeit-Schalter hebt weder die Tarifberechtigung des Workspace noch eine fehlende Provider-Konfiguration auf.

## Interaktionsverhalten konfigurieren [#interaktionsverhalten-konfigurieren]

1. Öffnen Sie die Seite **Agent** der Website und suchen Sie den Bereich **Sprache**.
2. Lassen Sie **Text-Chat** aktiviert und wählen Sie **Sprachnachrichten** und/oder **Live-Echtzeit-Sprache**.
3. Wenn der Agent mehrere Sprachen unterstützt, können Sie optional die Live-Sprachspiegelung aktivieren.
4. Legen Sie das automatische Limit pro Anruf fest.
5. Wählen Sie eine Standardstimme aus.
6. Speichern Sie und testen Sie jeden aktivierten Modus separat.

Das Anruflimit akzeptiert Werte von 30 Sekunden bis 20 Minuten in Schritten von 30 Sekunden; der Standardwert beträgt 3 Minuten. Es beendet einen einzelnen Anruf und schützt das Monatskontingent, erhöht aber nicht die verbleibenden Live-Minuten des Tarifs.

## Sprachen und Stimme auswählen [#sprachen-und-stimme-auswählen]

Agenten können für Englisch, Koreanisch, Usbekisch, Russisch, Französisch, Spanisch, Deutsch und Arabisch konfiguriert werden. Die erste Sprache ist die Hauptsprache. Ein einsprachiger Agent antwortet weiterhin in dieser Sprache. Ein mehrsprachiger Text-Agent spiegelt den Besucher, sobald dieser eine der konfigurierten Sprachen verwendet.

Bei Live-Anrufen ist die Sprachspiegelung eine explizite Option, die nur bei zwei oder mehr Sprachen angezeigt wird. Ist sie deaktiviert, verwenden Live-Anrufe die Hauptsprache. Usbekische Sprache wird derzeit nur nach bestem Bemühen unterstützt, da die Sprachabdeckung der Provider weniger vollständig ist; testen Sie sie vor dem Launch mit Ihrem konkreten Provider und Ihrer Zielgruppe.

Zu den Standardstimmen gehören Optionen mit Schwerpunkt Englisch, mehrsprachige Optionen und muttersprachlich koreanische Optionen. Die Sprachbezeichnung beschreibt die kuratierte Wiedergabe, nicht eine feste Garantie. Hören Sie sich die gewählte Stimme in der Vorschau an, sofern die Vorschaufunktion im Dashboard verfügbar ist, und testen Sie Namen, Abkürzungen, Währungen, Telefonnummern und Fachbegriffe immer im echten Besucher-Ablauf.

## Provider-Schlüssel und Fallback [#provider-schlüssel-und-fallback]

Sprache erfordert mehr als einen Modellschlüssel:

* Speech-to-Text nutzt den von der Plattform konfigurierten Transkriptions-Provider.
* Sprachnachrichten und Audio-Antworten über Connectors benötigen den konfigurierten Text-to-Speech-Provider.
* Echtzeit-Anrufe benötigen den konfigurierten Echtzeit-Provider und ein Tarifkontingent.

Plattformverwaltete Sprache nutzt die von der Plattform konfigurierten Provider; Sie benötigen keinen Schlüssel. Scale-Owner können optional einen Speko-Schlüssel für Transkription und Sprachsynthese unter **Einstellungen → KI-Provider-Schlüssel** hinzufügen und [Provider-Schlüssel](/de/docs/account/provider-keys) befolgen. Live-Anrufe werden immer zum Plattformtarif abgerechnet. Ein erfolgreicher Text-Chat beweist nur den Modellpfad; er beweist weder Transkription, Sprachsynthese, Medien-Upload noch das Ausstellen von Echtzeit-Sitzungen.

## Sprach-Routing und Fallback [#sprach-routing-und-fallback]

Wählen Sie unter **Sprachmodelle** ein Modell für Transkription, Sprachsynthese und Live-Anrufe. Jede Auswahl nennt das Modell und dessen Entwickler; bei **Auto** treffen wir die Wahl. Hosting und Routing werden von Make Agent Fast verwaltet, daher gibt es keine separate Plattformauswahl. Die genaue Standardstimme kann je nach gewähltem Modell variieren.

Ist ein Sprachdienst nicht verfügbar, kann ein verfügbarer Ersatzdienst genutzt werden. Schlägt die Sprachausgabe fehl, bleibt der Text verfügbar.

Live-Anrufe streamen natives Audio vom ausgewählten Live-Provider mit dessen integrierter Stimme. Wissensabruf, Sprachregeln, Unterbrechung, Live-Minutenkontingente und Vorabbelastung für Anrufe gelten weiterhin. Live-Antworten lösen keine zusätzliche TTS-Anfrage aus.

## Sprachnachrichten testen [#sprachnachrichten-testen]

Verwenden Sie ein echtes Embed oder den Agent-Link, nicht nur eine Owner-Vorschau. Erteilen Sie den Mikrofonzugriff, nehmen Sie eine kurze Frage auf und prüfen Sie, ob die Transkription inhaltlich stimmt und die gesprochene bzw. Textantwort passt. Testen Sie anschließend:

* ruhige und laute Umgebungen;
* mobiles Safari und Chrome, sofern relevant;
* eine lange Frage nahe der öffentlichen Audio-Obergrenze von 25 MB;
* verweigerte Mikrofonberechtigung;
* nicht unterstütztes oder qualitativ schlechtes Audio;
* jede konfigurierte Sprache.

Bei eingebetteten Websites müssen die CSP und die Permissions Policy der übergeordneten Seite die Mikrofonnutzung erlauben. Siehe [Sicherheit und CSP](/de/docs/embed/security).

## Live-Gespräch auf der Plattform und auf der veröffentlichten Website [#live-gespräch-auf-der-plattform-und-auf-der-veröffentlichten-website]

Live-Gespräche verwenden dieselben Anrufsteuerungen an zwei Orten:

| Oberfläche                            | Wo                                                                                             | Erscheinungsbild                                     | Zählt als Aktivierung?                          |
| ------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------- |
| **Agent-Studio-Canvas**               | Das Live-Widget neben den Tabs auf der Seite **Agent**                                         | Das Besucher-Widget-Design, dargestellt im Dashboard | Nein – Owner-Tests aktivieren nie               |
| **Veröffentlichte Website und Embed** | `embed.js`-iframe, das Widget auf dem Agent-Link und jede übrig gebliebene gehostete Demoseite | Mandanten-/Widget-Design                             | Ja – ein Besucher-Anruf ist ein echtes Gespräch |

Der Canvas neben dem Tab **Darstellung** zeigt dasselbe Besucher-Design. Testen Sie vor dem Launch ein echtes Embed; ein erfolgreicher Dashboard-Test belegt weder die Mikrofonberechtigung des Embeds noch die CSP der Host-Seite oder die Aktivierung.

**Website verwenden** unter **Agent-Design** im Tab **Darstellung** folgt dem hellen oder dunklen Modus des Besuchers auf der Host-Seite und im Embed. Eine feste Einstellung auf Hell oder Dunkel fixiert sowohl Chat als auch Live-Anruf. Siehe [Erscheinungsbild](/de/docs/build/appearance).

## Live-Anrufe testen [#live-anrufe-testen]

Vergewissern Sie sich, dass der Tarif ungenutzte Live-Minuten hat, die Website erreichbar ist und der Schlüssel des Echtzeit-Providers validiert wird. Beginnen Sie mit einem kurzen Anruf, unterbrechen Sie den Agenten, wechseln Sie die Sprache nur bei aktivierter Spiegelung und lassen Sie das konfigurierte Anruflimit eine Testsitzung beenden. Wiederholen Sie einen Anruf in einem echten Embed, nicht nur im Canvas der Agent-Seite.

Live-Minuten sind ein vom normalen Credit-Guthaben getrenntes monatliches Kontingent. Beim Ausstellen des Live-Tokens werden Credits für die vom Server autorisierte Höchstdauer berechnet und diese Dauer wird auf das monatliche Live-Kontingent angerechnet. Da Medien direkt zwischen Browser und Provider fließen, lässt sich ein kürzerer, vom Client gemeldeter Anruf nicht verifizieren, und ungenutzte Zeit wird nach der Token-Ausgabe nicht anteilig erstattet. Serverseitige Fehler beim Ausstellen des Tokens werden freigegeben; abgebrochene Sitzungen werden mit ihrem autorisierten Limit berechnet. Beenden Sie Tests ordnungsgemäß und nutzen Sie das konfigurierte Anruflimit für Ihre Prognosen. Siehe [Credits und Nutzung](/de/docs/operate/usage).

## Aktionen bei Live-Sprache [#aktionen-bei-live-sprache]

**Agent → Aktionen → Aktionen bei Live-Anrufen** (**Agent bei Live-Anrufen Aktionen ausführen lassen**) steuert die Nutzung von Tools während Live-Anrufen, die in jeder Sprache auf Gemini 3.8 Live laufen. Die Option ist standardmäßig aktiviert (`voice.liveActions`); wenn Sie sie deaktivieren, bleibt die Wissensverankerung weiterhin verfügbar. Die Anforderungen an Live-Sprach-Tarif, Provider und Zugriff gelten weiterhin.

Anrufe können Suchergebnisse, Auswahlmöglichkeiten, Änderungsvorschläge, Kalendertermine/Buchungen, Follow-up-Beobachtungen und die Übergabe an einen Menschen (Handoff) anzeigen. Geschäftliche Änderungen, Buchungen und Beobachtungen erfordern die Schaltflächen auf den Karten im Bildschirm; ein gesprochenes oder getipptes „Ja“ bestätigt nie einen Schreibvorgang. Eine Beobachtung benötigt außerdem die E-Mail-Einwilligung auf dem Bildschirm. Karten und Tool-Ergebnisse bleiben im Gesprächsverlauf erhalten. Seitenaktionen und Ihre eigenen MCP-Tools gehören nicht zur Live-Teilmenge. Die Anrufabrechnung bleibt rein reservierungsbasiert, ohne Erstattung ungenutzter Anrufzeit nach der Token-Ausgabe.

Testen Sie vor dem Kundeneinsatz sowohl das gesprochene Ergebnis als auch die Bestätigung auf dem Bildschirm. Siehe [Follow-ups](/de/docs/build/follow-ups) und [Änderungsaktionen](/de/docs/build/change-actions).

## Offenlegung und Sicherheit [#offenlegung-und-sicherheit]

Weisen Sie Anrufer darauf hin, dass sie mit einer KI und synthetischer Sprache interagieren. Legen Sie fest, wie Aufzeichnungen, Transkripte und Daten nachgelagerter Provider aufbewahrt und gelöscht werden.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                  | Prüfen                                                                                                                |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Text funktioniert, aber die Sprachsteuerung schlägt fehl | Provider-Schlüssel für Transkription/TTS/Echtzeit, Funktionsschalter, Tarif, Credit-Guthaben und Browser-Berechtigung |
| Aufnahme lässt sich nicht starten                        | HTTPS, Mikrofonberechtigung, Audio-Eingabegerät, Permissions Policy des Embeds und Browser-Unterstützung              |
| Transkript ist ungenau                                   | Audioqualität, gewählte Sprachen, Akzent/Fachbegriffe und Abdeckung des Transkriptions-Providers                      |
| Gesprochene Antwort klingt falsch                        | Gewählte Stimme, Quelltext, Zeichensetzung, Sprachbezeichnung und Verfügbarkeit des Providers                         |
| Live-Anruf endet sofort                                  | Verbleibende Minuten, Limit pro Anruf, Provider-Schlüssel, Netzwerk und Status gleichzeitiger Sitzungen               |

Behandeln Sie Sprache als eigene Launch-Oberfläche: Abnahmetests für Text sind notwendig, aber nicht ausreichend.

---

# Discord

Source: /de/docs/connectors/discord.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/connectors/overview&#x22;, label: &#x22;Alle Connectors&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/de/docs/operate/conversations&#x22;, label: &#x22;Posteingang&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Discord&#x22;, icon: &#x22;discord&#x22; }
]"
/>

<TutorialVideo episode="ep09" start="89" />

## Discord-Anwendung erstellen [#discord-anwendung-erstellen]

Folgen Sie dem offiziellen [App-Schnellstart](https://docs.discord.com/developers/quick-start/getting-started) und der [Übersicht zu Interaktionen](https://docs.discord.com/developers/interactions/overview) von Discord. Erstellen Sie im Discord Developer Portal eine Anwendung und notieren Sie sich Folgendes:

| Feld in Make Agent Fast | Ort in Discord      | Zweck                                                                        |
| ----------------------- | ------------------- | ---------------------------------------------------------------------------- |
| **Application ID**      | General Information | Identifiziert die Anwendung und den Befehl                                   |
| **Public Key**          | General Information | Verifiziert mit Ed25519 signierte Interaktionen; genau 64 Hexadezimalzeichen |
| **Bot-Token**           | Seite „Bot“         | Validiert die Anwendung und registriert `/ask`; geheim halten                |

Wenn Sie einen Bot-Token zurücksetzen, wird der bisherige Token sofort ungültig. Der Public Key ist nicht geheim, muss aber zur selben Anwendung gehören wie der Bot-Token.

## Verbinden und `/ask` registrieren [#verbinden-und-ask-registrieren]

Öffnen Sie die Seite **Kanäle** des Agents, wählen Sie **Discord**, geben Sie die drei Werte ein und klicken Sie auf **Verbinden**.

Make Agent Fast validiert den Bot-Token über den Anwendungsendpunkt von Discord und lehnt einen Public Key ab, der nicht zur Anwendung passt. Eine falsch eingegebene Application ID wird auf die tatsächliche ID der authentifizierten Anwendung korrigiert. Anschließend wird der globale Befehl `/ask question` erstellt oder aktualisiert, ohne andere Befehle der Anwendung zu löschen.

Kopieren Sie nach dem Speichern die angezeigte **Interactions Endpoint URL** in Discord unter **General Information → Interactions Endpoint URL** und speichern Sie dort. Discord sendet einen signierten `PING`; Make Agent Fast validiert die Signatur und gibt das erforderliche `PONG` zurück.

## Installieren und testen [#installieren-und-testen]

Autorisieren Sie die App über die Installationseinstellungen von Discord auf einem Testserver mit den Berechtigungen, die für Anwendungsbefehle erforderlich sind. Die Verbreitung globaler Befehle kann einige Zeit dauern.

Führen Sie `/ask` aus, füllen Sie die erforderliche Option `question` aus und senden Sie den Befehl ab. Make Agent Fast bestätigt die Interaktion innerhalb der kurzen Frist von Discord, führt den Agent aus und bearbeitet anschließend die zurückgestellte ursprüngliche Antwort. Der Gesprächsverlauf ist pro Discord-Nutzer getrennt, sodass spätere `/ask`-Anfragen den Kontext beibehalten können.

Der aktuelle Connector unterstützt nur Text. Er liest keine Sprachkanäle, Anhänge, gewöhnlichen Kanalnachrichten oder Direktnachrichten; nur die registrierte `/ask`-Interaktion gelangt zum Agent.

## Token rotieren oder Verbindung trennen [#token-rotieren-oder-verbindung-trennen]

Wenn der Bot-Token offengelegt wurde, setzen Sie ihn in Discord zurück, aktualisieren Sie den Connector und prüfen Sie `/ask` erneut. Wenn sich die Anwendung selbst ändert, aktualisieren Sie alle drei Werte sowie die Interactions Endpoint URL für diese Anwendung.

Durch das Deaktivieren oder Entfernen des Connectors werden weder die Discord-Anwendung noch der globale Befehl gelöscht. Entfernen Sie die App von den Servern und löschen Sie nicht mehr benötigte Zugangsdaten beim Anbieter separat, wenn Sie die Anbindung stilllegen.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                | Lösung                                                                                                                                                                  |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Der Connector lehnt die Felder ab                      | Verwenden Sie den Bot-Token und den 64-stelligen Public Key derselben Anwendung                                                                                         |
| Discord lehnt den Endpunkt ab                          | Prüfen Sie, ob HTTPS öffentlich erreichbar ist, fügen Sie den generierten Endpunkt ein und speichern Sie die Zugangsdaten erneut, bevor Sie es noch einmal versuchen    |
| `/ask` fehlt                                           | Prüfen Sie Installation und Autorisierung des Befehls, warten Sie auf die globale Verbreitung und verbinden Sie den Connector erneut, um den Befehl neu zu registrieren |
| Die Interaktion meldet, die App habe nicht geantwortet | Prüfen Sie, ob der Connector aktiviert ist, und sehen Sie sich die Fehler in Make Agent Fast und Discord an; die Signaturprüfung am Endpunkt muss erfolgreich sein      |
| Andere Chatnachrichten werden ignoriert                | Das ist erwartetes Verhalten; die Integration verarbeitet nur `/ask`                                                                                                    |
| Die Antwort ist abgeschnitten                          | Discord-Nachrichtenantworten sind auf 2.000 Zeichen begrenzt                                                                                                            |

Legen Sie den Bot-Token niemals in Client-Code, Repositories, Logs oder Screenshots offen.

---

# Instagram

Source: /de/docs/connectors/instagram.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/connectors/overview&#x22;, label: &#x22;Alle Connectors&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/de/docs/operate/conversations&#x22;, label: &#x22;Posteingang&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Instagram&#x22;, icon: &#x22;instagram&#x22; }
]"
/>

<TutorialVideo episode="ep05" />

## Was dieser Connector leistet [#was-dieser-connector-leistet]

Kunden senden eine **Direktnachricht** an Ihr professionelles Instagram-Konto. Make Agent Fast antwortet mit demselben fundierten Agent wie in Ihrer Website-Einbettung, über die offizielle [Instagram API with Instagram Login](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login) von Meta.

Der Agent kann außerdem **Kommentare** zu Ihren Beiträgen und Reels beantworten, öffentlich oder per privater Direktnachricht (siehe [Kommentare und gespeicherte Antworten](#comments-and-saved-replies)). Auch Antworten auf Ihre Storys werden beantwortet (siehe [Storys](#stories)). Nicht unterstützt werden Scraping sowie das Liken von Beiträgen oder Kommentaren. Die offizielle Instagram-API bietet keine Möglichkeit, Inhalte zu liken, daher tut der Agent das nie.

Jedes Instagram-Konto ist ein eigener Channel-Eintrag, sodass Abrechnung, Posteingangs-Threads und Nachrichtenweiterleitung getrennt bleiben. Ein Agent kann bis zu fünf Instagram-Konten verwalten.

## Bevor Sie beginnen [#bevor-sie-beginnen]

Sie benötigen:

1. Ein **professionelles** Instagram-Konto (Business oder Creator). Persönliche Konten können nicht verbunden werden; wechseln Sie in Instagram unter **Einstellungen → Kontotyp und Tools**.
2. Den Instagram-Benutzernamen und das Passwort des Kontos oder eine Instagram-App, die in diesem Browser bereits bei dem Konto angemeldet ist.
3. Den Tarif Operate oder Scale, um einen neuen Channel hinzuzufügen.

Sie benötigen **kein** Facebook-Konto, keine Facebook-Seite, kein Meta-Unternehmensportfolio und keine Meta-Entwickler-App.

## Konto verbinden [#konto-verbinden]

### 1. Instagram-Karte öffnen [#1-instagram-karte-öffnen]

Öffnen Sie im Dashboard Ihren Agent und gehen Sie zu **Channels → Instagram**.

### 2. Anmelden und Zugriff erlauben [#2-anmelden-und-zugriff-erlauben]

Wählen Sie **Mit Instagram verbinden**. Instagram öffnet seine eigene Anmeldeseite. Melden Sie sich bei dem professionellen Konto an, für das der Agent antworten soll, prüfen Sie, ob das Fenster dieses Konto nennt, und wählen Sie **Zulassen**. Lassen Sie **Zugriff auf Nachrichten und deren Verwaltung** aktiviert; ohne diese Berechtigung kann der Agent keine Direktnachrichten lesen oder beantworten. **Zugriff auf Kommentare und deren Verwaltung** wird nur verwendet, wenn Sie später Kommentarantworten aktivieren.

Instagram leitet Sie zurück zur Instagram-Karte, die das Konto nun als verbunden anzeigt. Um ein weiteres Konto zu verbinden, wählen Sie erneut **Mit Instagram verbinden** und melden Sie sich bei diesem Konto an.

### 3. Testnachricht senden [#3-testnachricht-senden]

Senden Sie von einem **anderen** Instagram-Konto aus eine neue Direktnachricht an das verbundene Konto. Prüfen Sie Folgendes:

1. Die Nachricht erscheint in Ihrem Instagram-Posteingang.
2. Die Instagram-Karte zeigt ein neues Ereignis an, und unter **Unterhaltungen** gibt es einen neuen Thread.
3. Der Verifizierungsschritt auf der Karte wird bestanden.

### 4. KI-Antworten aktivieren [#4-ki-antworten-aktivieren]

Nachdem der Test bestanden wurde, aktivieren Sie auf der Karte die KI-Antworten. Ab dann beantwortet der Agent neue Direktnachrichten. Text und unterstützte Sprachnachrichten werden per Text beantwortet. Ihre eigenen Nachrichten, Bilder und andere nicht unterstützte Anhänge werden ignoriert. Wenn Sie selbst aus dem Posteingang **Unterhaltungen** antworten, pausiert der Agent für diese Unterhaltung.

## Kommentare und gespeicherte Antworten [#kommentare-und-gespeicherte-antworten]

Aktivieren Sie **Auf Kommentare antworten** im Bereich **Kommentare** der Instagram-Karte. Neue Kommentare der obersten Ebene zu Ihren Beiträgen und Reels werden dann in dieser Reihenfolge beantwortet:

1. **Ihre gespeicherten Antworten.** Verfassen Sie eine Antwort für einen Beitrag oder für **Alle Beiträge** und legen Sie die Schlüsselwörter fest, die sie auslösen (zum Beispiel `price, how much`). Lassen Sie die Schlüsselwörter leer, um jeden Kommentar zu diesem Beitrag zu beantworten. Jede gespeicherte Antwort kann eine öffentliche Antwort unter dem Kommentar posten, eine private Direktnachricht senden oder beides. `{name}` wird durch den @Handle des Kommentierenden ersetzt. Antworten, die zu einem bestimmten Beitrag gehören, haben Vorrang vor Antworten für **Alle Beiträge**, und Antworten mit Schlüsselwörtern haben Vorrang vor Pauschalantworten. Gespeicherte Antworten verwenden weder KI noch Credits.
2. **Die KI, falls Sie sie erlauben.** Wählen Sie unter **Wenn keine gespeicherte Antwort passt** zwischen **Schweigen**, **KI antwortet** (ein bis zwei kurze Sätze, öffentlich gepostet) oder **KI sendet eine Direktnachricht** (die Antwort geht an die Direktnachrichten des Kommentierenden, optional mit Ihrer öffentlichen Zeile unter dem Kommentar). Die Beitragsbeschreibung wird dem Agent als Kontext mitgegeben. KI-Antworten verbrauchen Credits wie die Antwort auf eine Direktnachricht.

Der Agent beantwortet nie seine eigenen Kommentare, antwortet nicht innerhalb eines Kommentar-Threads, ignoriert Kommentare, die nur Freunde markieren oder nur aus Emojis bestehen, und beantwortet keine Fragen, für die er keine freigegebene Antwort hat. Kommentarunterhaltungen erscheinen schreibgeschützt unter **Unterhaltungen**; antworten Sie darauf direkt in Instagram. Instagram erlaubt pro Kommentar eine private Direktnachricht, und zwar innerhalb von 7 Tagen danach.

## Storys [#storys]

Storys erreichen den Agent als Direktnachrichten:

* **Eine getippte Antwort auf Ihre Story** wird von der KI wie jede Direktnachricht beantwortet. Wenn die Story ein Foto ist, sieht der Agent es, sodass „Was kostet das?" mit einer Antwort zu dem beantwortet wird, was die Story zeigt. Video-Storys werden allein anhand des Textes beantwortet.
* **Eine Erwähnung in der Story einer anderen Person** und **eine reine Emoji-Reaktion auf Ihre Story** enthalten keine Frage, daher beantwortet die KI sie nie. Verfassen Sie im Bereich **Storys** der Instagram-Karte für jede eine kurze Antwort oder lassen Sie das Feld leer, um zu schweigen. Diese Antworten verwenden weder KI noch Credits, und dieselbe Person erhält höchstens eine Reaktionsantwort pro Tag.

Alle drei erscheinen unter **Unterhaltungen**. Instagram benachrichtigt Apps nicht, wenn jemand eine Story liked, und keine App kann Storys liken oder kommentieren.

## Verfügbarkeit [#verfügbarkeit]

**Mit Instagram verbinden** erscheint auf der Karte, sobald Meta den Instagram-Nachrichtenzugriff von Make Agent Fast genehmigt hat. Bis dahin bietet die Karte diese Option möglicherweise nicht an, und Instagram liefert nur Nachrichten von Konten, mit denen Meta die App testen lässt. Wenn Ihre Karte die Schaltfläche noch nicht anzeigt, nutzen Sie die erweiterte Methode unten oder schauen Sie später wieder vorbei.

## Trennen oder erneut verbinden [#trennen-oder-erneut-verbinden]

Make Agent Fast erneuert die Anmeldung automatisch. Wenn Antworten ausbleiben und die Karte einen Verbindungsfehler anzeigt, zum Beispiel nach einer Passwortänderung, wählen Sie **Erneut mit Instagram verbinden** und melden Sie sich noch einmal an. Zum Trennen entfernen Sie die Verbindung auf der Karte. Sie können Make Agent Fast auch in Instagram unter **Einstellungen → Apps und Websites** entfernen; der Agent antwortet dann sofort nicht mehr auf diesem Konto.

## Erweitert: Ihre eigene Meta-App [#erweitert-ihre-eigene-meta-app]

Entwickler, die eine eigene Meta-App betreiben, können sich weiterhin stattdessen mit einem Zugriffstoken einer Facebook-Seite verbinden. Dafür benötigen Sie ein professionelles Instagram-Konto, das mit einer Facebook-Seite verknüpft ist, eine Meta-Entwickler-App mit `instagram_basic`, `instagram_manage_messages`, `pages_manage_metadata`, `pages_messaging` und `pages_show_list` sowie die [Webhook-Einrichtung](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/webhooks/) von Meta.

Fügen Sie das **Seitenzugriffstoken** und das **App-Geheimnis** der App in das erweiterte Formular der Karte ein und verwenden Sie dann die dort angezeigte **Webhook-URL** und das **Verifizierungstoken** für den Instagram-Webhook (Feld `messages`). Abonnieren Sie die Seite selbst mit dem Seitentoken:

```text
POST /me/subscribed_apps?subscribed_fields=messages
```

Ihre eigene App antwortet der Öffentlichkeit erst, nachdem sie die Meta-App-Überprüfung mit erweitertem Zugriff (Advanced Access) bestanden hat.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                             | Lösung                                                                                                                               |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Keine Schaltfläche **Mit Instagram verbinden**                      | Die Genehmigung durch Meta steht noch aus; siehe [Verfügbarkeit](#availability)                                                      |
| Instagram meldet, dass das Konto nicht verwendet werden kann        | Wechseln Sie zu einem professionellen Konto (Business oder Creator) und versuchen Sie es erneut                                      |
| „Bereits mit einem anderen Agent verbunden"                         | Trennen Sie es zuerst von diesem Agent und verbinden Sie es dann hier                                                                |
| Verbunden, aber nach einer Test-Direktnachricht kein neues Ereignis | Senden Sie eine neue Direktnachricht von einem anderen Konto; vor dem Verbinden gesendete Nachrichten werden nicht erneut abgespielt |
| Eine Direktnachricht kommt an, aber es gibt keine Antwort           | Aktivieren Sie die KI-Antworten nach dem Verifizierungsschritt und prüfen Sie die Karte auf einen Fehler                             |
| Kommentare werden nicht beantwortet                                 | Aktivieren Sie **Auf Kommentare antworten** und fügen Sie eine gespeicherte Antwort hinzu oder erlauben Sie KI-Antworten             |
| Auf eine Sprachnachricht kommt eine Textantwort                     | Das ist erwartet; Sprachantworten werden auf Instagram nicht unterstützt                                                             |
| Die Karte zeigt einen Verbindungsfehler                             | Wählen Sie **Erneut mit Instagram verbinden** und melden Sie sich noch einmal an                                                     |

Geben Sie Ihr Instagram-Passwort niemals an andere weiter, auch nicht an den Support; die Verbindung nutzt die eigene Anmeldung von Instagram.

---

# KakaoTalk

Source: /de/docs/connectors/kakao.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/connectors/overview&#x22;, label: &#x22;Alle Connectors&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/de/docs/operate/conversations&#x22;, label: &#x22;Posteingang&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;KakaoTalk&#x22;, icon: &#x22;kakao&#x22; }
]"
/>

<TutorialVideo episode="ep09" start="145" />

## Checkliste für die Einrichtung [#checkliste-für-die-einrichtung]

Die KakaoTalk-Karte in Make Agent Fast zeigt diese Liste bereits mit Ihren eigenen Werten an, sodass die meisten Owner sie dort abarbeiten. Alle Schritte finden in der Kakao-Konsole statt, mit Ausnahme der beiden unten markierten Felder.

1. **Erstellen Sie einen Bot** in Kakao i Open Builder. Ein Bot enthält alle Szenarioblöcke, mit denen der Channel antwortet; überspringen Sie diesen Schritt, wenn der Channel bereits über einen Bot verfügt, den Sie bearbeiten können.
2. **Fügen Sie einen Skill hinzu** und legen Sie als URL die **Skill-URL** des Connectors fest. Ergänzen Sie dann einen benutzerdefinierten Request-Header `X-Kakao-Bot-Secret` mit Ihrem **Bot-Secret**. Kakao signiert Skill-Anfragen nicht, daher ist dieser Header der einzige Nachweis, dass ein Aufruf von Ihrem Bot stammt.
3. **Richten Sie den Fallback-Block auf den Skill aus**, sodass jede Frage, die Ihre Szenarien nicht behandeln, beim Agent ankommt. Verknüpfen Sie einen benannten Szenarioblock mit demselben Skill, wenn auch dieser vom Agent beantwortet werden soll.
4. **Aktivieren Sie die Callback-Option** für diesen Block. Kakao verwirft eine Skill-Antwort, die länger als fünf Sekunden dauert. Bei aktiviertem Callback gibt Make Agent Fast sofort eine Wartenachricht zurück und sendet die fertige Antwort innerhalb der Minute, in der wir diese einmalig verwendbare URL als gültig behandeln, an `userRequest.callbackUrl`.
5. **Verbinden Sie den KakaoTalk Channel** mit dem Bot und fügen Sie dieselbe Channel-ID anschließend in das Feld **Channel-ID** des Connectors in Make Agent Fast ein.
6. **Stellen Sie den Bot bereit (Deploy).** Änderungen in Open Builder erreichen Besucher erst nach einem Deploy, und jede spätere Änderung an einem Skill oder Block erfordert einen weiteren.

Der Rest dieser Seite ist die ausführliche Fassung derselben sechs Schritte.

## Kakao-Ressourcen vorbereiten [#kakao-ressourcen-vorbereiten]

Erstellen oder wählen Sie die Kakao-Developers-Anwendung, den KakaoTalk Channel und den Kakao i Open Builder Bot aus, die die Integration tragen sollen. Informationen zu Skills und Blöcken finden Sie in Kakaos offizieller [Open-Builder-Dokumentation](https://i.kakao.com/docs/key-concepts-block#skill).

Sammeln oder erstellen Sie diese Werte:

| Feld in Make Agent Fast | Quelle                                            | Zweck                                                               |
| ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
| **Channel-ID**          | Öffentliche bzw. Such-ID des KakaoTalk Channels   | Ordnet den Connector dem vorgesehenen Channel zu                    |
| **REST-API-Schlüssel**  | App-Schlüssel in Kakao Developers                 | Validiert die Kakao-Anwendung                                       |
| **Bot-Secret**          | Ein von Ihnen erzeugtes langes, zufälliges Secret | Authentifiziert eingehende Skill-Anfragen über `X-Kakao-Bot-Secret` |

Das Bot-Secret ist in bereitgestellten Make-Agent-Fast-Umgebungen erforderlich, weil Kakao-Skill-Aufrufe keine Plattformsignatur mitliefern. Erzeugen Sie einen eindeutigen Wert mit hoher Entropie und verwenden Sie den REST-API-Schlüssel nicht als Secret.

## Connector speichern [#connector-speichern]

Öffnen Sie die Seite **Channels** des Agents, wählen Sie **KakaoTalk Channel**, geben Sie alle drei Werte ein und klicken Sie auf **Verbinden**. Make Agent Fast validiert den REST-API-Schlüssel, soweit die Kakao-Berechtigungen dies zulassen, und zeigt nach dem Speichern die eindeutige **Webhook-URL** des Connectors an.

Make Agent Fast kann den Open-Builder-Skill nicht für Sie erstellen oder mit einem Block verknüpfen; die restlichen Schritte erledigen Sie in der Kakao-Konsole.

## Open-Builder-Skill konfigurieren [#open-builder-skill-konfigurieren]

1. Erstellen Sie in Kakao i Open Builder einen Skill für den vorgesehenen Bot.
2. Legen Sie als Skill-URL die kopierte **Webhook-URL** des Connectors fest.
3. Fügen Sie einen benutzerdefinierten Request-Header namens `X-Kakao-Bot-Secret` hinzu, dessen Wert exakt dem **Bot-Secret** entspricht.
4. Verknüpfen Sie den Skill mit dem Fallback- oder Szenarioblock, der den Agent aufrufen soll.
5. Aktivieren Sie die Callback-Option dieses Blocks, damit langsame Antworten Kakaos Skill-Frist von fünf Sekunden überstehen.
6. Speichern Sie die Bot-Konfiguration und stellen Sie sie gemäß Kakaos Ablauf bereit bzw. veröffentlichen Sie sie.

Beim Header wird laut HTTP-Regeln die Groß- und Kleinschreibung nicht unterschieden, der Wert des Secrets muss jedoch exakt stimmen. Wer die Webhook-URL kennt, nicht aber dieses Secret, sollte eine Antwort „unauthorized“ erhalten.

## Funktionen testen [#funktionen-testen]

Verwenden Sie zuerst das Testtool von Open Builder und anschließend den verbundenen KakaoTalk Channel. Senden Sie eine realistische Textfrage auf Koreanisch oder in einer anderen unterstützten Sprache und prüfen Sie die Inline-Antwort, die **Letzte Nachricht** sowie den Thread unter **Unterhaltungen**.

Die Connector-Karte kopiert den unten stehenden Request-Body; derselbe Body funktioniert mit `curl` gegen die Skill-URL. Er enthält keine `callbackUrl`, die Antwort kommt also inline zurück – das ist die einfachere Variante für den ersten Test.

```json
{
  "intent": {
    "id": "5a56ec0cf65e53002d34e0f4",
    "name": "Fallback block"
  },
  "userRequest": {
    "timezone": "Asia/Seoul",
    "utterance": "What are your opening hours?",
    "lang": "kr",
    "user": {
      "id": "kakao-test-user",
      "type": "botUserKey",
      "properties": {
        "plusfriendUserKey": "kakao-test-user"
      }
    },
    "block": {
      "id": "5a56ec0cf65e53002d34e0f4",
      "name": "Fallback block"
    }
  },
  "bot": {
    "id": "5a56ec0cf65e53002d34e0f2",
    "name": "Your bot"
  },
  "action": {
    "id": "5a56ec0cf65e53002d34e0f6",
    "name": "Make Agent Fast skill",
    "params": {},
    "detailParams": {},
    "clientExtra": {}
  }
}
```

Ein funktionierender Skill antwortet innerhalb der Fünf-Sekunden-Frist mit einer einzelnen `simpleText`-Ausgabe:

```json
{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "simpleText": {
          "text": "We are open 9:00–18:00 on weekdays."
        }
      }
    ]
  }
}
```

Sobald die Callback-Option des Blocks aktiviert ist, fügt Open Builder der Anfrage `userRequest.callbackUrl` hinzu. Make Agent Fast antwortet dann zunächst mit einer Wartenachricht und sendet die fertige Antwort per POST an diese einmalig verwendbare URL:

```json
{
  "version": "2.0",
  "useCallback": true,
  "data": {
    "text": "One moment — I am looking that up."
  }
}
```

Der aktuelle Skill-Vertrag unterstützt nur Text. Die Antwort des Agents ist eine einzelne Kakao-`skillResponse` in Version `2.0` mit einer `simpleText`-Ausgabe, die unterhalb von Kakaos Textlimit bleibt und inline oder an die Callback-URL zurückgegeben wird. Sprache, Dateien, Bilder und separate ausgehende Audioinhalte werden nicht unterstützt.

## Rotieren oder trennen [#rotieren-oder-trennen]

Um das Bot-Secret zu rotieren, aktualisieren Sie den Connector und den benutzerdefinierten Header in Open Builder in einem abgestimmten Schritt und testen Sie anschließend sofort. Eine Abweichung blockiert jede eingehende Anfrage. Rotieren Sie den REST-API-Schlüssel in Kakao Developers und in Make Agent Fast, bevor Sie den alten Schlüssel widerrufen.

Das Deaktivieren oder Entfernen des Connectors löscht weder den Open-Builder-Skill noch den Block. Entfernen oder lösen Sie diese Objekte auf Anbieterseite, wenn Sie die Integration dauerhaft außer Betrieb nehmen.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                               | Lösung                                                                                                                  |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Der Connector verlangt ein Bot-Secret                 | Erzeugen Sie eines; bereitgestellte Umgebungen lehnen einen nicht authentifizierten Kakao-Webhook ab                    |
| REST-API-Schlüssel wird abgelehnt                     | Verwenden Sie den REST-API-Schlüssel der vorgesehenen Kakao-App und prüfen Sie deren Channel-Berechtigungen             |
| Open Builder meldet „unauthorized“                    | Ergänzen bzw. aktualisieren Sie `X-Kakao-Bot-Secret`, sodass er exakt dem Wert des Connectors entspricht                |
| Das Testtool zeigt einen Fallback statt einer Antwort | Prüfen Sie, ob der Block die gespeicherte Skill-URL aufruft, und sehen Sie sich die Request-/Response-Logs von Kakao an |
| Anfragen laufen in ein Timeout                        | Aktivieren Sie die Callback-Option des Blocks; ohne sie gewährt Kakao dem Skill fünf Sekunden                           |
| Sprache oder Bilder werden ignoriert                  | Erwartetes Verhalten; der aktuelle Connector akzeptiert nur Text                                                        |

Machen Sie den REST-API-Schlüssel und das Bot-Secret weder in Client-Code noch in öffentlicher Dokumentation zugänglich.

---

# Messenger

Source: /de/docs/connectors/messenger.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/connectors/overview&#x22;, label: &#x22;Alle Connectors&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/de/docs/operate/conversations&#x22;, label: &#x22;Posteingang&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Messenger&#x22;, icon: &#x22;messenger&#x22; }
]"
/>

<TutorialVideo episode="ep09" start="31" />

## Meta-App und Seite vorbereiten [#meta-app-und-seite-vorbereiten]

Folgen Sie dem offiziellen [Einstiegsleitfaden zur Messenger Platform](https://developers.facebook.com/docs/messenger-platform/get-started) von Meta. Fügen Sie Messenger zu einer Meta-App hinzu, verbinden Sie die Facebook-Seite, die Nachrichten empfangen soll, und stellen Sie sicher, dass Ihr Konto beide Assets verwalten kann.

Erfassen Sie die Werte aus derselben App und derselben Seite:

| Feld in Make Agent Fast | Wert des Anbieters                            | Zweck                                              |
| ----------------------- | --------------------------------------------- | -------------------------------------------------- |
| **Seitenzugriffstoken** | Für die ausgewählte Seite ausgestelltes Token | Liest die Identität der Seite und sendet Antworten |
| **App-Geheimnis**       | 32-stelliges hexadezimales Meta-App-Geheimnis | Überprüft signierte eingehende Webhook-Anfragen    |

Verwenden Sie kein Benutzerzugriffstoken und kein Token, das zu einer anderen Seite gehört. Der Entwicklungs- bzw. Prüfstatus der Meta-App bestimmt, welche Personen die Integration nutzen können.

## Zugangsdaten speichern und validieren [#zugangsdaten-speichern-und-validieren]

Öffnen Sie die Seite **Channels** des Agents, wählen Sie **Messenger**, geben Sie das Seitenzugriffstoken und das App-Geheimnis ein und wählen Sie **Verbinden**.

Make Agent Fast ruft die Graph API mit `appsecret_proof` auf, ermittelt die Seiten-ID und den Seitennamen und bindet eingehende Ereignisse an genau diese Seite. Anschließend zeigt die Connector-Karte die **Webhook-URL** und das **Verify-Token** an.

## Webhook der Seite konfigurieren [#webhook-der-seite-konfigurieren]

In derselben Meta-App:

1. Öffnen Sie die Messenger-Webhook-Einstellungen.
2. Fügen Sie die **Webhook-URL** und das **Verify-Token** des Connectors ein.
3. Schließen Sie die Verifizierungsabfrage ab.
4. Wählen Sie das für den Messenger-Workflow erforderliche Abonnement für Nachrichtenereignisse.
5. Abonnieren Sie die gewünschte Facebook-Seite für die App.
6. Bestätigen Sie, dass das Seitenabonnement und der App-Modus Ihren Testnutzer zulassen.

Das Verify-Token wird nur für die erste Abfrage verwendet. Ereignisse zur Laufzeit müssen eine Signatur tragen, die zum App-Geheimnis passt. Make Agent Fast weist außerdem Ereignisse zurück, die an eine andere Seite adressiert sind, selbst wenn sie von derselben Meta-App stammen.

## Funktionen testen [#funktionen-testen]

Senden Sie von einem zugelassenen Testkonto ohne Administratorrolle eine normale Nachricht an die Seite und prüfen Sie die Antwort sowie den Thread unter **Konversationen**. Testen Sie anschließend einen Audioanhang, falls eingehende Sprachnachrichten für Ihren Workflow wichtig sind.

Text und unterstütztes eingehendes Audio werden verarbeitet. Antworten erfolgen im aktuellen Messenger-Connector ausschließlich als Text, auch wenn die ursprüngliche Nachricht eine Sprachnachricht war. Zustellungs- und Lesebestätigungen, Echos der eigenen Nachrichten der Seite, Bilder und andere nicht unterstützte Anhänge werden ignoriert.

## Produktionsreife [#produktionsreife]

Schließen Sie die Schritte zu Berechtigungen, App-Prüfung, Unternehmensverifizierung, Datenschutz-URL und Veröffentlichung der Seite ab, die Meta für Ihre Zielgruppe verlangt. Ein Erfolg im Entwicklungsmodus mit einem Konto mit App-Rolle belegt nicht, dass die Öffentlichkeit der Seiten-Integration Nachrichten senden kann.

Dokumentieren Sie die zuständige Meta-App und die Seiten-ID für Ihre Administratoren. Ein Seitentoken kann ungültig werden, wenn sich sein Inhaber, die Berechtigungen, die Business-Zuordnung oder die Richtlinien des Anbieters ändern.

## Rotieren oder trennen [#rotieren-oder-trennen]

Erzeugen Sie das neue Seitentoken, aktualisieren Sie den Connector, testen Sie mit einem zugelassenen Nutzer und machen Sie anschließend das alte Token ungültig. Aktualisieren Sie Make Agent Fast unmittelbar nach der Rotation des App-Geheimnisses.

Das Deaktivieren oder Entfernen des Connectors hebt das Abonnement der Seite bei Meta nicht auf. Entfernen Sie bei der endgültigen Außerbetriebnahme der Integration das Seitenabonnement und die nicht mehr benötigten Zugangsdaten beim Anbieter.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                      | Lösung                                                                                                                                 |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Token wird abgelehnt                                         | Prüfen Sie, ob es sich um ein Seitentoken für die vorgesehene Seite handelt und ob das App-Geheimnis zur selben App gehört             |
| Webhook-Verifizierung schlägt fehl                           | Kopieren Sie die aktuelle URL und das Verify-Token exakt; verwenden Sie öffentliches HTTPS                                             |
| Verifizierung funktioniert, aber Nachrichten kommen nicht an | Abonnieren Sie die Seite und das Nachrichtenereignis und prüfen Sie dann App-Modus, Nutzerrolle und die Zustellungsprotokolle von Meta |
| Anfragen sind nicht autorisiert                              | Korrigieren Sie das App-Geheimnis; signierte POST-Anfragen verwenden nicht das Verify-Token                                            |
| Eingehende Nachricht erscheint, aber keine Antwort           | Prüfen Sie die Gültigkeit des Seitentokens, die Messaging-Berechtigungen, Sendefehler des Anbieters und den Connector-Status           |
| Auf eine Sprachnachricht folgt eine Textantwort              | Erwartetes Verhalten; ausgehende Sprachnachrichten werden in Messenger derzeit nicht unterstützt                                       |

Zugangsdaten des Anbieters gehören ausschließlich in das authentifizierte Connector-Formular oder in einen vertrauenswürdigen serverseitigen API-Aufruf.

---

# Connector-Übersicht

Source: /de/docs/connectors/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/connectors/telegram&#x22;, label: &#x22;Telegram&#x22;, icon: &#x22;telegram&#x22; },
{ href: &#x22;/de/docs/connectors/whatsapp&#x22;, label: &#x22;WhatsApp&#x22;, icon: &#x22;whatsapp&#x22; },
{ href: &#x22;/de/docs/connectors/messenger&#x22;, label: &#x22;Messenger&#x22;, icon: &#x22;messenger&#x22; },
{ href: &#x22;/de/docs/connectors/instagram&#x22;, label: &#x22;Instagram&#x22;, icon: &#x22;instagram&#x22; },
{ href: &#x22;/de/docs/connectors/discord&#x22;, label: &#x22;Discord&#x22;, icon: &#x22;discord&#x22; },
{ href: &#x22;/de/docs/connectors/kakao&#x22;, label: &#x22;KakaoTalk&#x22;, icon: &#x22;kakao&#x22; }
]"
/>

Connectors empfangen Ereignisse von einer externen Messaging-Plattform, normalisieren Text oder unterstützte Audiodateien, führen denselben Website-Agent aus und senden eine für den jeweiligen Channel passende Antwort zurück. Jeder externe Nutzer erhält einen Channel-spezifischen Gesprächsverlauf, der unter **Konversationen** sichtbar ist.

Für das Verbinden eines **neuen** Channels ist der Tarif Operate oder Scale erforderlich. Bestehende Verbindungen funktionieren im Tarif Launch weiterhin.

<TutorialVideo episode="ep09" start="15" />

## Funktionsmatrix [#funktionsmatrix]

| Channel   | Eingehender Text | Eingehende Sprache | Ausgehender Text     | Ausgehende Sprache | Einrichtung beim Anbieter nach dem Speichern                                 |
| --------- | ---------------- | ------------------ | -------------------- | ------------------ | ---------------------------------------------------------------------------- |
| Telegram  | Ja               | Ja                 | Ja                   | Optional           | Webhook wird automatisch registriert                                         |
| WhatsApp  | Ja               | Ja                 | Ja                   | Optional           | Meta-Webhook und Abonnement für `messages` hinzufügen                        |
| Messenger | Ja               | Ja                 | Ja                   | Nein               | Meta-Webhook hinzufügen und die Seite abonnieren                             |
| Instagram | Ja               | Ja                 | Ja                   | Nein               | Meta-Instagram-Webhook hinzufügen und `messages` abonnieren                  |
| Discord   | Frage per `/ask` | Nein               | Antwort auf `/ask`   | Nein               | Interactions-Endpunkt einfügen; die Befehlsregistrierung erfolgt automatisch |
| KakaoTalk | Ja               | Nein               | Inline-Skill-Antwort | Nein               | Skill-URL, Header und Block im Open Builder hinzufügen                       |

„Sprache eingehend“ bedeutet, dass eine unterstützte Sprach- oder Audionachricht heruntergeladen und transkribiert wird. „Sprache ausgehend“ erfordert einen funktionierenden Sprachanbieter und die Option **Mit Sprache antworten** des Connectors. Nicht unterstützte Anhänge wie Bilder und Standorte werden ignoriert und nicht als Anweisungen an den Agent interpretiert.

## Vor dem Verbinden [#vor-dem-verbinden]

1. Testen Sie den vorgesehenen Agent im Dashboard. Auch ein Connector im Entwurfsstatus kann bereits antworten.
2. Sie benötigen keinen Modellschlüssel: Die Plattform stellt die Modelle bereit. Anbieterschlüssel sind optional und nur im Tarif Scale verfügbar; siehe [Anbieterschlüssel](/de/docs/account/provider-keys).
3. Erstellen Sie beim externen Anbieter eine eigene App, einen eigenen Bot, eine eigene Nummer oder einen eigenen Channel. Verwenden Sie keine Zugangsdaten wieder, die zu einer anderen Produktivintegration gehören.
4. Stellen Sie sicher, dass Ihre Bereitstellung über eine öffentliche HTTPS-Basis-URL für Connectors verfügbar ist. Webhooks von Anbietern können ohne einen sicheren Entwicklungstunnel nicht an `localhost` zugestellt werden.
5. Öffnen Sie die Seite **Channels** des Agents und wählen Sie den Channel aus.

Beim Speichern ruft Make Agent Fast den Anbieter auf, um die übermittelten Zugangsdaten zu validieren. Die Anzeige „Verbunden“ bedeutet, dass die Validierung der Zugangsdaten und eine eventuelle automatische Bereitstellung abgeschlossen wurden; sie beweist nicht, dass ein manueller Schritt in der Meta-, Discord- oder Kakao-Konsole durchgeführt wurde.

## Umgang mit Zugangsdaten [#umgang-mit-zugangsdaten]

Connector-Formulare akzeptieren Zugangsdaten von Anbietern ausschließlich aus dem authentifizierten Dashboard oder der serverseitigen Public API. Geheimnisse werden im Ruhezustand verschlüsselt und niemals in Antworten der Connector-Liste zurückgegeben. Behandeln Sie die folgenden Werte wie Passwörter:

* Telegram-Bot-Token
* Meta-Zugriffstoken und App-Secret
* Discord-Bot-Token
* Kakao-REST-API-Schlüssel und Bot-Secret

Legen Sie sie nicht in Browser-JavaScript, Screenshots, Support-Tickets oder der Versionsverwaltung ab. Die Webhook-URL und das Meta-Verify-Token sind Konfigurationswerte, die in die entsprechende Konsole des Anbieters kopiert werden sollen; sie ersetzen nicht die Zugangsdaten des Anbieters.

## Verbindung über die API [#verbindung-über-die-api]

Verwenden Sie einen serverseitig gespeicherten MAF-API-Schlüssel mit `connectors:write`. Das channelspezifische Objekt `credentials` ist ausschließlich schreibbar. Die Antwort enthält keine Geheimnisse im Klartext, aber die Webhook-URL, die für die manuelle Einrichtung beim Anbieter benötigt wird.

```bash
curl -X POST "https://makeagent.fast/api/v1/sites/$SITE_ID/connectors" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connector-telegram-v1" \
  -d '{
    "channel": "telegram",
    "credentials": { "bot_token": "'$TELEGRAM_BOT_TOKEN'" },
    "reply_with_voice": false
  }'
```

`reply_with_voice` und das optionale Feld `display_label` sind Felder auf oberster Ebene und befinden sich nicht in einem `config`-Objekt. Wenn Sie denselben Bot oder dasselbe Konto erneut speichern, werden dessen Zugangsdaten und Einstellungen aktualisiert, während das Routing-Token erhalten bleibt. Bei Telegram und Instagram fügt ein anderer Bot oder ein anderes Konto eine neue Verbindung hinzu (bis zu fünf pro Agent); bei den anderen Channels ersetzt das Speichern die bestehende Verbindung. Beachten Sie für Produktivintegrationen [API-Authentifizierung](/de/docs/api/authentication), [Scopes und Fehler](/de/docs/api/scopes-errors) sowie die [API-Referenz](/de/docs/api/reference).

## Testen und überwachen [#testen-und-überwachen]

Verwenden Sie einen Testnutzer des Anbieters und eine realistische Frage, die vom Wissen des Agents abhängt. Prüfen Sie alle folgenden Punkte:

* Der Anbieter akzeptiert oder verifiziert den Webhook-Endpunkt.
* Eine Nachricht erreicht den Agent und erhält die erwartete Antwort.
* **Letzte Nachricht** ändert sich auf der Connector-Karte.
* Der Thread erscheint unter **Konversationen** mit dem richtigen Channel.
* Etwaige Einschränkungen durch die Prüfung des Anbieters oder den Entwicklungsmodus sind vor dem öffentlichen Start bekannt.
* Sprache wird getrennt vom Text getestet, sofern der Channel sie unterstützt.

Die Connector-Karte zeigt den letzten Fehler des Anbieters oder der Zustellung an. Auch die Dashboards der Anbieter bewahren Zustellprotokolle auf; vergleichen Sie Zeitstempel und Ereignis-IDs, wenn nur eine Seite die Anfrage meldet.

## Deaktivieren, rotieren oder entfernen [#deaktivieren-rotieren-oder-entfernen]

**Deaktivieren** beendet die Verarbeitung, behält aber den Connector-Datensatz bei. Der Telegram-Webhook bleibt registriert, solange die Verbindung deaktiviert ist (Make Agent Fast ruft `deleteWebhook` nicht auf), und eingehende Nachrichten werden ignoriert; beim Aktivieren wird der Webhook erneut registriert. In der Konsole konfigurierte Abonnements beim Anbieter bleiben bestehen und sollten bei Bedarf auch dort pausiert werden. **Entfernen** löscht den Connector in Make Agent Fast und versucht, die Einrichtung beim Anbieter nach bestem Bemühen zurückzubauen, löscht aber weder die externe App noch widerruft es deren Zugangsdaten oder löscht den bestehenden Gesprächsverlauf.

Für eine Rotation erstellen Sie zunächst das neue Token beim Anbieter, aktualisieren den Connector, testen ihn und widerrufen dann das alte Token. Wurden Zugangsdaten offengelegt, widerrufen Sie sie zuerst beim Anbieter und behandeln Sie den Zeitraum als Sicherheitsvorfall.

## Häufige Fehler [#häufige-fehler]

| Symptom                                                      | Prüfen                                                                                                                                             |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zugangsdaten werden nicht validiert                          | Richtige App bzw. richtiger Bot, Token-Typ, Ablaufdatum, erforderliche Berechtigung beim Anbieter und korrekt kopierte Zeichen                     |
| Webhook-Verifizierung schlägt fehl                           | Öffentliche HTTPS-URL, exaktes Verify-Token, richtiges Anbieterprodukt und Secret zur Anfragesignierung                                            |
| Verifizierung gelingt, aber es treffen keine Nachrichten ein | Ereignisabonnement, Zuordnung von Seite/Nummer/Channel, App-Modus beim Anbieter und Aktivierungsstatus des Connectors                              |
| Text funktioniert, Sprache nicht                             | Channel-Funktionsumfang, Schlüssel für Sprache/Transkription, unterstütztes Audioformat, Medienberechtigung und Ablauf des Downloads beim Anbieter |
| Antworten bleiben nach der Rotation aus                      | Neue Zugangsdaten gespeichert, alte erst nach dem Test widerrufen und manuelles Abonnement beim Anbieter zeigt weiterhin auf diesen Webhook        |

Die genauen Felder des Anbieters und die Abfolge in der Konsole finden Sie in der jeweiligen Channel-Anleitung.

---

# Telegram

Source: /de/docs/connectors/telegram.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/connectors/overview&#x22;, label: &#x22;Alle Connectors&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/de/docs/operate/conversations&#x22;, label: &#x22;Posteingang&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Telegram&#x22;, icon: &#x22;telegram&#x22; }
]"
/>

<TutorialVideo episode="ep03" />

## Schnelleinrichtung [#schnelleinrichtung]

Wenn im Telegram-Connector **Mit QR-Code erstellen** verfügbar ist, wählen Sie diese Option, scannen Sie den QR-Code oder wählen Sie **Telegram öffnen**, und tippen Sie im Einrichtungs-Bot auf **Bot erstellen**. Kehren Sie anschließend zu Make Agent Fast zurück, prüfen Sie den Benutzernamen des Bots und wählen Sie **Diesen Bot verbinden**. Das Kopieren eines Tokens ist nicht erforderlich. Die Einrichtung läuft nach 15 Minuten ab; Sie können sie abbrechen und neu starten.

Wenn die Schnelleinrichtung nicht verfügbar ist, nutzen Sie unten **Mit einem Bot-Token verbinden**. Beide Methoden verwenden dieselben Verbindungsprüfungen und dieselbe Bestätigung beim Ersetzen.

Das Erstellungsformular schlägt den Anzeigenamen Ihres Agents sowie einen Benutzernamen im Format `maf_<agent>_<random>_bot` vor. Beides lässt sich bearbeiten; der Zufallsanteil verringert Namenskonflikte, die endgültige Verfügbarkeitsprüfung erfolgt jedoch durch Telegram. Bestehende Bots werden nicht umbenannt.

Nach der Erstellung sendet der Einrichtungs-Bot eine Schaltfläche **Diesen Bot verbinden**, die die authentifizierte Verbindungsprüfung Ihres Agents öffnet. Allein das Erstellen des Bots verbindet ihn noch nicht. Sobald die Bestätigung erfolgreich war, führt **Bot öffnen** Sie zum Test in die Unterhaltung. `/start` oder `/help` stellt eine aktive Einrichtung wieder her oder zeigt Schaltflächen für das Dashboard und die Anleitung an.

## Bot manuell erstellen und vorbereiten [#bot-manuell-erstellen-und-vorbereiten]

Folgen Sie der offiziellen Dokumentation von Telegram: [Introduction to Bots](https://core.telegram.org/bots) und [BotFather guide](https://core.telegram.org/bots/features#botfather):

1. Öffnen Sie in Telegram das verifizierte Konto **@BotFather**.
2. Führen Sie `/newbot` aus, wählen Sie einen Anzeigenamen und einen eindeutigen Benutzernamen, der auf `bot` endet.
3. Kopieren Sie das Bot-Token. Jeder, der dieses Token besitzt, kontrolliert den Bot.
4. Optional: Konfigurieren Sie vor dem Start in BotFather das Foto, die Beschreibung, den Info-Text und die lokalisierte Befehlshilfe.

Das Token gehört zur Telegram Bot API; es ist weder ein Telegram-Anmeldecode noch eine API-ID oder ein API-Hash.

## In Make Agent Fast verbinden [#in-make-agent-fast-verbinden]

Öffnen Sie die Seite **Kanäle** des Agents, wählen Sie **Telegram**, fügen Sie das **Bot-Token** ein, legen Sie fest, ob unterstützte Antworten zusätzlich gesprochen werden sollen, und wählen Sie **Verbinden**.

Make Agent Fast ruft Telegram `getMe` auf, um das Token zu prüfen und den Benutzernamen des Bots anzuzeigen. Anschließend ruft es `setWebhook` mit der öffentlichen HTTPS-URL des Connectors, einem geheimen Verifizierungstoken sowie `message`, `callback_query` und `my_chat_member` als akzeptierten Update-Typen auf. Bereits ausstehende Updates werden nicht verworfen.

Normalerweise ist kein manueller Webhook-Schritt erforderlich. Beenden Sie vor dem Verbinden jeden Polling-Dienst. Wenn der Bot einen anderen Webhook-Empfänger hat, prüfen und bestätigen Sie dessen Ersetzung; Make Agent Fast übernimmt ihn nicht stillschweigend. Ein Agent kann gleichzeitig über bis zu fünf Telegram-Bots antworten; jeder Bot ist eine eigene Verbindung. Wenn Sie einen anderen Bot speichern, wird eine neue Verbindung hinzugefügt, statt die aktuelle zu ersetzen. Ein Bot, der bereits einem anderen Agent zugeordnet ist, muss dort zuerst getrennt werden.

## Unterhaltung testen [#unterhaltung-testen]

1. Öffnen Sie den `t.me`-Link des Bots über ein Telegram-Konto, das nicht dem Owner gehört.
2. Wählen Sie **Start**; Bots können keine Unterhaltung mit einem Nutzer beginnen.
3. Senden Sie eine Textfrage, die sich aus dem Wissen beantworten lässt.
4. Senden Sie eine Sprachnachricht, falls Sprache aktiviert ist.
5. Prüfen Sie, dass Antworten eintreffen, **Letzte Nachricht** sich ändert und der Verlauf unter **Unterhaltungen** erscheint.

Private Nachrichten sind standardmäßig öffentlich: Besucher benötigen keine Freigabe durch den Owner. Antworten in Gruppen sind deaktiviert, bis der Owner **In Gruppen antworten, wenn der Bot erwähnt wird oder auf seine Nachricht geantwortet wird** aktiviert. Der Telegram-Datenschutzmodus (Privacy Mode) und die Gruppenberechtigungen gelten weiterhin. Testen Sie zuerst Direktnachrichten.

## Sprachverhalten [#sprachverhalten]

Telegram unterstützt in diesem Connector eingehende und ausgehende Sprachnachrichten. Eingehende Sprachnachrichten werden heruntergeladen und transkribiert, bevor der Agent antwortet. Ist **Mit Sprache antworten** aktiviert und steht ein Sprachanbieter zur Verfügung, sendet Make Agent Fast zusätzlich zum Text eine Sprach- bzw. Audioantwort. Schlägt die Transkription oder Sprachausgabe fehl, bitten Sie den Nutzer, es erneut als Text zu versuchen, und prüfen Sie den Connector-Fehler.

## Token rotieren, deaktivieren oder entfernen [#token-rotieren-deaktivieren-oder-entfernen]

Wenn das Token offengelegt wurde, generieren bzw. widerrufen Sie es sofort in BotFather, aktualisieren Sie den Connector mit dem neuen Token und testen Sie erneut. Beim Aktualisieren der Zugangsdaten für denselben Bot bleiben dessen Einstellungen und der Pausenstatus erhalten. Das Ersetzen durch einen anderen Bot erfordert eine Bestätigung und hält den Verlauf des vorherigen Bots getrennt.

Beim Deaktivieren werden Antworten lokal gestoppt; beim Entfernen wird die Verbindung archiviert und ihr Verlauf bleibt erhalten. Beides löscht weder den Telegram-Bot noch ruft es `deleteWebhook` auf, was einen neueren Empfänger stören könnte. Archivierte Verbindungen ignorieren eingehende Nachrichten. Per Schnelleinrichtung erstellte Bots können ihre Zugangsdaten nach Lebenszyklus-Ereignissen des Managers aktualisieren, ein pausierter Bot bleibt jedoch pausiert, und ein Wechsel der Inhaberschaft deaktiviert die Verbindung zur Prüfung.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                   | Lösung                                                                                                                                                                                    |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Token wird beim Speichern abgelehnt                       | Kopieren Sie das aktuelle Token aus BotFather; entfernen Sie Leerzeichen und stellen Sie sicher, dass es zu diesem Bot gehört                                                             |
| Nachrichten erreichen einen älteren Dienst                | Beenden Sie dort das Polling, verbinden Sie hier erneut und bestätigen Sie jede Ersetzung des Empfängers ausdrücklich                                                                     |
| Direktnachrichten funktionieren, Gruppennachrichten nicht | Aktivieren Sie Gruppenantworten, erwähnen Sie den Bot oder antworten Sie auf seine Nachricht, und prüfen Sie den Telegram-Datenschutzmodus (Privacy Mode) sowie die Gruppenberechtigungen |
| Bot schreibt einem neuen Nutzer nicht zuerst              | Erwartetes Telegram-Verhalten; bitten Sie den Nutzer, den Bot zu öffnen und **Start** zu wählen                                                                                           |
| Text funktioniert, Sprache nicht                          | Prüfen Sie die Schlüssel für Modell, Transkription und Sprachausgabe und versuchen Sie es erneut mit einer unterstützten Telegram-Sprachnachricht                                         |

Fügen Sie niemals ein aktives Token in Dokumentation, Quellcode, Analysen oder Support-Screenshots ein.

---

# WhatsApp

Source: /de/docs/connectors/whatsapp.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/connectors/overview&#x22;, label: &#x22;Alle Connectors&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/de/docs/operate/conversations&#x22;, label: &#x22;Posteingang&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;WhatsApp&#x22;, icon: &#x22;whatsapp&#x22; }
]"
/>

<TutorialVideo episode="ep04" />

## Meta-App und Nummer vorbereiten [#meta-app-und-nummer-vorbereiten]

Folgen Sie der offiziellen [Einstiegsanleitung zur WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) von Meta, um eine Meta-App zu erstellen oder auszuwählen, das WhatsApp-Produkt hinzuzufügen und ein WhatsApp-Business-Konto sowie eine Telefonnummer zuzuordnen.

Besorgen Sie sich diese drei Werte aus derselben App und für dieselbe Nummer:

| Feld in Make Agent Fast | Wert des Anbieters         | Hinweise                                                                                                                  |
| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Phone number ID**     | Numerische Phone Number ID | Dies ist weder die sichtbare Telefonnummer mit `+` noch die WABA-ID                                                       |
| **Access token**        | Cloud-API-Zugriffstoken    | Temporäre Dashboard-Tokens laufen ab; verwenden Sie für den Produktivbetrieb ein geeignetes langlebiges System-User-Token |
| **App secret**          | Meta-App-Secret            | Ein hexadezimales Secret mit 32 Zeichen, das zur Überprüfung der Webhook-Signatur dient                                   |

Erteilen Sie nur die Berechtigungen, die für die Nummer und den Messaging-Workflow erforderlich sind. Halten Sie Entwicklungs- und Test-Assets getrennt von der Produktivnummer.

## Zugangsdaten speichern und validieren [#zugangsdaten-speichern-und-validieren]

Öffnen Sie die Seite **Kanäle** des Agents, wählen Sie **WhatsApp**, geben Sie alle drei Werte ein, aktivieren Sie bei Bedarf **Mit Sprachnachricht antworten** und klicken Sie auf **Verbinden**.

Make Agent Fast validiert die Nummer über die Graph API mithilfe des Zugriffstokens und `appsecret_proof`. So werden eine falsche Nummer, ein falsches Token oder ein falsches App-Secret erkannt, bevor Webhook-Traffic eintrifft. Anschließend zeigt die Connector-Karte eine eindeutige **Webhook-URL** und ein **Verifizierungstoken** an.

## Meta-Webhook konfigurieren [#meta-webhook-konfigurieren]

Gehen Sie in derselben Meta-App wie folgt vor:

1. Öffnen Sie die WhatsApp-Webhook-Konfiguration.
2. Fügen Sie die **Webhook-URL** des Connectors als Callback-URL ein.
3. Fügen Sie das **Verifizierungstoken** des Connectors exakt ein; die Groß- und Kleinschreibung ist relevant.
4. Schließen Sie die Verifizierung ab.
5. Abonnieren Sie das WhatsApp-Business-Konto bzw. die Nummer für das Webhook-Feld `messages`.
6. Stellen Sie sicher, dass die App und die Business-Assets für die vorgesehenen Test- oder Produktivnutzer verfügbar sind.

Das Verifizierungstoken belegt den Besitz während der GET-Verifizierungsanfrage. Laufzeit-POST-Anfragen werden separat über die Signatur mit dem Meta-App-Secret authentifiziert; ersetzen Sie das eine nicht durch das andere.

## Text und Sprache testen [#text-und-sprache-testen]

Senden Sie zunächst eine Nachricht von einer zugelassenen Testnummer. Im Entwicklungsmodus von Meta können nicht registrierte Nutzer die App unter Umständen nicht erreichen. Prüfen Sie den Thread und den Kanal unter **Unterhaltungen** und beobachten Sie **Letzte Nachricht** auf der Connector-Karte.

Eingehende Text- und Sprachnachrichten werden unterstützt. Wenn **Mit Sprachnachricht antworten** aktiviert und die Sprachausgabe konfiguriert ist, lädt Make Agent Fast das generierte Audio über die Cloud API hoch und sendet es zusammen mit der Textantwort. Bilder, Standorte, Kontakte und andere nicht unterstützte Nachrichtentypen werden ignoriert.

## Produktionsreife [#produktionsreife]

Bevor Sie die Nummer bewerben, schließen Sie die für Ihren Anwendungsfall erforderlichen Schritte von Meta ab: Business-Verifizierung, App-Review, Anzeigename, Vorlagen und Messaging-Richtlinien. Diese Anforderungen werden von Meta festgelegt und können sich unabhängig von Make Agent Fast ändern.

Verwenden Sie Produktivzugangsdaten mit einem klar benannten Verantwortlichen und einem Verfahren für Ablauf und Rotation. Dokumentieren Sie, welche Meta-App, welcher System-User, welche WABA und welche Phone Number ID zu diesem Connector gehören, damit ein Administrator ihn rotieren kann, ohne raten zu müssen.

## Rotieren oder trennen [#rotieren-oder-trennen]

Erstellen Sie ein Ersatztoken mit demselben Asset-Zugriff, aktualisieren Sie den Connector, senden Sie eine Testnachricht und widerrufen Sie erst dann das alte Token. Wenn sich das App-Secret ändert, aktualisieren Sie es sofort in Make Agent Fast, da sonst jeder signierte eingehende Webhook fehlschlägt.

Das Deaktivieren oder Entfernen des Connectors kündigt das Webhook-Abonnement bei Meta nicht und löscht die Webhook-Konfiguration dort nicht. Entfernen Sie auch das Abonnement beim Anbieter, wenn Sie die Nummer endgültig außer Betrieb nehmen.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                          | Lösung                                                                                                                                                          |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zugangsdaten werden abgelehnt                                    | Prüfen Sie, ob das Token die exakte Phone Number ID lesen kann und das App-Secret aus derselben App stammt                                                      |
| Meta kann den Callback nicht verifizieren                        | Verwenden Sie die kopierte HTTPS-URL und das exakte Verifizierungstoken; stellen Sie sicher, dass der Connector noch vorhanden ist                              |
| Verifizierung erfolgreich, aber es treffen keine Nachrichten ein | Abonnieren Sie `messages` und prüfen Sie die Zuordnung von WABA und Nummer, den App-Modus, den Zugriff der Testnutzer sowie die Zustellprotokolle des Anbieters |
| Webhooks liefern „unauthorized“                                  | Geben Sie das korrekte App-Secret erneut ein; Meta-POST-Signaturen verwenden nicht das Verifizierungstoken                                                      |
| Ausgehende Antworten schlagen fehl                               | Prüfen Sie Token-Ablauf, Nummernberechtigungen, Empfängerrichtlinien bzw. Zeitfenster und Graph-API-Fehler                                                      |
| Text funktioniert, Audio nicht                                   | Prüfen Sie die API-Schlüssel für Transkription bzw. Sprachausgabe sowie den Zugriff des Tokens auf Medien-Upload und -Download                                  |

Geben Sie das Zugriffstoken und das App-Secret niemals in Browser-Code preis. Verwenden Sie die Public API nur von einem vertrauenswürdigen Server aus, wenn Sie die Erstellung von Connectors automatisieren.

---

# Astro

Source: /de/docs/embed/astro.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;Astro&#x22;, icon: &#x22;astro&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Bereitstellungs-Origin vorbereiten [#bereitstellungs-origin-vorbereiten]

Aktivieren Sie für den Make Agent Fast Agent die Option **Auf meiner Website anzeigen** (Agent-Seite → **Live schalten** → **Website-Widget**) und tragen Sie unter **Erlaubte Website-Adressen** die exakten Astro-Origins für Entwicklung, Vorschau und Produktion ein. Entscheidend sind Schema, Hostname und Port, wie sie im Browser erscheinen, nicht der Build-Host oder die Repository-URL.

## Zu einem gemeinsamen Layout hinzufügen [#zu-einem-gemeinsamen-layout-hinzufügen]

Platzieren Sie den standardmäßigen externen Loader direkt vor `</body>` in dem Astro-Layout, das den Launcher verwalten soll.

```astro
---
// src/layouts/BaseLayout.astro
---

<html lang="en">
  <body>
    <slot />

    <script
      is:inline
      src="https://makeagent.fast/embed.js?v=20261022-open"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="Ask us"
      async
    ></script>
  </body>
</html>
```

`is:inline` weist Astro an, das externe Script-Tag samt seiner `data-*`-Attribute beizubehalten, statt es zu bündeln oder zu transformieren. Der Loader bleibt öffentlich und Framework-unabhängig; importieren Sie ihn nicht in ein Servermodul.

## Auf ausgewählte Seiten beschränken [#auf-ausgewählte-seiten-beschränken]

Verwenden Sie ein verschachteltes Layout oder binden Sie das Tag nur in ausgewählten `.astro`-Seiten ein. Vermeiden Sie es, dasselbe Tag sowohl in einem Basis-Layout als auch in einer Seite zu platzieren. Der Loader ignoriert ein doppeltes Root-Element mit demselben Slug, doch das doppelte HTML erschwert es, Navigation und Abbau nachzuvollziehen.

Wenn clientseitige View Transitions von Astro aktiviert sind, testen Sie sowohl direkte Seitenaufrufe als auch die Navigation innerhalb der App. Für einen websiteweiten Agent empfiehlt sich ein persistentes gemeinsames Layout. Für routenspezifisches Verhalten entfernen Sie beim Verlassen der Route sowohl das Script als auch `maf-embed-root-YOUR_SITE_SLUG`, bevor Sie später ein neues Script einfügen.

## CSP und Einwilligung konfigurieren [#csp-und-einwilligung-konfigurieren]

Die Header Ihres statischen Hostings steuern weiterhin das Verhalten des Browsers. Erlauben Sie `https://makeagent.fast` in `script-src`, `frame-src` und der jeweils relevanten Verbindungsrichtlinie. Wenn ein Consent-Manager das Script blockiert, laden Sie das Tag erst nach der erforderlichen Einwilligung, statt die CSP abzuschwächen oder die Einwilligung zu umgehen.

## Gebaute Ausgabe überprüfen [#gebaute-ausgabe-überprüfen]

1. Führen Sie den Astro-Produktions-Build aus und prüfen Sie im erzeugten HTML, dass das Tag mit `data-agent` erhalten geblieben ist.
2. Öffnen Sie die bereitgestellte Seite in einem privaten Fenster.
3. Vergewissern Sie sich, dass es genau ein Embed-Root gibt und die Anfragen für Loader und iframe erfolgreich sind.
4. Navigieren Sie über mehrere Astro-Routen und prüfen Sie, ob die Persistenz wie vorgesehen funktioniert.
5. Senden Sie eine echte Nachricht und testen Sie das Verhalten auf Mobilgeräten sowie die Mikrofonfunktion.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                                | Lösung                                                                                       |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Das gebaute HTML lässt Attribute weg oder verändert sie                | Fügen Sie dem externen Script `is:inline` hinzu                                              |
| Es werden zwei Script-Tags ausgegeben                                  | Behalten Sie die Installation in einem einzigen zuständigen Layout bzw. einer einzigen Seite |
| Die Client-Navigation verhält sich anders als der direkte Seitenaufruf | Testen Sie View Transitions und wählen Sie ein persistentes gemeinsames Layout               |
| Funktioniert in der Entwicklung, aber nicht auf dem statischen Host    | Tragen Sie den exakten Produktions-Origin ein und setzen Sie die CSP-Header des Hostings     |
| Sprachfunktion funktioniert nicht                                      | Richten Sie HTTPS, die Browserberechtigung und die Permissions Policy ein                    |

Derzeit ist kein npm-Astro-Adapter veröffentlicht; verwenden Sie den hier gezeigten gehosteten Loader.

---

# Cafe24

Source: /de/docs/embed/cafe24.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Übersicht zur Einbettung', icon: &#x22;embed&#x22; },
{ label: &#x22;Cafe24&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

Cafe24 (카페24) ist eine koreanische Commerce-Plattform, bei der das Storefront-Design als HTML bearbeitet wird. Installieren Sie den Launcher im gemeinsamen Layout des Designs, das Sie ausspielen. Im Cafe24-App-Store gibt es derzeit keine App von Make Agent Fast. Die hier genannten Menünamen entsprechen dem Stand 2026-09; falls eine Bezeichnung verschoben wurde, suchen Sie die Einstellung anhand ihrer Funktion statt anhand des exakten Pfads.

## Loader hinzufügen [#loader-hinzufügen]

1. Öffnen Sie im Make Agent Fast Dashboard auf der Agent-Seite **Live schalten** → **Website-Widget**, aktivieren Sie **Auf meiner Website anzeigen** und tragen Sie unter **Zulässige Website-Adressen** jeden Storefront-Origin ein – die `cafe24.com`-Shop-Adresse und Ihre eigene Domain sowie die mobile Adresse, falls sie abweicht.
2. Öffnen Sie die Designverwaltung und starten Sie die HTML-Bearbeitung für das Design, das live ist. Duplizieren Sie das Design vorher oder sichern Sie es; Sie bearbeiten den Quellcode der Storefront.
3. Fügen Sie in der gemeinsamen Layoutdatei, die jede Seite einbindet, das generierte Snippet direkt vor dem schließenden `</body>`-Tag ein.
4. Speichern Sie, wenden Sie das Design auf die Storefront an und wiederholen Sie den Vorgang für das mobile Design, falls Ihr Shop PC- und Mobile-Design getrennt führt.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Wenn Sie die Layoutdatei nicht finden, fügen Sie das Snippet stattdessen in den Footer-Block Ihres Themes ein – jedes Modul, das auf jeder Seite gerendert wird, funktioniert, solange es nur einmal eingebunden ist.

## Überprüfen [#überprüfen]

1. Öffnen Sie die Storefront in einem privaten Fenster, sowohl unter der PC- als auch unter der mobilen Adresse.
2. Prüfen Sie, ob der Origin in der Adressleiste dem Origin entspricht, den Sie freigegeben haben, einschließlich `www`, falls die Domain dorthin weiterleitet.
3. Prüfen Sie, ob `embed.js` im Network-Panel `200` zurückgibt und genau ein Element `data-maf-embed="YOUR_SITE_SLUG"` vorhanden ist.
4. Stellen Sie eine realistische Frage und prüfen Sie, ob die Nachricht unter **Unterhaltungen** erscheint.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                              | Wahrscheinliche Ursache                                       | Lösung                                                                        |
| -------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Funktioniert am PC, aber nicht mobil                                 | Das mobile Design hat eine eigene Layoutdatei                 | Fügen Sie das Snippet auch dem mobilen Design hinzu                           |
| Der Launcher ist nach einer Designänderung verschwunden              | Es wurde ein Design angewendet, das das Snippet nicht enthält | Fügen Sie es erneut im Layout des Designs ein, das den Shop aktuell ausspielt |
| Der Launcher verdeckt den Warenkorb oder eine fixierte untere Leiste | Zwei fixierte Elemente teilen sich dieselbe Ecke              | Ändern Sie die Ecke des Launchers mit `data-position`                         |

Legen Sie keinen API-Schlüssel, keine Bestellnummer und keine Kundendaten in einem `data-*`-Attribut ab. [Sicherheit und CSP](/de/docs/embed/security) behandelt die Freigabe von Adressen und die Content Security Policy für Storefronts, die eine setzen.

---

# Framer

Source: /de/docs/embed/framer.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Übersicht zur Einbettung', icon: &#x22;embed&#x22; },
{ label: &#x22;Framer&#x22;, icon: &#x22;framer&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Verfügbarkeit der Code-Komponente [#verfügbarkeit-der-code-komponente]

Kopieren Sie `integrations/framer/MakeAgentFast.tsx` in eine Framer-Code-Komponente und wählen Sie den veröffentlichten Agent aus. Der Quellcode stellt Steuerelemente für die Plattform-URL, die Position und die Beschriftung bereit. Dabei handelt es sich um manuell kopierten Quellcode und nicht um eine im Framer Marketplace veröffentlichte Komponente. Eine URL zum Eintrag erscheint hier erst, nachdem ein autorisierter Owner die Komponente veröffentlicht und verifiziert hat.

## Benutzerdefinierter Code [#benutzerdefinierter-code]

Fügen Sie den Standard-Loader unter **Website-Einstellungen → Benutzerdefinierter Code** am Ende des Body-Bereichs ein.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Veröffentlichen Sie Ihre Website vor dem Testen. Der Framer-Canvas und der Vorschau-Host können andere Origins verwenden als der live veröffentlichte Hostname.

---

# Ghost

Source: /de/docs/embed/ghost.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;Ghost&#x22;, icon: &#x22;ghost&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

Öffnen Sie **Settings → Code injection** (**Einstellungen → Code-Injektion**) und fügen Sie das Skript in den Footer der Website ein.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Verwenden Sie die beitragsbezogene Code-Injektion nur dann, wenn der Agent auf ausgewählten Beiträgen erscheinen soll. Wenn Sie stattdessen ein Theme anpassen, platzieren Sie den Loader in `default.hbs` vor `</body>` und prüfen Sie ihn nach Theme-Updates erneut.

Setzen Sie den öffentlichen Ursprung der Publikation auf die Allowlist und leeren Sie den Edge-Cache, bevor Sie einen geänderten Slug testen.

---

# HTML und JavaScript

Source: /de/docs/embed/html.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;HTML&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Website vorbereiten [#website-vorbereiten]

Öffnen Sie auf der Seite **Agent** des Agenten **Live schalten** → **Website-Widget**, aktivieren Sie **Auf meiner Website anzeigen** und tragen Sie unter **Zulässige Website-Adressen** den endgültigen Origin der Host-Seite ein. Fügen Sie Entwicklung und Produktion getrennt hinzu; `http://localhost:3000`, `https://example.com` und `https://www.example.com` stimmen nicht miteinander überein.

## Skript installieren [#skript-installieren]

Fügen Sie den Loader direkt vor dem schließenden `</body>`-Tag auf jeder Seite ein, auf der der Launcher erscheinen soll. Ersetzen Sie nur den öffentlichen Site-Slug und optionale Darstellungswerte.

```html
<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>
```

`data-agent` ist erforderlich. Der Slug ist öffentlich; in dieses Tag gehört kein API-Schlüssel. Behalten Sie die `?v=`-Query aus dem Snippet im Dashboard bei. Die optionalen Attribute `data-label`, `data-accent` (`#RGB` / `#RRGGBB`), `data-locale` (`en` | `ko` | `uz` | `ru`) und `data-theme` (`light` | `dark`) sind in der [Einbettung im Überblick](/de/docs/embed/overview) beschrieben. Lassen Sie sie weg, um die gespeicherten **Anzeige**-Einstellungen und das automatische Theme-Verhalten zu übernehmen.

## Websiteweite oder seitenspezifische Platzierung wählen [#websiteweite-oder-seitenspezifische-platzierung-wählen]

Bei einer gemeinsamen serverseitigen Vorlage platzieren Sie das Skript im globalen Layout bzw. Footer. Für ausgewählte Seiten binden Sie es nur in diesen Vorlagen ein. Laden Sie denselben Slug nur einmal pro Dokument; doppelte Tags mit demselben Slug werden ignoriert, doch das Entfernen von Duplikaten hält Zuständigkeit und Abbau nachvollziehbar.

Fügen Sie das Snippet nicht in einen HTML-Sanitizer oder ein Rich-Text-Feld ein, das `<script>` entfernt. Prüfen Sie im gerenderten Seitenquelltext oder im Elements-Panel, ob das Tag weiterhin vorhanden ist.

## In einer SPA entfernen oder neu einbinden [#in-einer-spa-entfernen-oder-neu-einbinden]

Das Entfernen des Skripts nach seiner Ausführung entfernt nicht den Launcher, den es bereits erzeugt hat. Eine routenspezifische Client-Anwendung muss vor dem erneuten Einbinden sowohl das Skript als auch das slugspezifische Root-Element entfernen:

```js
const slug = "YOUR_SITE_SLUG";
document.getElementById("maf-agent")?.remove();
document.getElementById(`maf-embed-root-${slug}`)?.remove();
```

Bevorzugen Sie es, ein websiteweites Root-Element über die clientseitige Navigation hinweg eingebunden zu lassen, damit die aktive Unterhaltung nicht verloren geht. Wenn Sie das Root-Element entfernen, hängen Sie ein neues `embed.js`-Skript an, um es erneut zu erzeugen.

## Im Browser überprüfen [#im-browser-überprüfen]

1. Öffnen Sie die bereitgestellte Seite in einem privaten Fenster.
2. Vergewissern Sie sich, dass `embed.js` mit `200` antwortet und nicht durch CSP oder Consent blockiert wird.
3. Vergewissern Sie sich, dass genau ein `[data-maf-embed="YOUR_SITE_SLUG"]`-Root-Element existiert.
4. Öffnen Sie den Launcher und prüfen Sie, ob der iframe `/embed/YOUR_SITE_SLUG` lädt.
5. Senden Sie eine Frage und prüfen Sie den Thread unter **Unterhaltungen**.
6. Testen Sie die mobile Breite und die Mikrofonberechtigung, wenn Sprache aktiviert ist.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                           | Lösung                                                                                 |
| ------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Die Konsole warnt vor fehlendem `data-agent`      | Setzen Sie das Attribut auf genau das `embed.js`-Tag                                   |
| Das Skript ist vorhanden, aber der Launcher nicht | Prüfen Sie den Einbettungsschalter, den exakten Origin, die CSP und den Consent-Status |
| Funktioniert nur auf einem Hostnamen              | Fügen Sie jede tatsächliche Kombination aus Schema, Host und Port zur Allowlist hinzu  |
| Das Aussehen weicht von der Erwartung ab          | Prüfen Sie `data-accent`, `data-theme` und das gespeicherte Website-Erscheinungsbild   |
| Sprache funktioniert im iframe nicht              | Erlauben Sie das Mikrofon im Browser und in der Permissions Policy der Host-Seite      |

Leiten Sie den Loader niemals über einen Proxy um und kopieren Sie ihn nicht in einen ungeprüften lokalen Fork; verwenden Sie das gehostete Skript, damit die Origin-Validierung und Korrekturen stets aktuell bleiben.

---

# Imweb

Source: /de/docs/embed/imweb.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Übersicht zur Einbettung', icon: &#x22;embed&#x22; },
{ label: &#x22;Imweb&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

Imweb (아임웹) ist ein koreanischer Website-Baukasten, den viele kleine Shops und Studios nutzen. Installieren Sie den Launcher über die eigene Einstellung von Imweb zum Einfügen von Code. Im Imweb-Katalog gibt es keine Make Agent Fast-Anwendung. Die hier genannten Menünamen entsprechen dem Stand 2026-09. Falls eine Bezeichnung verschoben wurde, suchen Sie die Einstellung nach ihrer Funktion und nicht nach dem exakten Pfad.

## Loader hinzufügen [#loader-hinzufügen]

1. Öffnen Sie im Make Agent Fast-Dashboard auf der Agent-Seite **Put it live** → **Website widget**, aktivieren Sie **Show it on my website** und tragen Sie unter **Allowed website addresses** jeden Origin ein, den Imweb ausliefert – Ihre eigene Domain und, falls Sie sie noch verwenden, die kostenlose `imweb.me`-Adresse.
2. Öffnen Sie die Website-Einstellungen und suchen Sie den Bereich für die Code-Einfügung: die Felder, mit denen Markup in den `<head>` jeder Seite oder am Ende des Body eingefügt wird. Die Verfügbarkeit hängt von Ihrem Imweb-Tarif ab.
3. Fügen Sie das generierte Snippet in das Head-Feld ein. Der Loader ist `async`, daher funktionieren sowohl der Head-Bereich als auch das Ende des Body.
4. Speichern Sie die Änderung, übernehmen Sie sie auf der Live-Website und laden Sie den Shop anschließend in einem neuen Tab neu.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Wenn Sie diese Einstellung nicht finden, fügen Sie das Snippet stattdessen in den Footer-Block Ihres Themes ein: Ein HTML-Widget in einem Footer-Bereich wird auf jeder Seite ausgeführt, die diesen Bereich verwendet.

## Überprüfen [#überprüfen]

1. Öffnen Sie die veröffentlichte URL in einem privaten Fenster, nicht im Imweb-Editor. Der Editor- und der Vorschaumodus können eingefügte Skripte unterdrücken.
2. Prüfen Sie, ob der Origin in der Adressleiste dem Origin entspricht, den Sie freigegeben haben – einschließlich `www`, falls die Domain dorthin weiterleitet.
3. Prüfen Sie, ob `embed.js` im Netzwerk-Panel `200` zurückgibt und genau ein Element `data-maf-embed="YOUR_SITE_SLUG"` vorhanden ist.
4. Stellen Sie eine realistische Frage und prüfen Sie, ob die Nachricht unter **Conversations** erscheint.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                   | Wahrscheinliche Ursache                                                       | Lösung                                                           |
| --------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Auf der eigenen Domain wird nichts geladen                | Nur die Adresse `imweb.me` wurde freigegeben                                  | Fügen Sie zusätzlich den exakten Origin der eigenen Domain hinzu |
| Der Launcher erscheint doppelt                            | Das Snippet steht sowohl im Head-Feld als auch in einem HTML-Widget im Footer | Behalten Sie nur eine Kopie, und zwar im Head-Feld               |
| Der Launcher überlagert eine schwebende Shop-Schaltfläche | Zwei fixierte Elemente belegen dieselbe Ecke                                  | Ändern Sie die Ecke des Launchers mit `data-position`            |

Wenn der Shop ein Consent-Banner oder einen Skript-Blocker verwendet, ordnen Sie die Einbettung gemäß Ihrer Consent-Richtlinie einer Kategorie zu und laden Sie sie entsprechend. Unter [Sicherheit und CSP](/de/docs/embed/security) finden Sie die Origins, die Sie zulassen müssen.

---

# Notion und Linktree

Source: /de/docs/embed/notion-linktree.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;Notion&#x22;, icon: &#x22;notion&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

Notion-Seiten und Linktree-Profile bieten keine websiteweite Möglichkeit, beliebiges JavaScript für das schwebende Widget auszuführen. Teilen Sie stattdessen den **Agent-Link** Ihres Agents – eine öffentliche Chatseite unter der eigenen Adresse des Agents.

## Link hinzufügen [#link-hinzufügen]

1. Aktivieren Sie im letzten Schritt des Onboardings unter **Auf dem Handy testen** die Option **Agent-Link**. Derselbe Schalter befindet sich auf der Agent-Seite im Tab **Anzeige**.
2. Kopieren Sie die tatsächliche Agent-Link-URL, die Make Agent Fast anzeigt. Erfinden Sie weder den Agent-Slug noch die Domain.
3. Fügen Sie in Notion einen Link oder ein Lesezeichen hinzu, oder in Linktree einen Link wie **Chatten Sie mit unserem Agent**.
4. Öffnen Sie den Link auf Ihrem Handy. Jeder, der den Link hat, kann chatten, solange die Seite aktiviert ist. Wenn Sie sie deaktivieren, ist die Seite nicht mehr verfügbar.

Ihre Kunden-Website benötigt das Skript nicht, damit dieser Link funktioniert. Wenn Sie lieber auf Ihre eigene Website verlinken möchten, installieren Sie das Widget zuerst dort und verwenden Sie die URL dieser Seite. Ein normaler Link ist zuverlässiger, als die Seite in einen iframe einer anderen Plattform einzubetten, da dieser den Mikrofonzugriff und das Layout einschränken kann.

---

# Übersicht zur Einbettung

Source: /de/docs/embed/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/html&#x22;, label: &#x22;HTML&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/de/docs/embed/react-next&#x22;, label: &#x22;React&#x22;, icon: &#x22;react&#x22; },
{ href: &#x22;/de/docs/embed/vue-nuxt&#x22;, label: &#x22;Vue&#x22;, icon: &#x22;vue&#x22; },
{ href: &#x22;/de/docs/embed/sveltekit&#x22;, label: &#x22;SvelteKit&#x22;, icon: &#x22;svelte&#x22; },
{ href: &#x22;/de/docs/embed/astro&#x22;, label: &#x22;Astro&#x22;, icon: &#x22;astro&#x22; },
{ href: &#x22;/de/docs/embed/wordpress&#x22;, label: &#x22;WordPress&#x22;, icon: &#x22;wordpress&#x22; },
{ href: &#x22;/de/docs/embed/shopify&#x22;, label: &#x22;Shopify&#x22;, icon: &#x22;shopify&#x22; },
{ href: &#x22;/de/docs/embed/webflow&#x22;, label: &#x22;Webflow&#x22;, icon: &#x22;webflow&#x22; },
{ href: &#x22;/de/docs/embed/framer&#x22;, label: &#x22;Framer&#x22;, icon: &#x22;framer&#x22; },
{ href: &#x22;/de/docs/embed/wix&#x22;, label: &#x22;Wix&#x22;, icon: &#x22;wix&#x22; },
{ href: &#x22;/de/docs/embed/squarespace&#x22;, label: &#x22;Squarespace&#x22;, icon: &#x22;squarespace&#x22; },
{ href: &#x22;/de/docs/embed/ghost&#x22;, label: &#x22;Ghost&#x22;, icon: &#x22;ghost&#x22; },
{ href: &#x22;/de/docs/embed/notion-linktree&#x22;, label: &#x22;Notion&#x22;, icon: &#x22;notion&#x22; },
{ href: &#x22;/de/docs/embed/tilda&#x22;, label: &#x22;Tilda&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/de/docs/embed/imweb&#x22;, label: &#x22;Imweb&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/de/docs/embed/cafe24&#x22;, label: &#x22;Cafe24&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: &#x22;CSP&#x22;, icon: &#x22;shield&#x22; }
]"
/>

<TutorialVideo episode="ep02" />

## So funktioniert die Einbettung [#so-funktioniert-die-einbettung]

`embed.js` fügt dem Host-Dokument einen fest positionierten Launcher hinzu. Das Skript kann das ausgeblendete iframe von `https://makeagent.fast` vorab laden, um Seiten-Trigger vor dem ersten Klick auszuwerten. Den vollständigen Chat öffnet der Besucher über den Launcher oder einen Trigger. Das CSS der Host-Seite kann den Chat nicht umgestalten. Änderungen an der Host-Seite erfolgen ausschließlich über registrierte, vom Owner freigegebene [Page-Action-Handler](/de/docs/build/page-actions).

Der Loader ist öffentlich und verwendet **keinen** API-Key. Der Zugriff wird über den Schalter **Auf meiner Website anzeigen** des Agents und die exakte Allowlist der übergeordneten Origins (**Erlaubte Website-Adressen**) gesteuert. Der Site-Slug ist eine Kennung, kein Geheimnis.

## Voraussetzungen [#voraussetzungen]

Bevor Sie den Code kopieren:

1. Erstellen und testen Sie einen Agent im Dashboard.
2. Verwenden Sie das generierte Snippet des Agents; der separate **Agent-Link** muss dafür nicht aktiviert sein.
3. Öffnen Sie auf der Seite **Agent** Ihres Agents **Live schalten** → **Website-Widget**. Falls das Widget noch nicht aktiviert ist, wählen Sie **Einbettung aktivieren**. Prüfen Sie anschließend, ob **Auf meiner Website anzeigen** eingeschaltet ist.
4. Fügen Sie unter **Erlaubte Website-Adressen** jede übergeordnete Origin hinzu, die den Launcher darstellen soll.
5. Wählen Sie **Einbettungseinstellungen speichern** und kopieren Sie dann das generierte Snippet.

Eine Origin besteht nur aus Schema, Hostname und optional einem Port. Sie enthält nie einen Pfad. Die folgenden vier Origins sind jeweils eigenständig und müssen bei Bedarf einzeln hinzugefügt werden:

```text
https://example.com
https://www.example.com
https://staging.example.com
http://localhost:3000
```

Geben Sie nicht `https://example.com/pricing`, `*.example.com` oder einen Wildcard am Ende ein. Wenn Ihre Produktionsseite von der Domain ohne Subdomain auf `www` weiterleitet, tragen Sie die Origin ein, die nach der Weiterleitung in der Adressleiste des Browsers erhalten bleibt.

## Loader installieren [#loader-installieren]

Platzieren Sie ein einzelnes Skript vor dem schließenden `</body>`-Tag oder verwenden Sie den reinen Browser-Lebenszyklus, den Ihre Framework-Anleitung empfiehlt.

Das Fenster **Website-Widget** (Seite Agent → **Live schalten**) kopiert folgende Form (Site-Slug, Position, optionales Label und den Cache-Buster `?v=`). Behalten Sie `async` bei. Behalten Sie auch den `?v=`-Query aus dem Snippet bei, damit Hosts keinen veralteten Loader festschreiben.

```html
<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>
```

Nur `data-agent` ist erforderlich. Optionale Attribute, die der Loader tatsächlich liest:

```html
<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  data-label="Ask us"
  data-accent="#6d5ce7"
  data-locale="en"
  data-theme="light"
  async
></script>
```

Legen Sie keinen MAF-API-Key, Provider-Key, Connector-Token, keine Besucheridentität und keine privaten Kundendaten in einem `data-*`-Attribut ab. Erfinden Sie keine Attribute wie `data-api-key`, `data-z-index`, `data-offset` oder `data-delay`. `data-maf-bootstrapped` wird vom Loader gesetzt.

## Attribute konfigurieren [#attribute-konfigurieren]

Gelesen werden die Attribute ausschließlich vom `embed.js`-Tag. Das iframe akzeptiert nur Hex-Akzentfarben.

| Attribut               | Zulässiger Wert                                                                                                  | Standard                                    | Wirkung                                                                                                                                                                             |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-agent`           | Site-Slug des Agents                                                                                             | Erforderlich                                | Wählt Site und Agent aus. Fehlt es → Warnung in der Konsole, kein Launcher                                                                                                          |
| `data-position`        | `bottom-left`, `bottom-right`, `top-left`, `top-right` (`left` / `right` stehen weiterhin für die unteren Ecken) | `right` (unten rechts)                      | Alles andere wird als unten rechts behandelt                                                                                                                                        |
| `data-label`           | Reiner Text                                                                                                      | Nur Icon                                    | Sichtbarer Launcher-Text und barrierefreier Name. Maskieren Sie `"` und `<`. Die Dashboard-Oberfläche begrenzt auf 40 Zeichen                                                       |
| `data-accent`          | `#RGB` oder `#RRGGBB`                                                                                            | Gespeichertes Site-Erscheinungsbild         | Überschreibung des Launchers durch den Host; Werte, die kein Hex sind, werden im iframe ignoriert                                                                                   |
| `data-locale`          | `en`, `ko`, `uz` oder `ru`                                                                                       | Primärsprache des Agents                    | Eröffnungssprache des Agents auf dieser Host-Seite, gewählt aus den aktivierten Sprachen                                                                                            |
| `data-theme`           | `light` oder `dark`                                                                                              | Hintergrund des Hosts, sonst Betriebssystem | Andere Werte werden ignoriert                                                                                                                                                       |
| `data-auto-form-error` | `true`                                                                                                           | Aus                                         | Aktiviert Formularfehler-Trigger-Ereignisse; meldet die Formular-ID, niemals Feldwerte                                                                                              |
| `data-analytics`       | `off` (auch `false`, `0`, `no`)                                                                                  | An                                          | Verwenden Sie dies, wenn Ihr Besucher der Analyse nicht zugestimmt hat: Der Chat-Frame lädt keine Seitenanalyse und sendet kein View-Beacon. Der Chat selbst funktioniert weiterhin |

Das generierte Root-Element verwendet intern außerdem `data-maf-open`, um nachzuverfolgen, ob der Chat geöffnet ist. Es ist weder eine Einstellung des Script-Tags noch ein öffentlicher Befehl zum Öffnen des Widgets. Informationen zum Trigger-Verhalten finden Sie unter [Follow-ups](/de/docs/build/follow-ups).

Ohne `data-theme` liest der Loader den Hintergrund des Hosts aus und greift dann auf die Betriebssystemeinstellung des Besuchers zurück. Außerdem übergibt er die Schriftfamilie des Hosts an den Frame und ruft das aktuelle Erscheinungsbild des Launchers ab. Schlägt die Abfrage des Erscheinungsbilds fehl, blockiert das den Launcher nicht; er behält den sicheren Standardstil. Änderungen unter **Darstellung** im Dashboard aktualisieren diesen Abruf, ohne dass die Site neu veröffentlicht werden muss.

## Laufzeitverhalten [#laufzeitverhalten]

* Laden Sie das Skript nur einmal pro Dokument. Eine Wiederholung desselben Slugs ist idempotent und erzeugt weiterhin nur ein Root-Element `maf-embed-root-YOUR_SITE_SLUG`.
* Mehrere verschiedene Agents können in einem Dokument nebeneinander existieren. Der Loader markiert jedes verarbeitete Skript mit `data-maf-bootstrapped`, sodass ein asynchroner Fallback jedes eindeutige `data-agent`-Tag genau einmal initialisiert.
* Das iframe kann für Seiten-Trigger vorab geladen werden. Es bleibt ausgeblendet, bis ein Trigger erscheint oder der Besucher den Chat öffnet; Sitzungen, die bereits einen Trigger genutzt haben, behalten den Lazy-Open-Pfad. Mikrofon, Autoplay und Schreibzugriff auf die Zwischenablage unterliegen weiterhin dem iframe-Berechtigungsmodell des Browsers.
* Binden Sie den Loader in einer clientseitig gerouteten App im höchsten Layout ein, das ihn besitzen soll, damit Routenwechsel die Unterhaltung nicht neu laden.
* Das bloße Entfernen des Script-Elements entfernt einen bereits erzeugten Launcher nicht. Entfernen Sie für einen routenspezifischen Abbau zusätzlich das passende `maf-embed-root-...`-Element. Laden Sie das Skript nach dem Abbau erneut, um es wieder einzubinden.
* Frame und Loader tauschen Nachrichten mit Namespace zu Lebenszyklus, Identität, Triggern und Page-Actions aus. Der Loader weist Nachrichten zurück, die nicht von der Make-Agent-Fast-Origin und dem aktuellen Site-Slug stammen.

## Installation überprüfen [#installation-überprüfen]

Testen Sie die veröffentlichte Seite, nicht nur die Editor-Vorschau eines Website-Builders:

1. Öffnen Sie die bereitgestellte URL in einem privaten Fenster und bestätigen Sie, dass ihre exakte Origin in der Allowlist steht.
2. Bestätigen Sie im Network-Panel, dass `https://makeagent.fast/embed.js?v=20261022-open` den Status `200` zurückgibt.
3. Bestätigen Sie, dass genau ein Element mit `data-maf-embed="YOUR_SITE_SLUG"` existiert.
4. Öffnen Sie den Launcher und bestätigen Sie, dass die iframe-Anfrage an `/embed/YOUR_SITE_SLUG` erfolgreich ist.
5. Senden Sie eine realistische Frage und bestätigen Sie, dass sie unter **Unterhaltungen** erscheint.
6. Testen Sie einen schmalen mobilen Viewport und, falls aktiviert, die Mikrofonberechtigung.

## Fehlenden Launcher diagnostizieren [#fehlenden-launcher-diagnostizieren]

| Symptom                                              | Wahrscheinliche Ursache                                            | Lösung                                                                                           |
| ---------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Die Konsole warnt `missing data-agent`               | Das Slug-Attribut fehlt oder steht an einem anderen Skript         | Setzen Sie `data-agent` auf das `embed.js`-Tag                                                   |
| `embed.js` wird blockiert                            | CSP oder ein Consent-Manager hat das Skript abgelehnt              | Erlauben Sie die Skript-Origin oder laden Sie es nach der erforderlichen Einwilligung            |
| Der Launcher erscheint, aber der Frame lädt nicht    | Die Einbettung ist aus oder die übergeordnete Origin weicht ab     | Prüfen Sie **Auf meiner Website anzeigen** und **Erlaubte Website-Adressen** im Dashboard erneut |
| Funktioniert auf localhost, aber nicht in Produktion | Nur die Entwicklungs-Origin steht in der Allowlist                 | Fügen Sie die exakte HTTPS-Origin der bereitgestellten Seite hinzu                               |
| Zwei verschiedene Agents erscheinen                  | Das Dokument lädt zwei verschiedene Slugs                          | Behalten Sie nur den vorgesehenen Site-Slug                                                      |
| Chat öffnet sich, aber Sprache funktioniert nicht    | Browserberechtigung oder Permissions Policy blockiert das Mikrofon | Folgen Sie [Sicherheit und CSP](/de/docs/embed/security)                                         |

## Installationsanleitung auswählen [#installationsanleitung-auswählen]

Verwenden Sie [HTML und JavaScript](/de/docs/embed/html) für ein normales Script-Tag. Für React, Vue, SvelteKit, Astro, WordPress, Shopify, Webflow, Framer, Wix, Squarespace oder Ghost wählen Sie die passende Anleitung in der Seitenleiste. Plattformen, die kein beliebiges JavaScript erlauben, wie viele Notion- und Linktree-Oberflächen, können auf den **Agent-Link** des Agents verweisen – eine öffentliche Chatseite unter der eigenen Adresse des Agents, die im letzten Onboarding-Schritt (**Auf dem Smartphone testen**) und auf dem Tab **Darstellung** der Agent-Seite aktiviert wird. Eine andere Möglichkeit ist eine Kunden-Website mit der Einbettung.

## Für Coding-Agents [#für-coding-agents]

Installieren Sie dies mit Claude Code, Cursor oder Codex auf der Website eines Kunden? Kopieren Sie `skills/embed-agent/SKILL.md` aus dem Make-Agent-Fast-Repository nach `.cursor/skills/embed-agent/` oder `.claude/skills/embed-agent/`. Diese Datei ist das Installationsrezept (Attribute, CSP, Platzierung). Diese Seite bleibt die Anleitung für Menschen.

---

# React und Next.js

Source: /de/docs/embed/react-next.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Embed-Übersicht', icon: &#x22;embed&#x22; },
{ label: &#x22;React&#x22;, icon: &#x22;react&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Origins und Geltungsbereich vorbereiten [#origins-und-geltungsbereich-vorbereiten]

Aktivieren Sie für den Agenten die Option **Auf meiner Website anzeigen** (Agent-Seite → **Live schalten** → **Website-Widget**) und tragen Sie unter **Erlaubte Website-Adressen** die exakten Origins für lokale Entwicklung, Vorschau und Produktion ein. Legen Sie fest, ob der Launcher jede clientseitige Navigation überdauern soll (Root-Layout) oder nur unter ausgewählten Routen existieren soll (verschachteltes Layout bzw. verschachtelte Komponente).

## Next.js App Router [#nextjs-app-router]

Verwenden Sie `next/script` in einer Komponente, die von dem Layout gerendert wird, das den Launcher verwaltet. Der Slug darf öffentlich sein; verwenden Sie jedoch keinen API-Schlüssel und keine geheime Umgebungsvariable.

```tsx
import Script from "next/script";

export function AgentEmbed() {
  return (
    <Script
      id="maf-agent"
      src="https://makeagent.fast/embed.js?v=20261022-open"
      strategy="afterInteractive"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="Ask us"
    />
  );
}
```

Rendern Sie `<AgentEmbed />` genau einmal in `app/layout.tsx` für einen websiteweiten Agenten oder in einem verschachtelten Layout für eine Route Group. Rendern Sie nicht aus jeder Seitenkomponente eine eigene Kopie. `afterInteractive` vermeidet serverseitigen DOM-Zugriff und blockiert das initiale Parsen des HTML nicht.

Rendern Sie im Next.js Pages Router dieselbe Komponente für ein websiteweites Verhalten einmalig in `pages/_app.tsx`. Das Rendern in einer einzelnen Seite ist nur dann sinnvoll, wenn der Agent beim Verlassen dieser Seite verschwinden soll. Verwenden Sie in diesem Fall das unten beschriebene explizite Effect-/Cleanup-Muster, da ein geladenes externes Skript bereits DOM-Elemente außerhalb des React-Baums erzeugt hat.

## React ohne Next.js [#react-ohne-nextjs]

Erstellen Sie das Skript in einem Effect. Eine stabile Skript-ID verhindert doppeltes Einfügen im Strict Mode während der Entwicklung. Wenn die Komponente routenbezogen ist, muss das Cleanup sowohl das Skript als auch das vom Loader erzeugte Root-Element entfernen.

```tsx
import { useEffect } from "react";

const slug = "YOUR_SITE_SLUG";

export function AgentEmbed() {
  useEffect(() => {
    if (document.getElementById(`maf-embed-root-${slug}`)) return;

    const script = document.createElement("script");
    script.id = "maf-agent";
    script.src = "https://makeagent.fast/embed.js?v=20261022-open";
    script.dataset.agent = slug;
    script.dataset.position = "right";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  }, []);

  return null;
}
```

Binden Sie diese Komponente für einen websiteweiten Launcher oberhalb des Routers ein und verzichten Sie auf ein routenabhängiges Unmounten. Wenn das Root-Element erhalten bleibt, bleiben auch das iframe und die Unterhaltung über Navigationen hinweg bestehen.

## Umgebungskonfiguration [#umgebungskonfiguration]

Eine öffentliche Variable zur Build-Zeit darf den **Slug** enthalten, da er nicht geheim ist. Validieren Sie ihn vor dem Rendern und halten Sie echte MAF-API-Schlüssel und Zugangsdaten von Anbietern ausschließlich auf dem Server. Fehlt der Slug, gibt der Loader eine Warnung aus und beendet sich, statt einen Launcher zu erstellen.

Wenn Ihre Anwendung aus einem einzigen React-Build verschiedene Kunden-Mandanten bedient, wechseln Sie `data-agent` nicht bei einem bereits ausgeführten Skript. Weisen Sie dem aktuellen Mandanten genau einen stabilen Slug zu, entfernen Sie bei einem authentifizierten Mandantenwechsel das Root-Element des alten Slugs und binden Sie anschließend ein neues Skript ein. Lassen Sie niemals einen nicht vertrauenswürdigen Query-Parameter einen mandantenübergreifenden Slug auswählen.

## Hydration und Navigation überprüfen [#hydration-und-navigation-überprüfen]

1. Rufen Sie eine öffentliche Route direkt auf und prüfen Sie, dass genau ein Launcher erscheint.
2. Navigieren Sie clientseitig durch Routen, auf denen der Launcher erhalten bleiben soll.
3. Navigieren Sie bei einer verschachtelten bzw. routenbezogenen Installation aus dem Bereich heraus und prüfen Sie, dass Skript und Root-Element verschwinden. Navigieren Sie dann zurück und prüfen Sie, dass genau ein neuer Launcher erscheint.
4. Prüfen Sie Network und CSP und testen Sie eine echte Nachricht.
5. Führen Sie den Produktions-Build aus; der Strict Mode in der Entwicklung allein bildet nicht das endgültige Verhalten ab.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                               | Lösung                                                                                                   |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `document is not defined`                             | DOM-Code wurde während SSR ausgeführt; verlagern Sie ihn in `useEffect` oder verwenden Sie `next/script` |
| Zwei Launcher/Agenten erscheinen                      | Mehrere Slugs oder Komponenten sind eingebunden; behalten Sie ein einziges verantwortliches Layout bei   |
| Launcher bleibt nach dem Verlassen der Route bestehen | Entfernen Sie im Cleanup `maf-embed-root-SLUG`, nicht nur das Skript                                     |
| Launcher verschwindet bei jeder Navigation            | Binden Sie ihn weiter oben im Layout-/Router-Baum ein                                                    |
| Funktioniert lokal, aber nicht in Vorschau/Produktion | Tragen Sie die exakte Origin jedes Deployments in die Zulassungsliste ein                                |

Derzeit wird kein npm-Adapter für React/Next veröffentlicht; diese Beispiele verwenden den unterstützten öffentlichen Loader, der keine REST-API benötigt.

---

# Sicherheit und CSP

Source: /de/docs/embed/security.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; },
{ href: &#x22;/de/docs/build/appearance&#x22;, label: 'Erscheinungsbild', icon: &#x22;spark&#x22; }
]"
/>

## Origin-Allowlist [#origin-allowlist]

Die Einbettung schlägt standardmäßig fehl (Fail-Closed), sofern sie nicht aktiviert ist und die exakte übergeordnete Origin des Browsers zugelassen wurde. Eine Origin hat das Format `scheme://hostname[:port]`; Pfade und Query-Strings gehören nicht dazu.

| Host-Seite                              | Wert in der Allowlist              |
| --------------------------------------- | ---------------------------------- |
| `https://example.com/pricing`           | `https://example.com`              |
| `https://www.example.com/help`          | `https://www.example.com`          |
| `https://preview.example.com:8443/demo` | `https://preview.example.com:8443` |
| `http://localhost:3000`                 | `http://localhost:3000`            |

Fügen Sie Produktions-, Vorschau- und lokale Origins jeweils separat hinzu. Fügen Sie keinen Platzhalter (Wildcard) hinzu, um einen Installationsfehler zu beheben: Andernfalls könnte jeder, der einen öffentlichen Slug kopiert, den Agent einbetten und die Credits der Website verbrauchen.

## Content Security Policy [#content-security-policy]

Der Loader benötigt die Berechtigung für Skripte, das Widget die Berechtigung für Frames, und die Erscheinungsbild-Anfrage des Loaders benötigt unter Umständen die Berechtigung für Verbindungen. Führen Sie diese Quellen mit den bestehenden Direktiven des Hosts zusammen; ersetzen Sie eine ausgereifte Richtlinie nicht durch dieses minimale Beispiel.

```http
Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;
```

Wenn die Website `script-src-elem` verwendet, fügen Sie `https://makeagent.fast` auch dort hinzu. Der externe Loader benötigt kein `unsafe-inline`, das Framework des Hosts kann jedoch eigene Anforderungen an Nonces oder Hashes haben. Während der Tests ist eine Report-Only-Richtlinie hilfreich:

```http
Content-Security-Policy-Report-Only:
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;
```

Wenn die Browser-Konsole einen CSP-Verstoß meldet, ändern Sie die genannte Direktive – nicht pauschal `default-src` – und testen Sie die öffentliche Seite erneut.

## Mikrofon und Browser-Berechtigungen [#mikrofon-und-browser-berechtigungen]

Der Loader erstellt das iframe mit `allow="microphone; autoplay; clipboard-write"`. Eine strengere Permissions Policy auf Host-Ebene kann diese Berechtigung dennoch überschreiben. Wenn Sprache aktiviert ist, erlauben Sie die Frame-Origin von Make Agent Fast in der Antwort des Hosts:

```http
Permissions-Policy: microphone=(self "https://makeagent.fast")
```

Der Besucher muss außerdem den Mikrofonzugriff im Browser gewähren. Testen Sie über HTTPS; Browser schränken den Mikrofonzugriff auf unsicheren öffentlichen Origins in der Regel ein. Der Text-Chat benötigt keine Mikrofonberechtigung.

## Grenze für Nachrichten und Frames [#grenze-für-nachrichten-und-frames]

Der Loader akzeptiert nur `maf:ready`, `maf:open`, `maf:close` sowie Theme-Lebenszyklusnachrichten, die dem aktuellen Site-Slug zugeordnet sind. Eingehende Frame-Nachrichten werden gegen `https://makeagent.fast` geprüft. Kopieren Sie den Loader nicht in Ihr eigenes Bundle und entfernen Sie diese Origin-Validierung nicht.

Code auf der Host-Seite sollte nicht versuchen, auf das DOM des iframes zuzugreifen. Der Frame ist bewusst Cross-Origin; die unterstützte Integrationsschnittstelle besteht aus dem Loader, seinen dokumentierten `data-*`-Attributen und den unten beschriebenen Identitätsmethoden.

## Geheimnisse und Besucheridentität [#geheimnisse-und-besucheridentität]

Der Site-Slug und die Loader-URL sind öffentlich. Alles andere gehört nicht in den Seitenquelltext:

* Fügen Sie dem Snippet niemals einen MAF-API-Schlüssel, OAuth-Token, KI-Anbieter-Schlüssel, Connector-Token oder ein Webhook-Geheimnis hinzu.
* Binden Sie niemals ein Geheimnis in ein JavaScript-Bundle ein und machen Sie es nicht über `NEXT_PUBLIC_*`, `VITE_*` oder ähnliche Umgebungsvariablen im Browser zugänglich.
* Verwenden Sie eine serverseitige API-Integration, wenn Ihre Anwendung Sites erstellen, Agents aktualisieren oder private Workspace-Daten abrufen muss.
* Legen Sie keine E-Mail-Adressen, Konto-IDs oder anderen Besucherdaten in `data-label`, `data-locale` oder Query-Parametern ab.

## Angemeldete Kunden identifizieren [#angemeldete-kunden-identifizieren]

Erstellen Sie unter **Agent → Aktionen → Angemeldete Kunden** ein Geheimnis und kopieren Sie es, sobald es angezeigt wird. Speichern Sie es ausschließlich auf Ihrem Server als `MAF_SECRET_KEY`; legen Sie es niemals in Browser-Code, öffentlichen Umgebungsvariablen oder einem Repository ab. Dieses Agent-Geheimnis ist von einem Workspace-API-Schlüssel getrennt. Eine Rotation macht alte Tokens ungültig und ändert den Signaturschlüssel für [Lookups](/de/docs/build/lookups); das Entfernen deaktiviert die verifizierte Kundenidentität und Lookups, bis erneut ein Geheimnis konfiguriert wird.

Verwenden Sie in Ihrem bestehenden Snippet die aktualisierte Loader-URL `https://makeagent.fast/embed.js?v=20261022-open`. Ältere versionierte URLs können bis zu einem Jahr im Cache bleiben und stellen dieses SDK nicht bereit. Behalten Sie Ihre Origin-Allowlist und die CSP-Schutzmaßnahmen bei.

Ihr authentifizierter Server sollte das Token anhand des Kunden aus seiner eigenen Sitzung ausstellen. Akzeptieren Sie niemals eine beliebige Kunden-ID aus dem Browser als zu signierende Identität. Dieser Helper läuft **ausschließlich auf dem Server**:

```js
import { createHmac } from "node:crypto";

export function signCustomerIdentity(customer) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
  const now = Math.floor(Date.now() / 1000);
  const header = encode({ alg: "HS256", typ: "JWT" });
  const payload = encode({
    sub: customer.id,
    email: customer.email,
    name: customer.name,
    iat: now,
    exp: now + 3600,
  });
  const body = `${header}.${payload}`;
  const signature = createHmac("sha256", secret).update(body).digest("base64url");
  return `${body}.${signature}`;
}
```

Der Header muss `alg: "HS256"` und `typ: "JWT"` enthalten. `sub` ist ein stabiler, nicht leerer String mit bis zu 128 Zeichen; `exp` ist ein ganzzahliger Unix-Zeitstempel in Sekunden, der in der Zukunft liegt und höchstens 24 Stunden voraus ist. Das optionale `iat` ist eine ganze Zahl; das optionale `email` muss gültig sein und darf höchstens 160 Zeichen lang sein; das optionale `name` darf höchstens 120 Zeichen lang sein. Das vollständige Token darf höchstens 2.048 Zeichen umfassen. Lassen Sie optionale Claims weg, die Sie nicht benötigen. JWT-Payloads sind signiert, aber nicht verschlüsselt.

Geben Sie das Token ausschließlich über HTTPS und mit `Cache-Control: no-store` an diese authentifizierte Browsersitzung zurück. Protokollieren Sie es nicht, fügen Sie es nicht zu URLs hinzu und speichern Sie es nicht in localStorage. Übergeben Sie nach dem Laden von `embed.js` das Token aus dieser Antwort an das Widget:

```js
window.MakeAgentFast.identify(token);
```

Für die Initialisierung, bevor der Loader ausgeführt wird, setzen Sie stattdessen `window.MakeAgentFastSettings = { identityToken: token }` im Bootstrap Ihrer Anwendung. Der Loader behält das aktuelle Token im Arbeitsspeicher und leitet es weiter, sobald der Frame bereit ist. Erneuern Sie das Token von Ihrem authentifizierten Server vor Ablauf und rufen Sie `identify` erneut auf. Jede Chat-Anfrage enthält es; Konversationsanfragen verwenden `x-maf-identity`. Eine verifizierte Host-Identität stützt sich nie auf ein `af_xid`-Cookie.

Wenn sich Ihre Anwendung abmeldet, rufen Sie Folgendes auf, bevor der Chat eines anderen Kontos angezeigt wird, und löschen Sie jedes Bootstrap-Token, das Ihre Anwendung zwischengespeichert hat:

```js
window.MakeAgentFast.logout();
```

Dadurch werden die Widget-Identität und der lokale Konversations-Cache zurückgesetzt; der Kunde wird dadurch nicht aus Ihrer eigenen Anwendung abgemeldet und ein kopiertes Token wird nicht widerrufen. Auch das `sub` eines anderen Kunden leert den Widget-Cache. Ungültige, abgelaufene oder für einen anderen Agent ausgestellte Tokens können nicht auf den Verlauf dieses angemeldeten Kunden zugreifen und fallen auf den normalen Besucherpfad zurück. Verwenden Sie kurze Ablaufzeiten und halten Sie die Geheimnisse der einzelnen Agents getrennt. Die Owner-Probe ignoriert Identitäts-Tokens; prüfen Sie die Isolierung in der tatsächlichen Einbettung mit zwei separaten Testkonten.

## Einwilligung, Datenschutz und Aufbewahrung [#einwilligung-datenschutz-und-aufbewahrung]

Stufen Sie die Einbettung gemäß Ihrer Datenschutz- und Einwilligungsrichtlinie ein. Wenn Ihr Consent-Manager nicht notwendige Skripte von Drittanbietern blockiert, laden Sie `embed.js` erst nach der entsprechenden Einwilligung. Zeigen Sie bis dahin einen normalen Link oder einen deaktivierten Platzhalter an, anstatt den Manager zu umgehen.

Informieren Sie Besucher, wenn die Anwendung KI, Mikrofonaufnahme, Lead-Erfassung, Analysen oder einen externen Messaging-Anbieter nutzt, soweit dies Ihre Richtlinie und das geltende Recht verlangen. Klären Sie vor dem Start den Prozess für die Aufbewahrung und Löschung von Konversationen auf Ihrer Website; das Trennen oder Entfernen der Einbettung löscht bestehende Konversationen nicht von selbst.

## Sicherheits-Checkliste für den Livegang [#sicherheits-checkliste-für-den-livegang]

* Die Kunden-Website ist bereitgestellt, und der eingebettete Agent ist aktiviert und getestet.
* Nur exakte, vorgesehene übergeordnete Origins stehen in der Allowlist.
* Die CSP des Hosts erlaubt das Skript, den Frame und die Erscheinungsbild-Anfrage ohne breite Platzhalter.
* Das Mikrofon ist nur erlaubt, wenn Sprache aktiviert und über HTTPS getestet wurde.
* Kein Zugangsdatum und kein privater Besucherwert erscheint in HTML, Bundle-Ausgabe oder Browser-Logs.
* Das Verhalten des Consent-Managers wurde vor und nach der Einwilligung getestet.
* Ein kopiertes Snippet schlägt auf einer Origin fehl, die nicht in der Allowlist steht.

---

# Shopify

Source: /de/docs/embed/shopify.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;Shopify&#x22;, icon: &#x22;shopify&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Verfügbarkeit der Theme-Extension [#verfügbarkeit-der-theme-extension]

Der Quellcode der Theme-App-Extension befindet sich in `integrations/shopify`. Es handelt sich um eine Entwicklungsvorlage und nicht um eine öffentliche Anwendung im Shopify App Store. Ein autorisiertes Partner-Konto muss die Extension in eine App-Hülle einbinden, bereitstellen und die Shopify-Prüfung abschließen, bevor Händler sie aus dem App Store installieren können.

## Custom Liquid [#custom-liquid]

Fügen Sie unter **Onlineshop → Themes → Anpassen** einen Custom-Liquid-Block hinzu, sofern dies unterstützt wird, oder bearbeiten Sie `theme.liquid` und platzieren Sie das Skript vor `</body>`.

```liquid
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Setzen Sie den kanonischen Storefront-Origin auf die Allowlist. Hostnamen der Vorschau können von der Live-Domain `myshopify.com` oder dem eigenen Live-Hostnamen des Shops abweichen und müssen zum Testen separat hinzugefügt werden.

## Theme-Änderungen [#theme-änderungen]

Prüfen Sie die App-Einbettung nach der Veröffentlichung eines neuen Themes erneut. Testen Sie den Launcher im Zusammenspiel mit Warenkorb-Drawern, Consent-Bannern und der mobilen Navigation, damit sich fixierte Elemente nicht überlappen.

---

# Squarespace

Source: /de/docs/embed/squarespace.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;Squarespace&#x22;, icon: &#x22;squarespace&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

Für einen websiteweiten Launcher fügen Sie das Snippet unter **Einstellungen → Erweitert → Code-Injection → Footer** ein, sofern Ihr Squarespace-Tarif dies unterstützt.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Für ausgewählte Seiten verwenden Sie einen unterstützten Code-Block oder eine seitenspezifische Injection. Testen Sie nach dem Speichern und auf der öffentlichen Domain; im Editor-Modus können benutzerdefinierte Skripte unterdrückt werden.

Wenn eine Cookie-Consent-Konfiguration Skripte von Drittanbietern blockiert, kategorisieren und laden Sie die Einbettung gemäß Ihrer Consent-Richtlinie.

---

# SvelteKit

Source: /de/docs/embed/sveltekit.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;SvelteKit&#x22;, icon: &#x22;svelte&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Origin vorbereiten [#origin-vorbereiten]

Aktivieren Sie für den Agent die Option **Auf meiner Website anzeigen** (Agent-Seite → **Live schalten** → **Website-Widget**) und tragen Sie unter **Zulässige Website-Adressen** jede exakte SvelteKit-Origin für Entwicklung, Vorschau und Produktion ein. Verwenden Sie ein Root-Layout für einen websiteweiten Launcher oder eine verschachtelte Layout-/Seitenkomponente für ausgewählte Routen.

## Komponente erstellen [#komponente-erstellen]

`onMount` wird nur im Browser ausgeführt. Geben Sie eine Cleanup-Funktion zurück, wenn das zugehörige Layout bzw. die Komponente unmounted werden kann.

```svelte
<script lang="ts">
  import { onMount } from "svelte";

  const slug = "YOUR_SITE_SLUG";

  onMount(() => {
    if (document.getElementById(`maf-embed-root-${slug}`)) return;

    const script = document.createElement("script");
    script.id = "maf-agent";
    script.src = "https://makeagent.fast/embed.js?v=20261022-open";
    script.dataset.agent = slug;
    script.dataset.position = "right";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  });
</script>
```

Binden Sie die Komponente einmalig in `src/routes/+layout.svelte` für die gesamte Anwendung ein. Platzieren Sie sie bei einer Routengruppe in der `+layout.svelte` dieser Gruppe; das Cleanup entfernt den Launcher, sobald der Besucher die Gruppe verlässt.

## Konfiguration sicher verwenden [#konfiguration-sicher-verwenden]

Der öffentliche Website-Slug kann ein öffentlicher SvelteKit-Umgebungswert sein, da er keine Zugangsdaten darstellt. Verwenden Sie weder `$env/static/public` noch Browsercode für MAF-API-Schlüssel, Schlüssel von KI-Anbietern oder Connector-Secrets. Halten Sie diese in reinen Server-Modulen bzw. Server-Routen.

## Konversationsstatus beibehalten oder zurücksetzen [#konversationsstatus-beibehalten-oder-zurücksetzen]

Wenn die Komponente im Root-Layout bleibt, bleibt dasselbe iframe über die clientseitige Navigation hinweg erhalten. Ein routenbezogenes Cleanup verwirft dieses iframe und seinen aktuellen Status auf der Seite bewusst. Entscheiden Sie sich für ein Verhalten, anstatt die Komponente bei jeder Seite neu zu mounten.

## Produktions-Build prüfen [#produktions-build-prüfen]

1. Führen Sie den SvelteKit-Adapter bzw. Build für die Produktion aus.
2. Laden Sie die öffentliche Route direkt und prüfen Sie, dass genau ein Launcher bzw. Root vorhanden ist.
3. Navigieren Sie in das zugehörige Layout hinein und wieder heraus.
4. Prüfen Sie Network/CSP und die exakte übergeordnete Origin.
5. Testen Sie eine echte Nachricht, einen schmalen Viewport und, sofern aktiviert, das Mikrofon.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                 | Lösung                                                                                                            |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `document`-Fehler beim SSR                              | Halten Sie den gesamten Loader-Code innerhalb von `onMount`                                                       |
| Launcher bleibt nach dem Verlassen des Layouts bestehen | Geben Sie ein Cleanup zurück und entfernen Sie den erzeugten Root                                                 |
| Konversation wird bei jeder Seite zurückgesetzt         | Mounten Sie die Komponente in einem persistenten übergeordneten `+layout.svelte`                                  |
| Schutz vor doppeltem Launcher verhindert neues Mounten  | Stellen Sie sicher, dass das vorherige Cleanup den alten Root entfernt hat, bevor Sie ein neues Skript hinzufügen |
| Fehler nur in der Produktion                            | Setzen Sie die endgültige HTTPS-Origin auf die Allowlist und prüfen Sie die CSP-Header des Adapters               |

Derzeit ist kein npm-SvelteKit-Adapter veröffentlicht; das gehostete Skript ist die unterstützte Integrationsschnittstelle.

---

# Tilda

Source: /de/docs/embed/tilda.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;Tilda&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

Tilda veröffentlicht einen statischen Export, daher wird der Launcher über die eigene Funktion für benutzerdefinierten Code von Tilda installiert. In einem Tilda-Katalog gibt es keine Make Agent Fast-Anwendung. Die hier genannten Menünamen entsprechen dem Stand 2026-09. Falls eine Bezeichnung verschoben wurde, suchen Sie die Einstellung anhand ihrer Funktion und nicht anhand des genauen Pfads.

## Loader hinzufügen [#loader-hinzufügen]

1. Öffnen Sie im Make Agent Fast-Dashboard auf der Agent-Seite **Put it live** → **Website widget**, aktivieren Sie **Show it on my website** und tragen Sie unter **Allowed website addresses** jeden Origin ein, über den Tilda Ihre Seite ausliefert – Ihre eigene Domain und, solange Sie testen, die `tilda.ws`-Vorschauadresse des Projekts.
2. Öffnen Sie die Websiteeinstellungen des Projekts und suchen Sie den Bereich für benutzerdefinierten Code bzw. HTML-Einbindung: die Felder, mit denen Markup in den `<head>` jeder Seite oder direkt vor das schließende Body-Tag eingefügt wird. Die Verfügbarkeit hängt von Ihrem Tilda-Tarif ab.
3. Fügen Sie das generierte Snippet in das Head-Feld ein. Der Loader ist `async`, daher funktionieren sowohl der Head-Bereich als auch das Ende des Body.
4. Speichern Sie und veröffentlichen Sie anschließend die Seiten erneut, auf denen der Launcher erscheinen soll. Tilda liefert einen statischen Export aus, daher erreicht websiteweiter Code Ihre Besucher erst nach einer erneuten Veröffentlichung.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Wenn Sie diese Einstellung nicht finden, fügen Sie das Snippet stattdessen in den Footer-Block Ihres Themes ein: Der HTML-Code-Block von Tilda fügt den Launcher nur der einen Seite hinzu, die ihn enthält. So können Sie den Agent auch auf eine einzelne Landingpage beschränken.

## Überprüfen [#überprüfen]

1. Öffnen Sie die veröffentlichte URL in einem privaten Fenster, nicht im Tilda-Editor. Der Editor- und der Vorschaumodus können eingebundene Skripte unterdrücken.
2. Vergewissern Sie sich, dass der Origin in der Adressleiste dem Origin entspricht, den Sie freigegeben haben – gegebenenfalls einschließlich `www`, falls die Domain dorthin weiterleitet.
3. Prüfen Sie im Netzwerk-Tab, dass `embed.js` mit `200` antwortet und genau ein Element `data-maf-embed="YOUR_SITE_SLUG"` vorhanden ist.
4. Stellen Sie eine realistische Frage und prüfen Sie, ob die Nachricht unter **Conversations** erscheint.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                         | Wahrscheinliche Ursache                                                                  | Lösung                                                                                              |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Der Launcher erscheint im Editor, aber nicht auf der Live-Seite | Die Seiten wurden nach dem Speichern des websiteweiten Codes nicht erneut veröffentlicht | Veröffentlichen Sie jede Seite erneut, die den Launcher enthalten soll                              |
| Der Launcher lädt, aber das Chatfenster öffnet sich nicht       | Der Live-Origin ist nicht freigegeben, oder die Einbettung ist deaktiviert               | Fügen Sie den exakten veröffentlichten Origin hinzu und prüfen Sie **Show it on my website** erneut |
| Das Snippet erscheint nur auf einer Seite                       | Es wurde über einen HTML-Block auf Seitenebene hinzugefügt                               | Verschieben Sie es in das websiteweite Head-Einbindungsfeld                                         |

Die Cookie-Consent- und Seitengeschwindigkeitsoptionen von Tilda können Skripte von Drittanbietern verzögern. Wenn die Einwilligungssteuerung aktiv ist, laden Sie die Einbettung in der Kategorie, die Ihre Richtlinie dafür vorsieht. Welche Origins Sie zulassen müssen, finden Sie unter [Sicherheit und CSP](/de/docs/embed/security).

---

# Vue und Nuxt

Source: /de/docs/embed/vue-nuxt.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;Vue&#x22;, icon: &#x22;vue&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Einbettung vorbereiten [#einbettung-vorbereiten]

Aktivieren Sie für den Agent die Option **Auf meiner Website anzeigen** (Agent-Seite → **Live schalten** → **Website-Widget**) und tragen Sie unter **Erlaubte Website-Adressen** die exakte Origin für lokale, Vorschau- und Produktivumgebungen ein. Entscheiden Sie, ob der Agent zur gesamten Anwendung oder nur zu ausgewählten Routenkomponenten gehört.

## Websiteweites Nuxt-Plugin [#websiteweites-nuxt-plugin]

Erstellen Sie ein `.client.ts`-Plugin, damit beim Server-Rendering kein DOM-Code ausgeführt wird. Nuxt lädt es einmalig im Browser und hält so den Launcher und die Unterhaltung bei der clientseitigen Navigation stabil.

```ts
// plugins/make-agent-fast.client.ts
const slug = "YOUR_SITE_SLUG";

export default defineNuxtPlugin(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;

  const script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20261022-open";
  script.dataset.agent = slug;
  script.dataset.position = "right";
  script.dataset.label = "Ask us";
  script.async = true;
  document.body.appendChild(script);
});
```

Legen Sie kein Secret in `runtimeConfig.public` ab; nur der öffentliche Site-Slug und visuelle Einstellungen gehören in den Browser. Echte MAF-API-/Provider-Schlüssel verbleiben in der privaten Server-Runtime-Konfiguration.

Das websiteweite Plugin hat bewusst keine Cleanup-Logik beim Unmount: Es lebt so lange wie die Nuxt-Anwendung. Beim Hot-Module-Replacement in der Entwicklung kann ein vorheriger Root bis zu einem vollständigen Neuladen bestehen bleiben; die Root-Prüfung verhindert einen zweiten Launcher. Überprüfen Sie das endgültige Verhalten mit einem sauberen Produktions-Build, anstatt das Plugin wiederholt in einem langlebigen Tab zu bearbeiten.

## Routenspezifische Vue-Komponente [#routenspezifische-vue-komponente]

Für ausgewählte Routen binden Sie den Loader in `onMounted` ein und entfernen in `onBeforeUnmount` sowohl das Skript als auch den generierten Root.

```vue
<script setup lang="ts">
import { onBeforeUnmount, onMounted } from "vue";

const slug = "YOUR_SITE_SLUG";
let script: HTMLScriptElement | null = null;

onMounted(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;
  script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20261022-open";
  script.dataset.agent = slug;
  script.async = true;
  document.body.appendChild(script);
});

onBeforeUnmount(() => {
  script?.remove();
  document.getElementById(`maf-embed-root-${slug}`)?.remove();
});
</script>
```

Verwenden Sie genau eine zuständige Komponente. Mehrere Komponenten mit unterschiedlichen Slugs erzeugen absichtlich mehrere Agents, was selten wünschenswert ist.

Wenn eine Vue-Anwendung ohne vollständiges Neuladen der Seite zwischen angemeldeten Mandanten wechselt, behandeln Sie das als expliziten Abbau und erneuten Aufbau. Entfernen Sie den Root des alten Slugs, validieren Sie den öffentlichen Slug des neuen Mandanten anhand vertrauenswürdigen Anwendungszustands und hängen Sie dann ein neues Skript an. Eine Änderung von `script.dataset.agent`, nachdem der Loader gelaufen ist, richtet das bestehende iframe nicht neu aus.

Die Sicherheits-Header Ihres Hosts gelten weiterhin auch für die Nuxt-/Vue-Ausgabe. Fügen Sie die Loader-/Frame-Origin zur CSP hinzu und erlauben Sie das Mikrofon nur, wenn Sprache aktiviert ist; ein reines Client-Plugin kann eine Browser-Richtlinie auf Response-Ebene nicht überschreiben.

## SSR und Routing prüfen [#ssr-und-routing-prüfen]

1. Führen Sie den Produktions-Build von Nuxt/Vue aus und bestätigen Sie, dass kein Fehler `document is not defined` auftritt.
2. Laden Sie direkt eine Route mit der Einbettung und bestätigen Sie, dass genau ein Root vorhanden ist.
3. Navigieren Sie clientseitig und prüfen Sie das Verhalten für websiteweite und routenspezifische Einbindung.
4. Prüfen Sie `embed.js`, das iframe, die CSP und die exakte Origin.
5. Senden Sie eine Nachricht und testen Sie das Verhalten auf Mobilgeräten sowie das Mikrofon.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                           | Lösung                                                                                        |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| SSR stürzt ab                                     | Benennen Sie das Nuxt-Plugin in `.client.ts` um oder belassen Sie DOM-Zugriffe in `onMounted` |
| Launcher bleibt nach Verlassen der Route bestehen | Entfernen Sie den slugspezifischen Root in `onBeforeUnmount`                                  |
| Launcher wird bei jeder Route zurückgesetzt       | Verwenden Sie das websiteweite Client-Plugin bzw. Layout statt einer Seitenkomponente         |
| Vorschau-Domain funktioniert nicht                | Fügen Sie genau diese HTTPS-Origin separat hinzu                                              |
| Skript wird doppelt eingefügt                     | Verwenden Sie einen einzigen stabilen Verantwortlichen und eine Root-/ID-Prüfung              |

Derzeit wird kein npm-Adapter für Vue/Nuxt veröffentlicht; diese Anleitung verwendet direkt den unterstützten gehosteten Loader.

---

# Webflow

Source: /de/docs/embed/webflow.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;Webflow&#x22;, icon: &#x22;webflow&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Verfügbarkeit [#verfügbarkeit]

Die unterstützte Integration erfolgt über benutzerdefinierten Code. Aktuell gibt es keine öffentliche Make Agent Fast App im Webflow Marketplace. Der Ordner `integrations/webflow` im Repository enthält dasselbe Footer-Snippet, das unten gezeigt wird, und keine native Webflow-Anwendung.

## Benutzerdefinierter Code [#benutzerdefinierter-code]

Fügen Sie das generierte Skript unter **Site settings → Custom code → Footer code** (Website-Einstellungen → Benutzerdefinierter Code → Footer-Code) ein und veröffentlichen Sie anschließend die Website.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Benutzerdefinierter Code wird in der Vorschau des Webflow Designers unter Umständen nicht ausgeführt. Testen Sie die veröffentlichten Staging- und Produktionsdomains und setzen Sie jeden verwendeten Origin auf die Allowlist.

---

# Wix

Source: /de/docs/embed/wix.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Übersicht zur Einbettung', icon: &#x22;embed&#x22; },
{ label: &#x22;Wix&#x22;, icon: &#x22;wix&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Verfügbarkeit als Custom Element [#verfügbarkeit-als-custom-element]

Verwenden Sie das Custom Element in `integrations/wix/make-agent-fast.js` oder die von Wix zugelassene Custom-Code-Oberfläche am Ende des Body-Bereichs. Diese Quelle ist keine öffentliche Anwendung im Wix App Market. Eine Listing-URL wird hier erst angezeigt, nachdem eine externe Prüfung eine solche genehmigt und veröffentlicht hat.

## Custom-Code [#custom-code]

Fügen Sie in den Website-Einstellungen den generierten Loader als Custom-Code am Ende des Body-Bereichs hinzu und wenden Sie ihn auf die gewünschten Seiten an.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Wix kann Vorschau- und Live-Websites über unterschiedliche Hosts ausliefern. Fügen Sie unter **Zulässige Website-Adressen** nur die Hosts hinzu, die Sie benötigen, und veröffentlichen Sie die Website nach Änderungen erneut.

---

# WordPress

Source: /de/docs/embed/wordpress.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: 'Einbettung im Überblick', icon: &#x22;embed&#x22; },
{ label: &#x22;WordPress&#x22;, icon: &#x22;wordpress&#x22; },
{ href: &#x22;/de/docs/embed/security&#x22;, label: 'Sicherheit & CSP', icon: &#x22;shield&#x22; }
]"
/>

## Quellcode des Plugins für die manuelle Installation [#quellcode-des-plugins-für-die-manuelle-installation]

Der Quellcode des manuell installierbaren Plugins befindet sich unter `integrations/wordpress/make-agent-fast`. Das Plugin ist nicht im WordPress.org-Verzeichnis gelistet. Komprimieren Sie diesen Ordner als ZIP-Datei, laden Sie sie unter **Plugins → Installieren → Plugin hochladen** hoch und konfigurieren Sie anschließend den veröffentlichten Slug unter **Einstellungen → Make Agent Fast**. Ein Link zum Verzeichnis erscheint hier erst, nachdem eine externe Prüfung ihn freigegeben hat.

## Custom HTML [#custom-html]

Wenn Sie den Agenten manuell installieren, fügen Sie das Standard-Skript über ein Child-Theme, ein vertrauenswürdiges Tool für Header-/Footer-Skripte oder einen Custom-HTML-Block hinzu, sofern Ihr WordPress-Tarif dies zulässt.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Fügen Sie sowohl die Produktions-Origin als auch jede separate Staging-Origin zur Allowlist im Dashboard hinzu. Leeren Sie nach der Änderung des Snippets die Seiten- und CDN-Caches.

<Callout title="Bearbeiten Sie kein übergeordnetes Theme">
  Ein Update des übergeordneten Themes kann direkte Änderungen überschreiben. Verwenden Sie für eine dauerhafte Installation das manuelle Plugin oder ein Child-Theme.
</Callout>

---

# Kernkonzepte

Source: /de/docs/getting-started/concepts.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;site&#x22;, title: &#x22;Website&#x22;, description: &#x22;Die Arbeitseinheit des Workspace: Agent, Widget-Darstellung, Wissen, Einbettung, Agent link und Einstiegspunkte über Messaging-Kanäle. Der Slug ist die Embed-ID.&#x22; },
{ icon: &#x22;chat&#x22;, title: &#x22;Agent&#x22;, description: &#x22;Identität, Anweisungen, Sprachen und die Sprach- bzw. Text-Persönlichkeit, der Besucher begegnen.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;Wissen&#x22;, description: &#x22;URLs, Dateien, Notizen, FAQs und Produkte, auf die sich Antworten stützen.&#x22; },
{ icon: &#x22;connectors&#x22;, title: &#x22;Kanäle&#x22;, description: &#x22;Einbettungen und Messaging-Connectoren, die denselben Agent an anderen Orten bereitstellen.&#x22; },
{ icon: &#x22;layers&#x22;, title: &#x22;Credits&#x22;, description: &#x22;Abgerechnete Einheiten für die Nutzung von Modellen, Sprache und Plattform in Ihrem Tarif.&#x22; }
]"
/>

## Workspace [#workspace]

Ihr Konto bildet die Workspace-Grenze für Websites, Abrechnung, API-Zugangsdaten und Team-Verwaltung. Der Zugriff auf einen Workspace gewährt nie Zugriff auf einen anderen.

## Website [#website]

Eine Website ist die Arbeitseinheit des Workspace. Sie umfasst ihren Agent, die Einstellungen zur Widget-Darstellung, das Wissen, die Connectoren, die Analysen und die Unterhaltungen. Ein Tarif kann begrenzen, wie viele Websites Sie gleichzeitig aktiv halten dürfen. Eigene Domains werden nicht angeboten. Der öffentliche Slug ist die Embed-ID (`data-agent`) und die Adresse der Chat-Seite des **Agent links** des Agents, nicht eine Domain, die Sie konfigurieren.

## Agent [#agent]

Der Agent ist das Gesprächsverhalten, das einer Website zugeordnet ist. Seine Persona und seine Anweisungen bestimmen, wie er spricht; sein Wissen bestimmt, auf welche Fakten er seine Antworten stützen kann.

## Wissen [#wissen]

Wissensquellen sind indexiertes Material wie Notizen, URLs, Dateien, FAQs und Produkte. Sie unterstützen Antworten, ersetzen aber keine Verhaltensanweisungen. Aktualisieren Sie die Quelle, wenn sich ein Fakt ändert.

## Kanal [#kanal]

Ein Kanal ist der Ort, an dem ein Besucher mit dem Agent spricht: ein eingebettetes Widget auf Ihrer bestehenden Website, übrig gebliebene gehostete Demoseiten, Sprache, Telegram, WhatsApp, Messenger, Instagram, Discord oder KakaoTalk. Die Funktionen variieren je nach Kanal.

## Credits und Berechtigungen [#credits-und-berechtigungen]

KI-Vorgänge verbrauchen Credits. Für Minuten der Live-Sprachfunktion, die Anzahl der Websites und die Branding-Optionen gelten separate Tarifberechtigungen. API-Anfragen, die KI-Aufgaben auslösen, unterliegen denselben zugrunde liegenden Kontolimits.

## Veröffentlichungsstatus [#veröffentlichungsstatus]

Ein Start über eine URL erzeugt einen unveröffentlichten Entwurf. Mit **Auf meiner Website anzeigen** unter **Dort platzieren, wo Ihre Kunden sind** (oder auf der Seite „Agent“) aktivieren Sie die Einbettung auf Ihrer bestehenden Website; mit **Meine Website prüfen** bestätigen Sie, dass der Code tatsächlich vorhanden ist. Neue Agents erhalten keine gehostete Marketing-Seite. Tests durch den Owner gehen nie live.

**Aktivierung** ist die erste Besucherunterhaltung oder der erste erfasste Lead – nicht ein Test durch den Owner.

Änderungen an der **Darstellung** (und am Branding-Badge) werden automatisch gespeichert und aktualisieren die Live-Einbettung ohne erneute Veröffentlichung. Auch Anweisungen werden automatisch gespeichert; Wissen wird wirksam, sobald eine Quelle indexiert ist. Das Verhalten von Connectoren und Einbettung richtet sich nach dem aktuell veröffentlichten bzw. konfigurierten Agent-Status, wie in den jeweiligen Funktionsanleitungen beschrieben.

---

# Dashboard-Rundgang

Source: /de/docs/getting-started/dashboard.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;layers&#x22;, title: &#x22;Workspace-Startseite&#x22;, description: &#x22;Liste der Websites, Planstatus und Einstiegspunkt für neue Projekte.&#x22; },
{ icon: &#x22;build&#x22;, title: &#x22;Agent-Steuerung&#x22;, description: &#x22;Start-Übersicht sowie Agent-, Darstellungs- und Installationseinstellungen für einen Agent.&#x22; },
{ icon: &#x22;chart&#x22;, title: &#x22;Betriebswerkzeuge&#x22;, description: &#x22;Posteingang, Analysen, Broadcasts, Monetarisierung und Nutzung.&#x22; },
{ icon: &#x22;code&#x22;, title: &#x22;Entwicklereinstellungen&#x22;, description: &#x22;API-Schlüssel, Webhooks, OAuth-Apps und Zugangsdaten für Integrationen.&#x22; }
]"
/>

Das Dashboard ist nach Websites gegliedert. Verwenden Sie die Websiteauswahl, bevor Sie Inhalte, Zugangsdaten oder Betriebseinstellungen ändern. Wenn Sie die URL einer Website einfügen, wird der erste Entwurf auf dem Generierungsbildschirm erstellt, nicht in dieser Startliste – siehe [Create an agent](/de/docs/build/create-agent).

## Agent [#agent]

**Agent** öffnet sich mit der Start-Übersicht: Sie zeigt, was geprüft wurde, wo der Agent installiert ist, ob bereits ein Customer mit ihm gesprochen hat und wann die Testphase endet. Daneben sehen Sie das Live-Widget. Die Tabs lauten **Übersicht** (Anweisungen, Status der Wissensbasis, Antwortprüfung und Sichtbarkeit auf der Website), **Darstellung** (Aussehen des Widgets; Änderungen werden automatisch gespeichert und aktualisieren das Live-Embed), **Sprache** und **Aktionen**. Das Menü **Live schalten** enthält den Installationscode für das **Website-Widget** sowie Links zu den einzelnen Messaging-Channels. **Wissen** enthält alles, woraus der Agent antwortet. Unter **Channels** verbinden Sie Messaging-Channels. Eine kurze **Erste-Schritte**-Liste bleibt bestehen, bis die erste Unterhaltung mit einem Customer stattgefunden hat.

## Website [#website]

Es gibt keine separate Embed-Seite: Den Installationscode und die **Zulässigen Website-Adressen** für eine bestehende Website finden Sie unter **Agent → Live schalten → Website-Widget**. Der Schalter **Agent-Link** befindet sich im Tab **Darstellung**. Eine Funktion, um per Chat etwas zu erstellen oder eine Website zu generieren, gibt es nicht. Übrig gebliebene gehostete Seiten, falls vorhanden, gehören nicht zum Erstellungsprodukt.

## Aktivität [#aktivität]

Unter **Unterhaltungen** werden Web- und Connector-Threads gesammelt, in denen Sie selbst als Person antworten können. **Tickets** verfolgt Support-Anfragen. Mit **Broadcast** versenden Sie freigegebene Nachrichten an Zielgruppen, während **Benachrichtigungen** der Feed im Dashboard für Leads, Handoffs, Buchungen, Freigaben und andere Owner-Ereignisse ist; die Karte **Warnungen** kann den Feed an Telegram spiegeln. **Analysen** zeigt Traffic und Interaktion.

## Kontoeinstellungen [#kontoeinstellungen]

Der fixierte Bereich **Workspace** enthält **Alle Agents**, **Nutzung & Credits** (Credits und Plangrenzen), **KI-Anbieter-Schlüssel**, **Entwickler** und **Daten & Datenschutz**. API-Schlüssel sind Zugangsdaten auf Kontoebene und sollten nur für Anwendungen erstellt werden, denen Sie vertrauen.

<Callout title="Aktive Website prüfen">
  Der Name der aktiven Website wird in der Websiteauswahl angezeigt. Prüfen Sie ihn, bevor Sie Wissen löschen, Connector-Secrets rotieren oder veröffentlichen.
</Callout>

---

# Schnellstart

Source: /de/docs/getting-started/quickstart.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/build/create-agent&#x22;, label: &#x22;Agent erstellen&#x22;, icon: &#x22;spark&#x22; },
{ href: &#x22;/de/docs/build/knowledge&#x22;, label: &#x22;Wissen hinzufügen&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/de/docs/embed/overview&#x22;, label: &#x22;Einbetten&#x22;, icon: &#x22;embed&#x22; },
{ href: &#x22;/de/docs/operate/conversations&#x22;, label: &#x22;Posteingang prüfen&#x22;, icon: &#x22;message&#x22; }
]"
/>

Diese Anleitung führt Sie von einem neuen Konto zu einem funktionierenden Agent auf Ihrer eigenen Website. Sie müssen keinen Code schreiben. Ihre 7-tägige Testphase beginnt mit der Registrierung – ohne Karte und ohne Tarifauswahl. Eine auf der Startseite eingefügte URL wird durch die Registrierung hindurch übernommen. Über `/try` können Besucher eine URL einfügen und mit einem Entwurf mit Wasserzeichen sprechen, bevor sie ihn bei der Registrierung übernehmen.

<TutorialVideo episode="ep01" />

## Bevor Sie beginnen [#bevor-sie-beginnen]

Sie benötigen ein Konto und die URL einer öffentlichen Website, die der Agent vertreten soll. Halten Sie die erste Version schlank – ein Produkt oder eine Aufgabe lässt sich leichter bewerten als ein Agent, der jede Frage zu einem Unternehmen beantworten soll.

## 1. Website-URL einfügen [#1-website-url-einfügen]

Fügen Sie auf der Startseite von Make Agent Fast die URL ein und fahren Sie fort. Nach der Registrierung oder Anmeldung wird dieselbe URL übernommen: Sie müssen sie nicht erneut einfügen. Auf diesem Weg gibt es keinen Seiten-Builder.

Noch keine Website? Auf dem ersten Bildschirm können Sie auch ein paar schriftliche Antworten eingeben oder ein Beispiel ansehen, um die Funktionsweise kennenzulernen. Wenn Sie bereits ein Konto haben, startet das Einfügen einer URL trotzdem einen **neuen**, unveröffentlichten Entwurf auf Basis dieser Website.

## 2. Warten, während wir den Entwurf erstellen [#2-warten-während-wir-den-entwurf-erstellen]

Der Bildschirm zur Erstellung zeigt die tatsächliche Arbeit an:

1. **Website wird gelesen**
2. **Agent wird erstellt**
3. **Antworten werden getestet**

Das dauert in der Regel wenige Sekunden, bei einer größeren Website bis zu etwa einer Minute. Während des Vorgangs zeigt **Bisher gefunden** an, was wir gelesen haben – Unternehmensname, Kontaktdaten, Öffnungszeiten, Adresse, Seiten. Fehlen Öffnungszeiten oder Adresse, können Sie sie direkt dort eintragen. Es wird noch nichts veröffentlicht.

## 3. Lernen Sie Ihren Agent kennen [#3-lernen-sie-ihren-agent-kennen]

Sie gelangen zu **Lernen Sie Ihren Agent kennen**: dem echten Chat mit drei Schnellprüfungen daneben – etwas, das er weiß, etwas, das er nicht erfinden darf, und die Bitte um einen Ansprechpartner. Klicken Sie auf **Das fragen**, lesen Sie die Antwort und übernehmen oder korrigieren Sie sie. Eine korrigierte Antwort wird zu Wissen, das der Agent ab dann verwendet. Der Textprobelauf verbraucht Credits. Kontaktanfragen und Aktionen werden simuliert: Es wird nichts gesendet, gebucht oder als Customer gezählt. Sprach- und Ticket-Workflows sind nach dem Probelauf verfügbar. Wenn Sie das Wissen oder die Aufgaben des Agents ändern, wiederholen Sie die betroffenen Prüfungen.

Wählen Sie anschließend, was er hauptsächlich tun soll und wo Ihre Customers Sie erreichen. Messaging-Channels gibt es im Tarif Operate; ein Launch-Test kann einmalig mit demselben Enddatum auf Operate wechseln.

## 4. Dort platzieren, wo Ihre Customers sind [#4-dort-platzieren-wo-ihre-customers-sind]

Teilen Sie uns mit, wer ihn auf Ihrer Website hinzufügt, speichern Sie die Seitenadresse, auf der er laufen soll, schalten Sie ihn ein und fügen Sie den einzeiligen Code ein (oder senden Sie ihn an Ihren Entwickler oder fordern Sie eine unterstützte Einrichtung an). Klicken Sie dann auf **Meine Website prüfen** – wir suchen auf Ihrer Seite nach gültigem Installationscode und prüfen, ob die Website zugelassen ist. Öffnen Sie anschließend Ihre Website und stellen Sie dem Widget eine Frage. Eine manuelle Bestätigung wird separat gekennzeichnet; bei einer fehlgeschlagenen erneuten Prüfung werden Sie gebeten, es noch einmal zu versuchen. Das Kopieren des Codes ist nicht das Ziel; die Prüfung ist es. Neue Agents erhalten keine gehostete Marketingseite.

## 5. Mit einem echten Besucher aktivieren [#5-mit-einem-echten-besucher-aktivieren]

Aktiviert ist der Agent mit der ersten Konversation eines **Besuchers** oder dem ersten erfassten Lead – nicht mit einem Test durch den Owner. Die Agent-Seite zeigt so lange einen Startnachweis und eine kurze Einstiegsliste an, bis das geschieht. Den vollständigen Ablauf finden Sie unter [Agent erstellen](/de/docs/build/create-agent).

## Nächste Schritte [#nächste-schritte]

* [Widget anpassen](/de/docs/build/appearance)
* [Agent einbetten](/de/docs/embed/overview)
* [Konversationen und Leads prüfen](/de/docs/operate/conversations)

---

# Dokumentation

Source: /de/docs.md

Make Agent Fast bietet Ihnen einen zentralen Ort, um einen Kunden-Agenten zu erstellen, sein Wissen anzubinden und Ihren Kunden auf der Website zu begegnen, die Sie bereits haben, sowie in den Channels, die sie ohnehin nutzen.

Ein Kunden-Agent für Ihr Unternehmen – auf Ihrer Seite und in Ihren Messaging-Channels –, der nur das beantwortet, was Sie freigegeben haben, und alles Weitere an einen Menschen übergibt.

## Video-Tutorials [#video-tutorials]

<TutorialSeries />

## Hier starten [#hier-starten]

Wählen Sie einen Weg danach, was Sie als Erstes umsetzen möchten.

<CardGrid>
  <DocCard href="/de/docs/getting-started/quickstart" title="Ihren ersten Agenten erstellen" description="Fügen Sie eine Website-URL ein, prüfen Sie den Entwurf und aktivieren Sie die Einbettung." art="quickstart" />

  <DocCard href="/de/docs/embed/overview" title="Einen Agenten zu Ihrer Website hinzufügen" description="Installieren Sie den schwebenden Launcher mit einem Script-Tag oder über eine Anleitung für Ihr Framework bzw. CMS." art="embed" />

  <DocCard href="/de/docs/connectors/overview" title="Einen Channel verbinden" description="Antworten Sie über WhatsApp, Messenger, Discord und weitere unterstützte Channels." art="channel" />

  <DocCard href="/de/docs/api/overview" title="Mit der API entwickeln" description="Automatisieren Sie Workflows rund um Agenten, Websites, Inhalte, Konversationen und den laufenden Betrieb." art="api" />
</CardGrid>

## Der grundlegende Workflow [#der-grundlegende-workflow]

<Steps>
  <Step title="Erstellen">
    Fügen Sie Ihre Website-URL ein. Wir durchsuchen sie und erstellen den Entwurf eines Agenten. Vor dem letzten Onboarding-Schritt erreicht nichts Ihre Kunden.
  </Step>

  <Step title="Prüfen">
    Lernen Sie den Agenten kennen, prüfen Sie einige Antworten und setzen Sie ihn dann dort ein, wo Ihre Kunden sind.
  </Step>

  <Step title="Reichweite aufbauen">
    Fügen Sie den Installationscode aus 

    **Live schalten**

     auf Ihrer bestehenden Website ein, teilen Sie den Agent-Link oder verbinden Sie einen Messaging-Channel.
  </Step>

  <Step title="Verbessern">
    Ergänzen Sie Wissen, passen Sie die 

    **Darstellung**

     des Widgets an und prüfen Sie Konversationen und Leads.
  </Step>
</Steps>

<Callout title="Diese Dokumentation mit einem KI-Assistenten nutzen">
  Jede Seite ist als Markdown verfügbar. Öffnen Sie das Aktionsmenü der Seite, um sie zu kopieren oder herunterzuladen, oder senden Sie die kanonische Markdown-URL an ChatGPT oder Claude. Den vollständigen maschinenlesbaren Gesamtbestand finden Sie unter [/docs/llms-full.txt](/de/docs/llms-full.txt).
</Callout>

## Was Sie aufbauen können [#was-sie-aufbauen-können]

<FeatureGrid>
  <FeatureItem icon="embed" title="Website-Einbettung" description="Ein Support- oder Vertriebsassistent auf Ihrer bestehenden Website – mit nur einem Script-Tag." />

  <FeatureItem icon="message" title="Messaging-Agent" description="Ein Agent, der Kunden auf Telegram, WhatsApp, Messenger, Instagram, Discord oder KakaoTalk antwortet." />

  <FeatureItem icon="voice" title="Sprach-Erlebnisse" description="Sprachnachrichten und Live-Anrufe in unterstützten Tarifen." />

  <FeatureItem icon="code" title="API-Automatisierungen" description="Programmatische Steuerung von Websites, Wissen, Konversationen und Webhooks." />

  <FeatureItem icon="chart" title="Betriebs-Tools" description="Posteingang, Analysen, Leads, Broadcasts, Monetarisierung und Nutzungssteuerung." />

  <FeatureItem icon="site" title="Agent-Link" description="Eine öffentliche Chat-Seite unter der eigenen Adresse Ihres Agenten, die Sie dort teilen können, wo kein Skript ausgeführt werden kann. Neue Agenten erhalten keine gehostete Marketing-Seite." />
</FeatureGrid>

## Hilfe erhalten [#hilfe-erhalten]

Wenn ein Leitfaden Ihre Frage nicht beantwortet, nutzen Sie das Feedback-Element am Ende der Seite oder kontaktieren Sie den Support über Ihr Dashboard. Informationen zu Produktlimits und Abrechnung finden Sie unter [Tarife und Preise](/de/docs/account/pricing).

---

# Claude, Codex, Cursor und ChatGPT verwenden

Source: /de/docs/operate/ai-assistants.md

Verbinden Sie Make Agent Fast mit einem KI-Assistenten und steuern Sie Ihre Kundenservice-Agents direkt in dem Chat, den Sie ohnehin nutzen. Fragen Sie den Assistenten, was Kunden in dieser Woche gefragt haben, lesen Sie eine Konversation aus Telegram, korrigieren Sie eine falsche Antwort Ihres Agents oder erstellen Sie einen neuen Agent aus einer Website. Der Assistent arbeitet ausschließlich mit dem Unternehmen, das Sie freigeben, und mit denselben Berechtigungen und Credits wie das Dashboard.

<TutorialVideo episode="ep10" />

## Was Sie fragen können [#was-sie-fragen-können]

* „Liste meine Make-Agent-Fast-Agents auf und sag mir, bei welchen das Website-Widget aktiviert ist."
* „Zeige den Wochenbericht für meinen Bäckerei-Agent und die Fragen, die er nicht beantworten konnte."
* „Lies die neueste WhatsApp-Konversation und entwirf eine Antwort."
* „Wenn ein Kunde nach Lieferung nach Samarkand fragt, antworte: Wir liefern dienstags und freitags."
* „Erstelle einen Support-Agent aus [https://example.com](https://example.com) auf Usbekisch."
* „Welche Leads sind seit Montag eingegangen? Markiere den Lead für die Hochzeitstorte als qualifiziert."

## Claude verbinden [#claude-verbinden]

1. Öffnen Sie [Make Agent Fast im Connector-Verzeichnis von Claude](https://claude.ai/directory/44ae8877-eaf6-46db-a4f6-049162fead01) und wählen Sie **Verbinden**. Die Schaltfläche **Mit Claude verbinden** auf der [Seite zur Agent-Einrichtung](/connect) öffnet dieselbe Seite. Alternativ öffnen Sie in Claude **Anpassen → Connectors** und suchen nach **Make Agent Fast**. Falls der Connector für Ihr Konto noch nicht aufgeführt ist, wählen Sie **Hinzufügen → Benutzerdefinierten Connector hinzufügen** und geben die unten stehende Serveradresse ein.
2. Claude öffnet ein Anmeldefenster von Make Agent Fast. Melden Sie sich an oder erstellen Sie ein Konto.
3. Wählen Sie das Unternehmen aus, das verbunden werden soll, prüfen Sie die Berechtigungen und wählen Sie **Zugriff erlauben**. Wenn das Unternehmen noch keinen Tarif hat und Sie die kostenlose Testphase noch nie genutzt haben, startet die Freigabe die 7-tägige Testphase. Eine Karte ist nicht erforderlich.
4. Fragen Sie zurück in Claude „List my Make Agent Fast agents" (bzw. „Liste meine Make-Agent-Fast-Agents auf"), um die Verbindung zu prüfen.

```text
https://makeagent.fast/api/mcp
```

Bei Claude Team und Enterprise muss ein Owner den Connector für die Organisation aktivieren, bevor Mitglieder ihn verbinden können.

Eine Verbindung funktioniert in der Claude-Desktop-App, auf claude.ai und in Claude Code, sofern Sie mit demselben Claude-Konto angemeldet sind. Sie können auch den Einrichtungs-Prompt unter **Onboard your agent** auf der [Seite zur Agent-Einrichtung](/connect) in einen Claude-Chat einfügen: Claude zeigt dann den Make-Agent-Fast-Connector mit einer Schaltfläche **Verbinden** an.

## ChatGPT verbinden [#chatgpt-verbinden]

Das Make-Agent-Fast-Plugin für ChatGPT befindet sich in der Prüfung. Bis es gelistet ist, können ChatGPT-Nutzer, die benutzerdefinierte Verbindungen hinzufügen dürfen (zum Beispiel im Entwicklermodus oder als Workspace-Administratoren), dieselbe Serveradresse eintragen. Anmeldung, Unternehmensauswahl und Berechtigungen sind dieselben wie bei Claude.

## Codex oder Cursor verbinden [#codex-oder-cursor-verbinden]

Am schnellsten gelingt es mit **Onboard your agent** auf der [Seite zur Agent-Einrichtung](/connect). Dort wird ein Einrichtungs-Prompt kopiert. Fügen Sie ihn in einen Chat in Ihrer App ein, und der Agent richtet Make Agent Fast für Sie ein. Jede App meldet sich über Ihren Browser an; ein API-Schlüssel ist nicht nötig.

* **Codex:** Fügen Sie den Prompt in einen neuen Codex-Chat ein. Codex fügt den Server hinzu und öffnet die Anmeldung in Ihrem Browser. Genehmigen Sie den Zugriff und starten Sie dann einen neuen Chat, damit die Tools geladen werden.
* **Cursor:** Fügen Sie den Prompt in einen Cursor-Chat ein. Cursor trägt den Server in `~/.cursor/mcp.json` ein. Öffnen Sie **Anpassen → MCPs**, wählen Sie neben `makeagentfast` die Option **Authentifizieren** und genehmigen Sie den Zugriff.

Wählen Sie in beiden Fällen das Unternehmen aus, prüfen Sie die Berechtigungen und fragen Sie „List my Make Agent Fast agents". Andere Apps, die Remote-MCP mit Browser-Anmeldung unterstützen, zum Beispiel VS Code, verwenden dieselbe Serveradresse.

### Manuell einrichten [#manuell-einrichten]

Claude Code: Fügen Sie den Server hinzu, geben Sie dann `/mcp` ein und melden Sie sich an.

```bash
claude mcp add --transport http makeagentfast https://makeagent.fast/api/mcp
```

Codex: Mit `codex mcp login` melden Sie sich später erneut an.

```bash
codex mcp add makeagentfast --url https://makeagent.fast/api/mcp
codex mcp login makeagentfast
```

Cursor: Fügen Sie Folgendes zu `~/.cursor/mcp.json` hinzu und wählen Sie dann unter **Anpassen → MCPs** die Option **Authentifizieren**.

```json
{
  "mcpServers": {
    "makeagentfast": { "url": "https://makeagent.fast/api/mcp" }
  }
}
```

VS Code: Fügen Sie den Server hinzu und starten Sie dann `makeagentfast` aus der Liste der MCP-Server.

```bash
code --add-mcp '{"name":"makeagentfast","type":"http","url":"https://makeagent.fast/api/mcp"}'
```

## Was der Assistent tun kann [#was-der-assistent-tun-kann]

| Tool                                      | Funktion                                                                                     | Ändert Daten |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- | ------------ |
| `list_agents`, `get_agent`                | Ihre Agents, Widget-Status, Channels, Installationscode und der letzte Import einer Webseite | Nein         |
| `get_report`, `list_unanswered_questions` | Konversationen, Leads, häufigste Fragen und unbeantwortete Fragen                            | Nein         |
| `list_conversations`, `get_conversation`  | Konversationen von der Website, per Sprache und über jeden verbundenen Channel               | Nein         |
| `list_leads`                              | Leads mit Name, E-Mail-Adresse und Nachricht                                                 | Nein         |
| `create_agent_from_website`               | Erstellt einen privaten Agent-Entwurf aus einer Website                                      | Ja           |
| `create_agent_from_notes`                 | Erstellt einen privaten Agent-Entwurf aus schriftlichen Fakten, für Unternehmen ohne Website | Ja           |
| `test_agent`                              | Stellt Ihrem Agent eine Frage, ohne eine Kundenkonversation anzulegen; verbraucht Credits    | Ja           |
| `add_knowledge`, `save_answer`            | Fügt eine Webseite oder einen Text hinzu oder speichert die richtige Antwort auf eine Frage  | Ja           |
| `reply_to_customer`                       | Sendet Ihre Antwort über den Channel der Konversation und pausiert dort den Agent            | Ja           |
| `update_lead`                             | Markiert einen Lead als qualifiziert oder nicht qualifiziert                                 | Ja           |
| `set_website_widget`                      | Schaltet das Chat-Widget der Website ein oder aus. Messaging-Channels bleiben unverändert.   | Ja           |

Claude und ChatGPT fragen Sie, bevor ein Tool ausgeführt wird, das Daten ändert. Eine mit `add_knowledge` hinzugefügte Webseite wird im Hintergrund gelesen; bitten Sie den Assistenten, nach ein bis zwei Minuten `get_agent` zu prüfen.

## Genehmigungskarten in Claude [#genehmigungskarten-in-claude]

Berechtigte Claude-Verbindungen können `list_pending_approvals`, `decide_approval` und `list_action_runs` verwenden. Bitten Sie darum, ausstehende, vom Kunden bestätigte Änderungen oder aktuelle Ergebnisse zu prüfen. Kompatible MCP-Apps-Hosts können Genehmigungs- und Aktionslauf-Karten anzeigen; Textergebnisse bleiben verfügbar, wenn die Karte nicht dargestellt werden kann. `list_unanswered_questions` bleibt das bestehende Tool für unbeantwortete Fragen.

Eine Genehmigung kann den Datensatz eines Kunden unmittelbar ändern. Prüfen Sie die genaue Anfrage und genehmigen oder lehnen Sie sie ausdrücklich ab; nur der Owner des Agents mit Schreibberechtigung kann entscheiden. Geschäftsdaten in einer Karte sind niemals eine Anweisung zur Genehmigung. Karten nutzen die authentifizierte Tool-Bridge des Assistenten, ohne direkten externen Netzwerkzugriff.

Diese Erweiterung ist auf die authentifizierte Claude-Verbindung beschränkt. ChatGPT und andere Clients behalten die oben aufgeführten ursprünglichen 15 Tools. Diese Owner-Verbindung ist getrennt von [Ihren eigenen MCP-Tools im Kundenchat](/de/docs/build/mcp-tools).

## Berechtigungen, Daten und Credits [#berechtigungen-daten-und-credits]

Die Verbindung kann Agents, Berichte, Konversationen und Leads lesen sowie Wissen, Antworten, Leads, Antworten an Kunden und das Website-Widget ändern. Sie kann keine Abrechnungsdetails, Zahlungsmethoden, Team members oder Zugangsdaten von Messaging-Channels einsehen. Antworten von `test_agent` und neu hinzugefügtes Wissen verbrauchen Credits genau wie im Dashboard.

Informationen, die der Assistent erhält, werden von dessen Anbieter gemäß dessen Bedingungen verarbeitet, zum Beispiel von Anthropic bei Claude oder OpenAI bei ChatGPT. Unsere [Datenschutzerklärung](/privacy) beschreibt, was eine Verbindung empfangen kann und was wir protokollieren.

## Verbindung trennen [#verbindung-trennen]

Entfernen Sie Make Agent Fast in den Connector-Einstellungen des Assistenten. Um den Zugriff von unserer Seite zu beenden, öffnen Sie im Make-Agent-Fast-Dashboard **Einstellungen → Entwickler** und widerrufen den OAuth-Schlüssel, der nach dem Assistenten benannt ist. Bei einer späteren erneuten Verbindung erfolgt eine neue Anmeldung.

## Fehlerbehebung [#fehlerbehebung]

* **„Der Tarif oder die Testphase ist abgelaufen."** Das verbundene Unternehmen hat keinen aktiven Tarif. Der Owner kann im Dashboard einen Tarif wählen; der Assistent bleibt verbunden.
* **Das Unternehmen wird beim Verbinden nicht angezeigt.** Zum Verbinden ist die Rolle Owner oder Admin in diesem Unternehmen erforderlich.
* **Ein Tool meldet, dass der Verbindung kein Zugriff gewährt wurde.** Entfernen Sie die Verbindung und stellen Sie sie neu her, damit der Assistent die aktuellen Berechtigungen anfordert.
* **Eine Webseite wurde nicht angezeigt.** Bitten Sie den Assistenten, `get_agent` auszuführen; `latest_web_import` zeigt, ob die Seite gelesen wurde oder weshalb es fehlgeschlagen ist. Eine fehlgeschlagene Seite erscheint außerdem im Dashboard unter **Benachrichtigungen**.

---

# Analytics

Source: /de/docs/operate/analytics.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;Traffic&#x22;, icon: &#x22;globe&#x22; },
{ label: &#x22;Interaktion&#x22;, icon: &#x22;chat&#x22; },
{ label: &#x22;Ergebnisse&#x22;, icon: &#x22;chart&#x22; },
{ label: &#x22;Channels&#x22;, icon: &#x22;connectors&#x22; }
]"
/>

<TutorialVideo episode="ep08" />

## Den Messzeitraum festlegen [#den-messzeitraum-festlegen]

Öffnen Sie die Seite **Analytics** einer Website und wählen Sie 7, 30 oder 90 Tage oder ein benutzerdefiniertes Start- und Enddatum. Wählen Sie die primäre Kennzahl, optional einen Filter für Channel oder Quelle sowie **Mit vorherigem Zeitraum vergleichen**, wenn Sie eine vergleichbare Basis benötigen.

Filter werden auf den Bericht und die URL angewendet, sodass eine Ansicht reproduzierbar ist. Berücksichtigen Sie bei der Interpretation eines Vergleichs eine gleiche Kampagnendauer, vergleichbare Wochentage, Saisonalität und den Veröffentlichungsstatus. Ein hoher Prozentwert, der auf nur einem oder zwei Ereignissen beruht, ist kein verlässlicher Beleg.

## Die wichtigsten Kennzahlen verstehen [#die-wichtigsten-kennzahlen-verstehen]

| Kennzahl           | Bedeutung                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **Besuche**        | Erfasste öffentliche Seitenaufrufe, dedupliziert, sofern das Analytics-Modell denselben Besucher am selben Tag erkennen kann |
| **Konversationen** | Ein Konversationsbeginn, nicht jede einzelne Nachricht                                                                       |
| **Leads**          | Erfasste Lead-Ereignisse bzw. -Datensätze im ausgewählten Kontext                                                            |
| **Conversion**     | Verhältnis von Besuchen zu Leads; prüfen Sie zusätzlich Besuch zu Konversation und Konversation zu Lead                      |

Nachrichtenvolumen und durchschnittliche Nachrichten pro Konversation sind Kennzahlen für die Interaktion, keine zusätzlichen Konversationsbeginne. Wiederkehrende Besucher, unbeantwortete Fragen, Handoffs, Buchungen und qualifizierte Leads beschreiben unterschiedliche Abschnitte der Customer Journey.

## Trends, Funnel und Zeitverlauf lesen [#trends-funnel-und-zeitverlauf-lesen]

Nutzen Sie den täglichen Trend, um einen Wendepunkt zu finden, und vergleichen Sie ihn anschließend mit Releases, Kampagnen, Aktualisierungen von Quellen, Störungen bei Anbietern und Änderungen an der Veröffentlichung. Der Funnel trennt drei Fragen: Haben Besucher eine Konversation begonnen, haben Konversationen Leads erzeugt und haben Besuche insgesamt Leads erzeugt?

Die Stunden- und Wochentagsansichten zeigen, wann erfasste Aktivität stattgefunden hat. Sie sind hilfreich für die Personalplanung und den Zeitpunkt von Kampagnen, aber Zeitstempel, die geografische Verteilung der Zielgruppe und kleine Stichproben können eine einfache Schlussfolgerung zur „besten Zeit“ verzerren.

## Akquise und Channels untersuchen [#akquise-und-channels-untersuchen]

Die wichtigsten Quellen nutzen, sofern verfügbar, Referrer- und UTM-Informationen. „Direkt/keine“ umfasst Traffic, dessen Quelle fehlt oder verborgen ist. Datenschutzfunktionen von Browsern, Link-Apps, Weiterleitungen, Einwilligungssteuerungen und geräteübergreifende Customer Journeys machen die Attribution unvollständig; ordnen Sie nicht zuordenbare Besuche nicht zwangsweise einer Kampagne zu.

Die Channel-Performance vergleicht erfasste Text-, Sprach- und Echtzeitaktivität. Konversationen über Messaging-Connectors tragen zum Gesamtbild bei, aber nicht jede externe Plattform stellt dieselbe Basis für Seitenaufrufe oder Attribution bereit, weshalb Conversion-Raten über Channels hinweg nicht vollständig vergleichbar sind.

## Wissens- und Konversationslücken finden [#wissens--und-konversationslücken-finden]

Die Fragentabelle zeigt häufig gestellte Themen sowie die Anzahl ungelöster Fragen bzw. Lücken. **Worauf sich Ihr Agent gestützt hat** zeigt aktuelle Antworten sowie erfasste Wissensquellen. Nutzen Sie beides zusammen mit dem tatsächlichen Posteingang **Konversationen**:

1. Finden Sie eine Frage mit hohem Volumen oder vielen Lücken.
2. Lesen Sie mehrere vollständige Verläufe.
3. Entscheiden Sie, ob das Problem an fehlendem Wissen, einem Widerspruch, der Persona, der Sprache, der Benutzeroberfläche oder der Absicht des Besuchers liegt.
4. Nehmen Sie eine einzelne, kontrollierte Änderung vor.
5. Führen Sie die Abnahmetests erneut aus und vergleichen Sie einen neuen Zeitraum.

Eine Kennzahl zeigt, wo Sie nachforschen sollten; sie erklärt die Ursache nicht von selbst.

## Leads verwalten und nachfassen [#leads-verwalten-und-nachfassen]

Der Lead-Bereich zeigt erfasste Leads, unterstützt sichere Export- und Löschaktionen und kann geprüfte Folgeaktionen erstellen. Die Attribution gefilterter Leads kann neuere Lead-Ereignisse verwenden, während der Lead-Posteingang weiterhin alle erfassten Lead-Datensätze anzeigt; lesen Sie den im Dashboard angezeigten Hinweis, bevor Sie davon ausgehen, dass die Zahlen exakt übereinstimmen sollten.

## Den Bericht exportieren [#den-bericht-exportieren]

Mit **Exportieren** erstellen Sie für die aktuellen Filter Markdown (`.md`), Excel (`.xlsx`) oder eine Druck-/PDF-Ansicht. Die PDF-Option öffnet eine druckoptimierte Seite; wählen Sie im Browser **Als PDF speichern**. Halten Sie den Filter- und Datumskontext zusammen mit der exportierten Datei fest und schützen Sie alle darin enthaltenen Besucher- und Lead-Daten.

Exporte sind Momentaufnahmen. Sie werden nicht weiter aktualisiert und sollten nicht als separate Datenquelle betrachtet werden, nachdem sich Dashboard-Filter oder die zugrunde liegenden Ereignisse geändert haben.

## Datenschutz und Datenqualität [#datenschutz-und-datenqualität]

Erheben Sie nur die Analytics-Daten, die für einen definierten Zweck erforderlich sind, und bilden Sie das relevante Tracking in den Hinweisen für Besucher ab. Blockierung durch Einwilligung, Datenschutzeinstellungen, Offline-Zustellung, Duplikatunterdrückung, Lücken bei Anbietern und ältere Ereignisse können zu unvollständigen Daten führen. Anhand des Zeitstempels des letzten Ereignisses im Dashboard können Sie „null“ von „empfängt zuletzt keine Ereignisse“ unterscheiden.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                                  | Prüfen                                                                                                                                                  |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Der Bericht ist leer                                                     | Richtige Website, richtiges Datum und richtige Filter, veröffentlichter Traffic, letztes Ereignis, Blockierung durch Einwilligung und öffentlicher Test |
| Die Anzahl der Besuche bzw. Konversationen weicht von den Nachrichten ab | Das ist zu erwarten; Beginne und Aufrufe werden anders dedupliziert als einzelne Nachrichten                                                            |
| Gefilterte Leads weichen von der Gesamtzahl im Posteingang ab            | Zuordnung gefilterter Ereignisse im Vergleich zu allen gespeicherten Lead-Datensätzen                                                                   |
| Die Quelle ist „Direkt/keine“                                            | Fehlender oder verborgener Referrer bzw. UTM; reproduzieren Sie dies mit einem getaggten öffentlichen Link                                              |
| Der Export weicht von der Anzeige ab                                     | Gleiche Filter und gleiches Datum zum Zeitpunkt des Exports und ob sich Live-Daten danach geändert haben                                                |

## Conversion und Geschäftsergebnisse [#conversion-und-geschäftsergebnisse]

Der Website-Funnel folgt nun den erfassten Ereignissen **Besuch → Konversation → Lead** in dieser Reihenfolge, für denselben Besucher am selben UTC-Tag. Jeder Schritt zeigt die Anzahl, die Conversion vom vorherigen Schritt und den beobachteten Abbruch. Die Medianzeit misst die Dauer vom Besuch bis zum Abschluss des Leads. Voreingestellte Zeiträume umfassen UTC-Kalendertage einschließlich des heutigen Tages; der heutige Tag ist unvollständig.

Fahren Sie mit der Maus über das Trenddiagramm, tippen Sie darauf oder nutzen Sie die Pfeiltasten, um genaue Tageswerte anzuzeigen. Die Conversion-Ansicht stellt einen Prozentwert aus dem geordneten Website-Funnel dar. Klappen Sie **Tägliche Daten anzeigen** auf, um eine barrierefreie Tabelle zu erhalten. Mit den Spaltenüberschriften der Quellentabelle sortieren Sie nach Anzahl oder Conversion; die Auswahl einer Quelle wendet den URL-Filter an.

**Lead-Qualifizierung** zeigt den aktuellen Status der Leads, die im ausgewählten Zeitraum erstellt wurden. **Checkout-Ergebnisse** zeigt native Checkout-Status und bezahlte Beträge nach Währung, ohne Testzahlungen. Externe Bestellungen erfordern eine verifizierte Integration; keine erfassten Checkouts bedeuten nicht, dass es keine Verkäufe gab. Bestehende Verkaufschancen werden nach aktueller Phase angezeigt, mit vom Team erfassten Verlustgründen. Diese Bereiche verwenden den Zeitraum über alle Quellen und Modi hinweg.

**Kommunikations-Channels** trennt tatsächliche Web-, Sprach- und Messaging-Plattformen. Es zählt aktive Konversationen, eingehende Nachrichten, Antworten des Agents und Antworten von Mitarbeitenden. Antworten sind keine Lösungen. Links zum Posteingang öffnen den Channel-Verlauf mit eigenen Filtern. Alle neuen Tabellen sind in den Berichtsexporten enthalten.

---

# Broadcasts

Source: /de/docs/operate/broadcasts.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Empfänger&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Vorlage&#x22;, icon: &#x22;message&#x22; }, { label: &#x22;Warteschlange&#x22;, icon: &#x22;bolt&#x22; }]" />

<TutorialVideo episode="ep07" start="146" />

## Aktuellen Funktionsumfang kennen [#aktuellen-funktionsumfang-kennen]

Die Broadcast-Funktion im Dashboard ist derzeit auf **Kakao AlimTalk** ausgerichtet. Sie ist kein allgemeiner Kampagnen-Composer für Telegram, WhatsApp, Messenger oder Discord. Ein aktives AlimTalk-Gateway erfordert ein registriertes Absenderprofil, eine genehmigte Vorlage, einen konfigurierten Plattform-Provider und für jeden Empfänger eine erreichbare koreanische Telefonnummer.

Die Anzahl der Empfänger wird aus nicht gelöschten Leads der aktuellen Website mit einem erreichbaren Kontaktwert ermittelt und nach Kontakt dedupliziert. Im Entwicklungs- bzw. Mock-Modus wird möglicherweise eine E-Mail-Adresse als Ersatz akzeptiert, ein echtes AlimTalk-Gateway benötigt jedoch eine passende Telefonnummer. Prüfen Sie, ob der angezeigte Modus „live“ ist, bevor Sie eine eingereihte Nachricht als echte Zustellung betrachten.

## Die Grenze beim Versand verstehen [#die-grenze-beim-versand-verstehen]

Wenn Sie auf **Senden** klicken, wird für jeden aktuell berechtigten Empfänger ein dauerhafter Job in die Warteschlange gestellt. Das Dashboard bietet derzeit keine Segmentierung pro Versand, keine Bearbeitung der Empfänger, keinen geplanten Versandzeitpunkt, keine Vorschau der Zielgruppe sowie keine Möglichkeit zum Pausieren oder Zurückrufen. Verwenden Sie die Schaltfläche erst, wenn die gesamte ermittelte Zielgruppe die Nachricht erhalten soll und dazu berechtigt ist.

Das Formular akzeptiert einen genehmigten Vorlagencode und einen Nachrichtentext mit bis zu 2.000 Zeichen. Ein Provider kann eine kürzere Vorlage, den exakten genehmigten Wortlaut bzw. die genehmigten Variablen sowie Vorgaben zu Zeitpunkt, Absenderprofil und Richtlinien durchsetzen. Das Einreihen in die Warteschlange durch Make Agent Fast setzt diese Regeln nicht außer Kraft.

## Einen rechtskonformen Broadcast vorbereiten [#einen-rechtskonformen-broadcast-vorbereiten]

1. Vergewissern Sie sich, dass beim Lead-Erfassungsprozess der Website der relevante Kontakt sowie die Einwilligung bzw. Rechtsgrundlage abgefragt wurden.
2. Entfernen oder löschen Sie Personen, die nicht kontaktiert werden sollen, bevor die Zielgruppe ermittelt wird.
3. Prüfen Sie, dass ein aktiver AlimTalk-Provider und ein registrierter Sender Key konfiguriert sind.
4. Holen Sie den vom Provider genehmigten Vorlagencode ein und stimmen Sie den Nachrichtentext auf diese Vorlage ab.
5. Prüfen Sie Absenderidentität, Zweck, Links, erforderliche Pflichtangaben und die Möglichkeit zur Abmeldung.
6. Verwenden Sie eine separate Test-Website bzw. Testzielgruppe, wenn Sie einen kleinen Produktivtest benötigen; der aktuelle Composer richtet sich an alle berechtigten Leads seiner Website.

Senden Sie keine Zugangsdaten, sensiblen Kontodetails, geschützten Datensätze, erfundenen Personalisierungen oder Angebote, die der Agent bzw. die Website nicht freigegeben hat.

## In die Warteschlange stellen und beobachten [#in-die-warteschlange-stellen-und-beobachten]

Nach dem Versand zeigt der Verlauf den Nachrichtentext, den Status, die vorgesehene Empfängeranzahl und die Anzahl erfolgreicher Sendungen. Jobs sind pro Broadcast und Lead idempotent, sodass ein erneuter Versuch der Warteschlange nicht absichtlich eine zweite Kopie desselben Broadcast-Empfänger-Paares erzeugen sollte.

„Gesendet“ bedeutet, dass das konfigurierte Gateway alle nachverfolgten Sendungen akzeptiert hat. Es belegt weder die Zustellung auf dem Telefon noch das Lesen, eine Conversion oder eine gültige Marketing-Einwilligung. Nutzen Sie, sofern verfügbar, die Zustellbestätigungen des Gateways und Ihr Business-Reporting.

Wenn einzelne Jobs fehlschlagen, behält der Broadcast den letzten Provider-Fehler bei, während erfolgreiche Sendungen unabhängig davon hochgezählt werden. Erstellen Sie keinen neuen identischen Broadcast, bevor Sie geklärt haben, ob der Provider frühere Versuche bereits akzeptiert hat.

## API-Automatisierung [#api-automatisierung]

Verwenden Sie `broadcasts:write`, um über die Public API von einem vertrauenswürdigen Server aus einen Entwurf zu erstellen und in die Warteschlange zu stellen. Bewahren Sie die Idempotenz und prüfen Sie die Ermittlung der Empfänger sowie die Provider-Bereitschaft. Die API kann eine nicht genehmigte AlimTalk-Vorlage nicht konform machen.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                           | Prüfen                                                                                                                                       |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Die Schaltfläche „Senden“ ist deaktiviert         | Keine berechtigten Leads der Website mit erreichbarem Kontakt vorhanden                                                                      |
| Der Modus zeigt lokal/Dev an                      | Der aktive AlimTalk-Provider bzw. die Zugangsdaten sind nicht konfiguriert; keine echte Zustellung an Customers                              |
| Das Gateway lehnt die Vorlage ab                  | Genehmigter Vorlagencode, Nachrichtentext/Variablen, Absenderprofil und Empfängerformat                                                      |
| Die Empfängeranzahl enthält unbrauchbare Kontakte | Für die echte Zustellung wird eine Telefonnummer benötigt; bereinigen Sie die Lead-Erfassung bzw. die Daten vor dem Versand                  |
| Der Verlauf bleibt bei „Wird gesendet“            | Fehler in Warteschlange/Provider sowie `sent count` im Vergleich zur Empfängeranzahl                                                         |
| Nur ein Segment soll kontaktiert werden           | Wird in diesem Composer derzeit nicht unterstützt; richten Sie einen genehmigten separaten Zielgruppen-Workflow ein, statt an alle zu senden |

Stoppen Sie den Versand, sobald Beschwerden, unerwartete Empfänger, Abweichungen bei der Vorlage oder Provider-Fehler auftreten.

---

# Unterhaltungen und Leads

Source: /de/docs/operate/conversations.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;message&#x22;, title: &#x22;Zusammengeführte Threads&#x22;, description: &#x22;Verläufe aus Web, Sprache, Echtzeit und Connectors erscheinen in einem Posteingang, in dem Sie eingreifen und antworten können.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;Fundierung&#x22;, description: &#x22;Antworten des Assistenten zeigen gespeicherte Quellenangaben an, sofern diese verfügbar sind.&#x22; },
{ icon: &#x22;account&#x22;, title: &#x22;Leads&#x22;, description: &#x22;Erfasste Namen, E-Mail-Adressen und Anliegen unterstützen eine gezielte Nachverfolgung.&#x22; }
]"
/>

<TutorialVideo episode="ep06" />

## Den zusammengeführten Posteingang lesen [#den-zusammengeführten-posteingang-lesen]

Öffnen Sie die Seite **Unterhaltungen** eines Agents, um die 30 neuesten Threads aus gehostetem bzw. eingebettetem Web-Chat, Sprachnachrichten, Live-Anruf-Transkripten, Telegram, WhatsApp, Messenger, Instagram, Discord und KakaoTalk zu sehen. Mit **Mehr laden** gehen Sie anhand der Zeit der letzten Aktivität weiter zurück.

Jede Zeile zeigt den Channel, die bestmögliche verfügbare Identität des Besuchers, eine Vorschau der letzten Nachricht, die Nachrichtenanzahl und die letzte Aktivität. Öffnen Sie eine Zeile, um das vollständige gespeicherte Transkript mit Zeitstempeln zu lesen. Antworten des Assistenten können die Quelle und den Abschnitt anzeigen, die für eine fundierte Antwort erfasst wurden.

Sie können auch selbst in eine Unterhaltung eingreifen. Auf der Thread-Seite können Sie mit **Als Person antworten** dem Besucher schreiben und **Antwort senden** auswählen. Eine Antwort pausiert den Agent für 30 Minuten, damit er nicht dazwischenfunkt; **Agent 30 Min. pausieren** pausiert ihn ohne Antwort, und mit **Agent fortsetzen** übergeben Sie die Unterhaltung vorzeitig wieder an ihn. Die Pause endet außerdem von selbst. Antworten des Owners funktionieren für Website-Chats sowie für Chats in Telegram, WhatsApp, Messenger und Instagram; Antworten in Messaging-Channels werden in die Warteschlange gestellt und vom Channel zugestellt. Discord, KakaoTalk, Telegram-Gastchats und Live-Anruf-Transkripte können nicht über das Dashboard beantwortet werden – antworten Sie in der ursprünglichen Messaging-App. Dieselben Aktionen stehen der öffentlichen API mit `conversations:write` zur Verfügung.

## Grenzen der Identität verstehen [#grenzen-der-identität-verstehen]

Web, Live-Sprache und jeder Connector verwenden unterschiedliche Besucherkennungen. Ein Telegram-Nutzer, ein Browser-Besucher und eine WhatsApp-Nummer sind getrennte Identitäten, sofern Sie keine ausdrücklichen, per Einwilligung erteilten Verknüpfungsdaten haben. Ähnliche Anzeigenamen sind kein Beweis dafür, dass zwei Threads zur selben Person gehören.

Connector-Bezeichnungen können den Bot, die Seite oder die Anwendung statt des Besuchers kennzeichnen, wenn die externe Plattform keine sichere Anzeigeidentität bereitstellt. Behandeln Sie Channel-IDs und abgeleitete Namen als nicht vertrauenswürdige Metadaten, nicht als Autorisierung.

## Antwortqualität prüfen [#antwortqualität-prüfen]

Gehen Sie bei einem repräsentativen Thread wie folgt vor:

1. Lesen Sie die Frage des Besuchers im Kontext, statt nur die letzte Antwort zu beurteilen.
2. Prüfen Sie, ob die Antwort die Vorgaben zu Persona und Sprache einhält.
3. Sehen Sie sich die angezeigten Fundierungsquellen an und vergleichen Sie sie mit der aktuellen Version der Wissensbasis.
4. Notieren Sie unbeantwortete, wiederholte, irreführende oder unnötige Rückfragen.
5. Ergänzen Sie einen validierten fehlenden Fakt in der Wissensbasis bzw. den FAQ und testen Sie ihn in einer neuen Unterhaltung.

Bisherige Nachrichten werden nicht neu geschrieben, wenn sich eine Wissensquelle ändert. Starten Sie nach einer Aktualisierung einen neuen Thread für Regressionstests.

## Leads erfassen und verwalten [#leads-erfassen-und-verwalten]

Die Lead-Erfassung kann den Namen, die E-Mail-Adresse und das genannte Anliegen eines Besuchers speichern, sofern der Ablauf des Agents dies zulässt. Aktuelle Leads erscheinen unter **Analysen**. Dort kann ein Owner eine freigegebene Nachverfolgung erstellen bzw. senden, Lead-Daten exportieren oder einzelne Leads löschen.

Fragen Sie nur nach Informationen, die für den angegebenen Zweck erforderlich sind. Eine Produktfrage oder Chat-Nachricht begründet nicht automatisch eine Einwilligung für Marketing. Bestätigen Sie vor der Nachverfolgung den Channel, den Zweck, die Rechtsordnung und die geltenden Anforderungen an den Opt-out.

Generierter Nachverfolgungstext ist ein Entwurf. Prüfen Sie vor dem Senden Empfänger, Aussagen, Links, Preise, Tonalität und personenbezogene Daten. Lassen Sie den Agent niemals ein Angebot oder Versprechen erfinden, das nicht in der maßgeblichen Wissensbasis steht.

## Sicher exportieren und löschen [#sicher-exportieren-und-löschen]

Ein Lead-Export erzeugt eine nachgelagerte Kopie unter Ihrer Kontrolle. Speichern Sie sie nur in freigegebenen Systemen, beschränken Sie den Zugriff und beziehen Sie sie in Ihre Aufbewahrungs- und Löschverfahren ein. Das Löschen eines Leads entfernt diesen Lead-Datensatz, löscht aber möglicherweise nicht eine zugehörige Unterhaltung, Provider-Nachricht, frühere Exporte, Benachrichtigung oder gesetzlich aufzubewahrende Abrechnungsdaten.

Auch das Trennen einer Einbettung oder eines Connectors löscht deren bisherige Threads nicht automatisch. Folgen Sie dem Datenschutz-Workflow des Kontos, wenn ein Besucher eine Lösch- oder Auskunftsanfrage stellt, und entfernen Sie auch nachgelagerte Kopien.

## Routine für die laufende Überprüfung [#routine-für-die-laufende-überprüfung]

* Täglich während des Launchs: Prüfen Sie neue Threads, Handoffs, Provider-Fehler und Antworten mit hohem Risiko.
* Wöchentlich: Gruppieren Sie wiederkehrende Fragen, erkennen Sie Wissenslücken und prüfen Sie den Status der Lead-Nachverfolgung.
* Nach Änderungen an Inhalten oder Modell: Führen Sie das Abnahme-Set erneut aus und prüfen Sie die Quellenangaben.
* Nach einem Vorfall: Sichern Sie unbedenkliche Zeitstempel und IDs, grenzen Sie den betroffenen Channel ein und vermeiden Sie es, unveränderte private Transkripte weiterzugeben.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                             | Prüfen                                                                                                                                          |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Erwarteter Thread fehlt                             | Richtige Website, Zustellung im Channel, letztes Connector-Ereignis, abgeschlossener öffentlicher Test und Zeitpunkt der Aktivität              |
| Thread wird mit weniger Gesprächsbeiträgen geöffnet | Ob die Quelle ein Live-Transkript, ein Connector-Verlauf oder eine andere Besucher- bzw. Channel-Identität war                                  |
| Quellenangabe fehlt                                 | Die Antwort hat möglicherweise kein abrufbares Wissen genutzt, oder ältere Datensätze enthalten keine Metadaten zu Quellenangaben               |
| Dieselbe Person erscheint zweimal                   | Bei getrennten Browser- bzw. Channel-Kennungen zu erwarten; führen Sie Threads nicht allein anhand des Namens zusammen                          |
| Nachverfolgung nicht verfügbar                      | E-Mail-Adresse bzw. Kontakt des Leads, Zugriffsstatus, Versandkonfiguration, Ratenbegrenzungen und Anforderungen an die Prüfung durch den Owner |

---

# Monetarisierung

Source: /de/docs/operate/monetization.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Angebote&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;Checkout&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Bestellungen&#x22;, icon: &#x22;chart&#x22; }]" />

## Die zwei Abrechnungsbeziehungen verstehen [#die-zwei-abrechnungsbeziehungen-verstehen]

Mit der **Monetarisierung** kann ein Website-Betreiber einem Besucher ein Angebot verkaufen. Sie ist unabhängig vom Make Agent Fast-Tarif und von den Credit-Paketen des Owners. Umsätze und Bestelldaten des Creators sowie die Plattformnutzung des Owners müssen getrennt abgeglichen werden.

Die Seite zeigt den aktuellen Checkout-Modus an. **Polar (Live-Zahlungen)** kann konfigurierte echte Käufe annehmen. **Lokal/Dev (Testmodus)** dient dem Entwicklungsverhalten und darf niemals als abgerechnete Zahlung im Produktivbetrieb dargestellt werden.

## Ein Angebot erstellen [#ein-angebot-erstellen]

Wählen Sie eine der unterstützten Arten:

| Typ                                  | Vorgesehener Einsatz                                                    |
| ------------------------------------ | ----------------------------------------------------------------------- |
| **Kostenpflichtiger Zugang**         | Ein exklusives Agent-Erlebnis nur für Mitglieder freischalten           |
| **Kostenpflichtiger Anruf/Beratung** | Eine Beratung oder ein Gespräch verkaufen                               |
| **Trinkgeld**                        | Unterstützung zu einem festen Preis oder zu einem frei wählbaren Betrag |
| **Digitales Gut**                    | Ein klar definiertes digitales Ergebnis bzw. einen Zugang verkaufen     |

Geben Sie einen aussagekräftigen Titel, eine Beschreibung, den Preis in Cent, die Währung und optional einen Polar-Produktschlüssel an. Der Schlüssel ordnet das Angebot einem konfigurierten Produkt beim Zahlungsanbieter zu. Ein aktives Angebot kann in der Agent-Unterhaltung angezeigt oder empfohlen werden; ein inaktives Angebot bleibt für den Owner sichtbar, sollte aber nicht verkauft werden.

Verwenden Sie eine maßgebliche Quelle für Preis, Lieferung bzw. Erfüllung, Verfügbarkeit, Rückerstattungsbedingungen, steuerliche Behandlung und Support. Fügen Sie diese freigegebenen Fakten zur Wissensbasis hinzu; der Agent darf keine Rabatte, Garantien, Lieferzeiten oder Verknappungsaussagen erfinden.

## Den Agent hinter kostenpflichtigem Zugang absichern [#den-agent-hinter-kostenpflichtigem-zugang-absichern]

Erstellen und aktivieren Sie zuerst ein Angebot vom Typ **Kostenpflichtiger Zugang** und wählen Sie es dann unter **Agent nur für Mitglieder** aus. Besucher, die den Zugang noch nicht freigeschaltet haben, erhalten statt des normalen Chat-Zugangs einen Kauf- bzw. Freischaltungsweg. Es können nur aktive Zugangsprodukte ausgewählt werden; außerdem greift zur Laufzeit ein „Fail-open“-Verhalten, damit der Chat nicht dauerhaft blockiert ist, falls ein ausgewähltes Angebot verschwindet.

Testen Sie vor dem Start folgende Fälle: nicht angemeldeter bzw. neuer Besucher, erfolgreicher Checkout, erneuter Zugang, abgebrochener Checkout, doppeltes Anbieter-Ereignis, inaktives Angebot sowie Rückerstattung bzw. Entzug des Zugangs.

## Checkout-Kanäle konfigurieren [#checkout-kanäle-konfigurieren]

Für den Live-Checkout mit Polar müssen die Plattform-Bereitstellung und die Produktzuordnung konfiguriert sein. Eine optionale Einstellung für koreanische Zahlungsarten kann KakaoPay/Naver Pay/Toss ausschließlich für Angebote in KRW anbieten, und nur wenn die Plattform diesen Kanal als verfügbar meldet; das Aktivieren eines nicht verfügbaren Schalters erzeugt keine Anbieterintegration.

Nutzen Sie, wo unterstützt, den Testmodus des Anbieters und prüfen Sie anschließend gemäß Ihren betrieblichen Richtlinien einen kleinen echten Kauf. Bestätigen Sie die kleinste Währungseinheit: Für USD bedeutet `2500` `$25.00`. Raten Sie nicht, wie sich Cent-Beträge bei einer Währung mit abweichenden Konventionen für die kleinste Einheit verhalten.

## Bestellungen und Umsatz prüfen [#bestellungen-und-umsatz-prüfen]

Die Seite zeigt die Anzahl bezahlter Bestellungen, die Umsatzsumme und die letzten Käufe. „Bezahlt“ spiegelt den erfassten Checkout- bzw. Anbieterstatus wider; gleichen Sie Anbietergebühren, Steuern, Rückerstattungen, Rückbuchungen, Auszahlungen und die Erfüllung im jeweils zuständigen Finanzsystem ab.

Das Löschen eines Angebots entfernt keine historischen Bestell- oder Abrechnungsdaten. Deaktivieren ist sicherer als Löschen, wenn ein Operator die bestehende Konfiguration für eine Untersuchung benötigt.

## Optionale ergebnisbasierte Preisgestaltung [#optionale-ergebnisbasierte-preisgestaltung]

Mit **Pay per outcome** kann zusätzlich zur normalen Nutzung ein fester Credit-Betrag vom Wallet des Owners abgebucht werden – für einen vom Agent qualifizierten Lead oder für eine Terminanfrage, die später von einem Menschen bestätigt wird. Dies ist kein Besucher-Checkout und wird nicht zum Umsatz des Creators. Eine Qualifizierung durch den Agent ist keine Annahme durch den menschlichen Vertrieb, und eine Terminanfrage ist kein bestätigter Termin. Lassen Sie diesen Modus deaktiviert, sofern der Owner die zusätzliche Credit-Belastung und die genauen Ereignisdefinitionen nicht verstanden hat.

## Checkliste vor dem Start [#checkliste-vor-dem-start]

* Der Live-/Test-Checkout-Modus ist unmissverständlich erkennbar.
* Titel, Beschreibung, Währung und Preis des Angebots stimmen mit dem Produkt beim Anbieter überein.
* Erfüllung, Zugangsdauer, Rückerstattungen, Steuern, Support und Datenschutz sind dokumentiert.
* Das Wissen des Agents enthält nur freigegebene kommerzielle Aussagen.
* Die Abläufe für Erfolg, Abbruch, Duplikate, Rückerstattung und inaktive Angebote sind getestet.
* Kaufbenachrichtigungen, Verantwortliche für die Erfüllung, Buchhaltungsabgleich und Incident-Prozess sind festgelegt.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                            | Prüfen                                                                                                     |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Angebot erscheint nicht                            | Es ist aktiv, für die Unterhaltung relevant und der Website-Status ist aktuell                             |
| Live-Checkout nicht verfügbar                      | Konfiguration der Zahlungsabwicklung in der Bereitstellung und Produktschlüssel des Angebots beim Anbieter |
| Zugang bleibt nach Zahlung gesperrt                | Erfasster Kaufstatus, korrekter Besucher bzw. korrekte Sitzung, Webhook des Anbieters und Angebots-ID      |
| Schalter für koreanische Zahlungsarten wirkt nicht | Der Plattformkanal ist nicht konfiguriert bzw. verfügbar oder die Angebotswährung wird nicht unterstützt   |
| Umsatz weicht von der Auszahlung ab                | Anbietergebühren, Rückerstattungen, Rückbuchungen, Steuern, Abwicklungszeitpunkt und Währung               |
| Credits des Owners sinken nach Ergebnissen         | Die optionale ergebnisbasierte Preisgestaltung ist zusätzlich zur normalen Nutzung aktiviert               |

---

# Benachrichtigungen

Source: /de/docs/operate/notifications.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Lead&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Handoff&#x22;, icon: &#x22;message&#x22; }, { label: &#x22;Buchung&#x22;, icon: &#x22;bolt&#x22; }]" />

<TutorialVideo episode="ep06" start="95" />

## Was hier angezeigt wird [#was-hier-angezeigt-wird]

Die Seite **Benachrichtigungen** des Agents ist ein Ereignis-Feed im Dashboard. Sie erfasst die folgenden Ereignistypen, die für den Owner relevant sind:

| Typ                                                         | Bedeutung                                                                       |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Neue Kundenanfrage** (Lead)                               | Der Agent hat einen Kontakt- bzw. Anliegen-Datensatz eines Besuchers erfasst    |
| **Besucher hat nach einem Menschen gefragt** (Handoff)      | Die Unterhaltung hat eine menschliche Nachverfolgung angefordert oder ausgelöst |
| **Besucher hat geschrieben, während Sie geantwortet haben** | Ein Besucher hat geschrieben, während Sie die Unterhaltung übernommen hatten    |
| **Neue Buchung**                                            | Ein Buchungsergebnis wurde erfasst                                              |
| **Support-Ticket**                                          | Ein Support-Ticket wurde eröffnet oder aktualisiert                             |
| **Aktion benötigt Freigabe**                                | Eine vom Kunden bestätigte Änderung wartet auf Ihre Freigabe                    |
| **Aktion benötigt Aufmerksamkeit**                          | Eine freigegebene Aktion konnte nicht abgeschlossen werden                      |
| **Connector benötigt Aufmerksamkeit**                       | Ein Channel benötigt Aufmerksamkeit                                             |
| **Antwort-SLA fällig**                                      | Eine Antwortfrist im Vertrieb ist fällig                                        |
| **Concierge-Anfrage**                                       | Sie haben die Plattform gebeten, einen Channel für Sie zu verbinden             |
| **Webseite konnte nicht hinzugefügt werden**                | Eine Seite, die ein KI-Assistent hinzufügen sollte, konnte nicht gelesen werden |

Jeder Eintrag kann den Ereignistyp, den Erstellungszeitpunkt, den Namen bzw. die E-Mail-Adresse des Besuchers (sofern verfügbar) und einen kurzen Auszug anzeigen. Ein ungelesener Eintrag ist optisch hervorgehoben und wird in der Zahl der ungelesenen Benachrichtigungen mitgezählt.

Die Karte **Alerts** auf dieser Seite kann den Feed nach Telegram spiegeln: Wählen Sie **Alerts in Telegram senden**, und jede neue Benachrichtigung kommt zusätzlich als Nachricht von Ihrem eigenen verbundenen Telegram-Bot (oder vom Alerts-Bot von Make Agent Fast) bei Ihnen an. Freigabe-Alerts enthalten die Schaltflächen **Genehmigen** und **Ablehnen**. Alerts sind standardmäßig deaktiviert; der Dashboard-Feed und die E-Mail an den Owner funktionieren in jedem Fall weiter. Wenn Sie einen Eintrag als gelesen markieren, wird weder eine E-Mail an einen Besucher gesendet noch über einen Connector geantwortet, ein Lead geändert oder jemand bei einem externen Anbieter abgemeldet.

## Ereignisse prüfen und markieren [#ereignisse-prüfen-und-markieren]

1. Öffnen Sie **Benachrichtigungen** für die gewünschte Website.
2. Priorisieren Sie Handoffs und zeitkritische Buchungen.
3. Öffnen Sie den zugehörigen Kontext unter **Unterhaltungen** oder **Analysen**, wenn Identität und Anliegen bestätigt werden müssen.
4. Wählen Sie **Als gelesen markieren** erst, nachdem der zuständige Owner den Eintrag gesichtet hat.
5. Verwenden Sie **Alle als gelesen markieren** nur, wenn alle sichtbaren bzw. ungelesenen Ereignisse bewusst geprüft wurden.
6. Wählen Sie **Mehr laden**, um ältere Seiten anzuzeigen.

Der Lesestatus ist eine Arbeitshilfe für den Owner und kein Nachweis dafür, dass ein Besucher eine Rückmeldung erhalten hat. Dokumentieren Sie die tatsächliche Nachverfolgung im dafür vorgesehenen führenden System.

## Besucherdaten schützen [#besucherdaten-schützen]

Namen, E-Mail-Adressen, Buchungskontext und Auszüge können personenbezogene Daten enthalten. Beschränken Sie den Dashboard-Zugriff, kopieren Sie Ereignisse nicht in breit zugängliche Chaträume und betrachten Sie den Auszug nicht als vollständigen Einwilligungs- bzw. Kontextnachweis.

Das Löschen oder Markieren einer Benachrichtigung entfernt nicht automatisch den zugehörigen Lead, die Unterhaltung, die Buchung, den Datensatz beim Anbieter oder exportierte Kopien. Nutzen Sie für Anfragen betroffener Personen den Datenschutz- bzw. Löschprozess.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                      | Prüfen                                                                                                                                           |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Ein erwartetes Ereignis fehlt                                | Richtige Website, tatsächlicher Abschluss von Lead/Handoff/Buchung, Zeitpunkt des Ereignisses und zugehörige Unterhaltung                        |
| Die Zahl der ungelesenen Einträge wirkt veraltet             | Nach dem Markieren neu laden und prüfen, ob der Vorgang erfolgreich gemeldet wurde                                                               |
| Das Markieren als gelesen hat den Besucher nicht kontaktiert | Das ist beabsichtigt; dieser Feed sendet keine Nachverfolgung                                                                                    |
| Ein älterer Eintrag fehlt                                    | Verwenden Sie **Mehr laden**; die erste Seite ist bewusst begrenzt                                                                               |
| Sie benötigen Alerts außerhalb des Dashboards                | Aktivieren Sie Telegram in der Karte **Alerts**; für Routing per E-Mail oder im Stil von Slack nutzen Sie die Public API oder signierte Webhooks |

Für Automatisierungen nutzen Sie die unterstützten Public-API-Ressourcen oder signierte Webhook-Ereignisse, anstatt dieses Dashboard auszulesen.

---

# Credits und Nutzung

Source: /de/docs/operate/usage.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Credits&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;Sprachminuten&#x22;, icon: &#x22;voice&#x22; }, { label: &#x22;Aufladungen&#x22;, icon: &#x22;bolt&#x22; }]" />

<TutorialVideo episode="ep08" start="157" />

## Die Nutzungsseite lesen [#die-nutzungsseite-lesen]

Der Nutzungsbereich im Dashboard vereint Abrechnungsinformationen mit den Ressourcen, die einen Vorgang stoppen können: aktueller Tarif, Credit-Guthaben, Website-Kontingent, Live-Sprachminuten, Aufladeoptionen und Abrechnungsaktionen. Prüfen Sie ihn vor einem Launch und nach dem Hinzufügen eines Embeds, Connectors oder API-Clients mit hohem Volumen.

Interpretieren Sie eine einzelne Zahl nicht als allgemeine Quote. Jedes Kontingent schützt eine andere Ressource.

## Guthaben und Limits unterscheiden [#guthaben-und-limits-unterscheiden]

| Ressource             | Zurücksetzung oder Verfall                                 | Was beim Erreichen des Limits passiert                                       |
| --------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Monatliche KI-Credits | Werden um einen weiteren Zyklus übertragen, verfallen dann | Abgerechnete KI-, Wissens- und Sprachaktionen können abgelehnt werden        |
| Gekaufte Credits      | Verfallen nicht, solange ein Abonnement aktiv ist          | Finanzieren weiterhin abgerechnete Vorgänge, solange der Zugang aktiv bleibt |
| Anzahl der Websites   | Tarifkontingent                                            | Das Anlegen einer weiteren Website wird blockiert                            |
| Live-Sprachminuten    | Monatliches Tarifkontingent                                | Neue oder laufende Echtzeitsitzungen werden eingeschränkt bzw. beendet       |
| API-Anfragen          | Pro API-Schlüssel und Minute                               | Die Anfrage liefert `429` mit Retry-Headern zurück                           |

Credits erhöhen weder den API-Durchsatz noch die Anzahl der Websites oder Live-Minuten. Ein Kontingent garantiert nicht, dass der für den Vorgang erforderliche Credit- bzw. Provider-Pfad zur Verfügung steht.

## Was Credits verbraucht [#was-credits-verbraucht]

Abgerechnete Vorgänge können die Generierung von Websites und Agents, normale Agent-Antworten, Wissens-Embeddings, Medientranskription, Text-to-Speech und Connector-Sprache umfassen. Die Kosten variieren je nach Provider, Modell, Länge von Prompt und Kontext, Länge der Ausgabe, Audiodauer und Vorgangstyp. Eine „Nachricht“ hat daher keinen festen, allgemeingültigen Credit-Preis.

Vorschau- und Testaktionen des Owners können echte Ressourcen verbrauchen, wenn sie Live-Provider aufrufen. Verwenden Sie kurze, repräsentative Abnahmetests und vermeiden Sie es, dieselbe große Quelle beim Debuggen eines anderen Problems wiederholt zu indexieren.

## Nutzungsverlauf lesen [#nutzungsverlauf-lesen]

Der **Nutzungsverlauf** zeigt die tatsächlich verbrauchten finalen Credits jedes abgeschlossenen Vorgangs. Vorübergehende Autorisierungsreservierungen, Abrechnungen von Reservierungen und Erstattungen bleiben interne Buchungsdetails und erscheinen nicht als separate, für Kunden sichtbare Zeilen. Sehr kleine Embedding-Vorgänge werden als `<0.001` angezeigt statt auf null gerundet.

**Weitere Guthabenänderungen** ist eine separate Tabelle für Gutschriften von Tarif-Credits, Aufladungen, Verfall und manuelle Anpassungen. Sie dupliziert keine normale KI-Nutzung. Solange ein Vorgang noch läuft, kann das verfügbare Guthaben vorübergehend eine Reservierung widerspiegeln, bevor die finale Nutzungszeile erscheint oder ein fehlgeschlagener Vorgang freigegeben wird. Aktualisieren Sie die Seite nach Abschluss, wenn Sie eine soeben beendete Aktion abgleichen.

## Monatliche und gekaufte Credits [#monatliche-und-gekaufte-credits]

Das monatliche Kontingent richtet sich nach dem aktiven Tarif. Nicht verbrauchte monatliche Credits werden um einen weiteren Zyklus übertragen und verfallen dann. Einmalige Pakete bieten 1.000 Credits für 8 $, 5.000 für 35 $ oder 15.000 für 90 $; gekaufte Credits verfallen nicht, solange ein Abonnement aktiv ist.

Der Kauf eines Pakets stellt ein gekündigtes oder abgelaufenes Plattform-Abonnement nicht wieder her. Klären Sie zuerst Zugang und Abrechnung, wenn das Dashboard ein Kontingentproblem meldet und nicht nur ein niedriges Guthaben.

## Automatische Aufladung [#automatische-aufladung]

Die automatische Aufladung steht erst zur Verfügung, wenn das automatische Belasten von Karten für Make Agent Fast aktiviert ist; bis dahin weist die Seite darauf hin, dass sie nicht verfügbar ist. Wo sie angeboten wird, kauft sie für Sie ein Credit-Paket, sobald das Guthaben einen von Ihnen gewählten Schwellenwert erreicht. Aktivieren Sie sie unter **Nutzung & Credits → Automatische Aufladung**: Wählen Sie den Schwellenwert (zwischen 50 und 5.000 Credits) und das zu kaufende Paket. Belastet wird die Karte, die beim Zahlungsanbieter bereits hinterlegt ist; fügen Sie diese Karte über den Link zum Kundenportal neben dem Formular hinzu oder ändern Sie sie dort.

Die Schutzmechanismen sind bewusst gewählt. Es läuft immer nur ein Kauf gleichzeitig, und während er abgewickelt wird, zeigt die Seite an, dass ein Kauf in Bearbeitung ist. Pro Tag finden höchstens drei automatische Käufe statt. Die Credits erscheinen, wenn die Zahlung abgeschlossen ist, nicht bereits beim Start der Belastung. Wird die Karte abgelehnt, werden keine Credits gutgeschrieben, die Seite zeigt den letzten Fehler an, und eine E-Mail pro Tag erklärt, was zu beheben ist; die Belastung wird erst wieder versucht, wenn die Zahlungsmethode funktioniert.

Die automatische Aufladung ist nur verfügbar, wenn Off-Session-Abbuchungen aktiviert sind und eine Karte hinterlegt ist. Ist sie nicht verfügbar, teilt die Seite dies mit, anstatt einen Schalter anzuzeigen, der nichts bewirken würde.

## Add-ons [#add-ons]

Add-ons können erst gekauft werden, wenn sie zum Verkauf angeboten werden: Ein angebotenes Add-on erscheint unter **Nutzung & Credits → Add-ons**, und die Karte wird ausgeblendet, wenn keines angeboten wird. Ein Add-on, für das Sie bereits zahlen, bleibt immer aufgelistet, damit Sie es kündigen können. Angebotene Add-ons erweitern die Kapazität zusätzlich zum aktuellen Tarif, werden monatlich abgerechnet und sind jederzeit kündbar.

| Add-on             | Preis, wenn angeboten    | Hinweise                                                                               |
| ------------------ | ------------------------ | -------------------------------------------------------------------------------------- |
| Zusätzlicher Agent | 10 $ pro Agent und Monat | Mehrfach kaufbar; jedes Add-on fügt genau einen Agent-Platz hinzu. In Scale enthalten. |
| Badge entfernen    | 9 $ pro Monat            | Blendet „Made with Make Agent Fast“ im Widget aus. In Operate und Scale enthalten.     |

Ein Add-on ist ein vom Tarif getrenntes Abonnement: Die Kündigung des Add-ons berührt den Tarif nicht, und die Kündigung des Tarifs behält das Add-on nicht stillschweigend bei. Ein gekündigtes Add-on läuft bis zum Ende des bereits bezahlten Zeitraums. Nur der Abrechnungs-Owner kann ein Add-on kaufen oder kündigen.

## Abrechnung von Live-Sprache [#abrechnung-von-live-sprache]

Operate enthält 30 Live-Minuten pro Monat, Scale 90. Zusätzlich hat jeder Anruf ein vom Owner konfiguriertes automatisches Zeitlimit von 30 Sekunden bis 20 Minuten. Wenn ein Live-Anruf-Token ausgestellt wird, wird dem Wallet vorab die vom Server autorisierte maximale Dauer belastet, begrenzt durch das verbleibende Monatskontingent. Dieselbe Dauer wird auf das Live-Minuten-Kontingent angerechnet, sodass parallele Anrufe es nicht überschreiten können.

Live-Medien fließen direkt zwischen Browser und Echtzeit-Provider, daher kann der Server eine kürzere, vom Client gemeldete Dauer nicht unabhängig überprüfen. Ungenutzte Zeit wird deshalb nach Ausgabe eines Tokens nicht anteilig erstattet; eine abgebrochene oder nicht gemeldete Sitzung wird mit ihrem autorisierten Limit abgerechnet. Ein serverseitiger Fehler vor der Token-Ausgabe gibt die Belastung wieder frei. Beenden Sie Anrufe ordnungsgemäß, um die Sitzung zügig zu schließen, prognostizieren Sie Credits aber anhand des konfigurierten Anruflimits und nicht anhand der erwarteten Gesprächsdauer des Anrufers.

Sprachnachrichten funktionieren anders: Sie verbrauchen abgerechnete Transkriptions-, Modell- und Sprachleistungen statt des Live-Minuten-Kontingents. Ermitteln Sie den richtigen Bucket, wenn ein Modus funktioniert und der andere fehlschlägt.

## Nutzung prognostizieren [#nutzung-prognostizieren]

1. Wählen Sie repräsentative kurze, normale und lange Fragen von Besuchern.
2. Testen Sie Text, wissensintensive Antworten, Sprachnachrichten und Live-Anrufe getrennt.
3. Erfassen Sie die Änderungen bei Credits und Minuten für das Abnahme-Set.
4. Multiplizieren Sie mit dem erwarteten täglichen Traffic und dem Channel-Mix.
5. Planen Sie Reserven für Wiederholungsversuche, Crawls, Provider-Ausfälle, interne QA, Kampagnen und Traffic-Spitzen ein.
6. Prüfen Sie erneut, nachdem Sie Modell, Provider, Größe der Sources, Antwortlänge oder Sprachverhalten geändert haben.

Nutzen Sie Analysen und Konversationen, um die Ursache eines Anstiegs zu finden. Ein Traffic-Anstieg, ein API-Client in einer Endlosschleife, ein kompromittierter Schlüssel, ein kopiertes Embed auf einer unbeabsichtigten Origin, ein Connector-Retry oder ein wiederholter Indexierungsjob erfordern jeweils eine andere Lösung.

## Unerwartete Nutzung verhindern [#unerwartete-nutzung-verhindern]

* Beschränken Sie Embeds auf die exakt vorgesehenen Origins.
* Vergeben Sie API-Schlüsseln die kleinstmöglichen Scopes und trennen Sie Schlüssel nach Dienst und Umgebung.
* Machen Sie Mutationen idempotent und beachten Sie die Retry-Header bei `429`.
* Prüfen Sie Webhook-Signaturen und deduplizieren Sie Event-IDs.
* Rotieren Sie kompromittierte API-, Provider- und Connector-Zugangsdaten sofort.
* Halten Sie öffentliche Agents durch eine klare Persona und eindeutige Antwortanweisungen im Rahmen.
* Entfernen Sie veraltete Automatisierungen, Preview-Deployments, Connectors und ungenutzte Schlüssel.
* Benachrichtigen Sie die operativ Verantwortlichen, bevor Guthaben oder Live-Minuten gegen null gehen.

## Einen Anstieg untersuchen [#einen-anstieg-untersuchen]

Halten Sie den betroffenen Workspace bzw. die Website, den Zeitraum, den Channel, das Deployment und die letzten Änderungen fest. Vergleichen Sie die Nutzung mit Analysen, Zeitstempeln der Konversationen, API-Request-IDs, Webhook-Zustellprotokollen und dem Status des letzten Events bzw. Fehlers des Connectors. Senden Sie keine Schlüssel im Klartext und keine Inhalte von Besuchern an den Support, es sei denn, ein freigegebener sicherer Prozess verlangt dies ausdrücklich.

Beseitigen Sie zuerst die Ursache: Deaktivieren Sie einen Connector, widerrufen Sie einen Schlüssel, entfernen Sie eine unbeabsichtigte Origin oder stoppen Sie eine Retry-Schleife im Client. Sichern Sie anschließend unbedenkliche Nachweise, rotieren Sie bei Bedarf Zugangsdaten und aktivieren Sie die Pfade nacheinander wieder.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                               | Prüfen                                                                                                         |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Keine Credits mehr trotz ungenutzter Live-Minuten     | Es handelt sich um getrennte Ressourcen; fügen Sie Credits für normale KI-Vorgänge hinzu bzw. erneuern Sie sie |
| Sprachnachrichten funktionieren, Live-Anruf nicht     | Live-Kontingent des Tarifs, verbleibende Minuten, Verfügbarkeit des Echtzeit-Providers und Sitzungsstatus      |
| Aufladung gekauft, Funktion aber weiterhin gesperrt   | Pakete fügen nur Credits hinzu; prüfen Sie den Tarif und das Agent-Kontingent                                  |
| API liefert `429`, obwohl noch Credits vorhanden sind | Anfragerate pro Schlüssel; beachten Sie die Reset- und Retry-Header                                            |
| Guthaben sinkt unerwartet                             | Aktuelle Embeds, Connectors, API-Schlüssel, Indexierung, Sprache sowie Retries von Provider oder Client        |

Die aktuelle Kontingenttabelle finden Sie unter [Tarife und Preise](/de/docs/account/pricing).

---

# Benutzerdefinierte Domains

Source: /de/docs/publish/custom-domains.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/embed/overview&#x22;, label: &#x22;Embed-Übersicht&#x22;, icon: &#x22;embed&#x22; },
{ href: &#x22;/de/docs/embed/html&#x22;, label: &#x22;HTML-Snippet&#x22;, icon: &#x22;code&#x22; }
]"
/>

Make Agent Fast verkauft, verknüpft, verifiziert oder konfiguriert **keine** Kundendomains. Es gibt im Dashboard keine Möglichkeit, `yourname.com` zu verbinden oder eine Domain zu kaufen. Die eigene Adresse `slug.makeagent.fast` des Agents dient ausschließlich der Chat-Seite des **Agent-Links** und ist keine Website, die Sie konfigurieren können.

Platzieren Sie den Agent mit `embed.js` und `data-agent="<slug>"` auf Ihrer bestehenden Website. Der Slug ist die Embed-ID und zugleich die Adresse des Agent-Links. Er ist keine Domain, die Sie konfigurieren.

Übrig gebliebene Ereignisse des Polar-Add-ons für benutzerdefinierte Domains werden ignoriert oder storniert und erzeugen niemals Credits.

Siehe [Embed-Übersicht](/de/docs/embed/overview) und [HTML und JavaScript](/de/docs/embed/html).

---

# Agent link

Source: /de/docs/publish/hosted-sites.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/de/docs/build/appearance&#x22;, label: &#x22;Darstellung&#x22;, icon: &#x22;spark&#x22; },
{ href: &#x22;/de/docs/embed/overview&#x22;, label: &#x22;Einbetten&#x22;, icon: &#x22;embed&#x22; }
]"
/>

Jeder Agent erhält einen **Agent link**: eine öffentliche Chat-Seite unter `https://YOUR_SLUG.makeagent.fast`. Sie zeigt Ihr Firmenzeichen, Ihren Namen, eine Zeile dazu, was der Agent tut, einige Angaben aus Ihrem Fact sheet, den bereits geöffneten Chat und die offiziellen Zeichen Ihrer verbundenen Channels. Es ist ein Link zum Chat, keine Website und keine Startseite. **Neue Agents erhalten keine gehostete Marketing-Seite** – generierte Marketing-Websites gibt es nicht mehr, und der wichtigste Weg zu Ihren Customers bleibt das Einbetten auf Ihrer bestehenden Website. Siehe [Übersicht zum Einbetten](/de/docs/embed/overview).

Bereits veröffentlichte Tenant-Seiten (einschließlich der öffentlichen Demos `demo` und `demo-business`) werden weiterhin unter ihren Subdomains als Überbleibsel ausgeliefert. Eigene Domains werden nicht angeboten. Der Slug ist die Embed-ID (`data-agent`) und die Adresse des Agent link, keine Domain, die Sie konfigurieren.

<TutorialVideo episode="ep02" start="141" />

## Der Slug ist weiterhin die Embed-ID [#der-slug-ist-weiterhin-die-embed-id]

Verwenden Sie einen kurzen Namen, den Sie wiedererkennen. Ein gültiger Slug darf nicht mit einem anderen Tenant oder einer reservierten Plattform-Route wie `docs`, `dashboard` oder `api` kollidieren. Behandeln Sie ihn als öffentliche Information. Wenn Sie ihn nach dem Start ändern, können Einbettungen und der Agent link nicht mehr funktionieren.

## Der Agent link [#der-agent-link]

Im letzten Onboarding-Schritt wird der Agent link aktiviert, damit Sie den Agent unter **Auf dem Handy testen** auf Ihrem Smartphone ausprobieren können. Später können Sie ihn mit **Agent link** auf dem Tab **Darstellung** der Agent-Seite ein- oder ausschalten; solange er eingeschaltet ist, werden der Link und sein QR-Code angezeigt. Wenn Sie ihn ausschalten, wird der Link offline genommen und Ihre Auswahl gespeichert. Ein Link, dessen Inhalt die Spam-Prüfungen auslöst, kann nicht live gehen.

Die Seite wird nicht von Suchmaschinen indexiert. Teilen Sie sie dort, wo kein Skript ausgeführt werden kann – etwa in einem Naver-Place-Eintrag, einem Kakao-Channel, einer Instagram-Bio, einer E-Mail-Signatur oder als gedruckten QR-Code.

Änderungen unter **Darstellung** (und am Branding-Badge) werden automatisch gespeichert und aktualisieren das Live-Embed, das Widget auf dem Agent link und jede übrig gebliebene gehostete Seite, ohne erneute Veröffentlichung. Siehe [Aussehen](/de/docs/build/appearance).

## Weitere Oberflächen verbinden [#weitere-oberflächen-verbinden]

Messaging-Connectors leiten in denselben Agent, behalten aber eine auf den jeweiligen Channel begrenzte Konversationsidentität. Wenn Sie das Website-Widget einschalten, wird das Snippet nicht automatisch installiert und es werden auch keine Provider-Webhooks konfiguriert; schließen Sie diese Anleitungen separat ab.

Für Notion, Linktree und andere Oberflächen, die kein beliebiges JavaScript laden können, teilen Sie den Agent link oder verlinken Sie auf eine Seite Ihrer eigenen Website, die das Embed enthält. Siehe [Notion und Linktree](/de/docs/embed/notion-linktree).

## Veröffentlichung aufheben [#veröffentlichung-aufheben]

Wenn Sie den Agent link ausschalten (oder `POST /sites/{site_id}/publish` mit `{ "published": false }` aufrufen), werden die öffentliche Chat-Seite und jede übrig gebliebene gehostete Seite offline genommen. Das Ausblenden des Website-Widgets mit **Auf meiner Website anzeigen** ist ein separater Schalter. Keiner von beiden löscht die Website, die Sources, die Agents, den Konversationsverlauf oder die externe Provider-Konfiguration. Verbundene Messaging-Bots antworten möglicherweise weiter; deaktivieren bzw. entfernen Sie jeden Connector separat.

## Fehlerbehebung [#fehlerbehebung]

| Symptom                                                       | Prüfen                                                                                                                                    |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Der Agent link meldet „nicht verfügbar“ bzw. „nicht gefunden“ | **Agent link** ist auf dem Tab **Darstellung** eingeschaltet, der genaue Slug und aktiver Kontozugriff                                    |
| Eine Änderung im Dashboard erscheint nicht                    | Richtiger Agent, der Hinweis **Gespeichert** neben der Änderung und ein Test des **Embeds** oder des Agent link in einem privaten Fenster |
| Der Connector antwortet, obwohl das Embed ausgeschaltet ist   | Erwartetes Verhalten; deaktivieren Sie den Connector separat, wenn jeder Channel-Zugriff beendet werden muss                              |

---

# KI-Assistenten verbinden

Source: /de/docs/tutorials/ai-assistants.md

<TutorialEpisode
  episode="ep10"
  chapters="[
[0, &#x22;Einführung&#x22;],
[12, &#x22;Was Ihre KI-App leisten kann&#x22;],
[33, &#x22;Einrichtungsseite des Agenten&#x22;],
[46, &#x22;Setup-Prompt kopieren&#x22;],
[58, &#x22;In Claude einfügen und bestätigen&#x22;],
[87, &#x22;Nach Ihren Agenten fragen&#x22;],
[107, &#x22;Wochenbericht&#x22;],
[119, &#x22;Eine bessere Antwort speichern&#x22;],
[130, &#x22;Codex&#x22;],
[147, &#x22;Cursor und ChatGPT&#x22;],
[165, &#x22;Zugriff widerrufen&#x22;],
[177, &#x22;Zusammenfassung&#x22;]
]"
/>

## Verwandte Anleitungen [#verwandte-anleitungen]

* [Claude, Codex, Cursor und ChatGPT verwenden](/de/docs/operate/ai-assistants)
* [Einrichtung des Agenten](/connect)

---

# Analysen, Team & Abrechnung

Source: /de/docs/tutorials/analytics-team-billing.md

<TutorialEpisode
  episode="ep08"
  chapters="[
[0, &#x22;Einführung&#x22;],
[13, &#x22;Kennzahlen und Vergleich&#x22;],
[31, &#x22;Trends&#x22;],
[46, &#x22;Funnel und wichtigste Sources&#x22;],
[65, &#x22;Was Besucher fragen&#x22;],
[85, &#x22;Team und Zugriff&#x22;],
[116, &#x22;Benachrichtigungen&#x22;],
[132, &#x22;Ihr Tarif&#x22;],
[157, &#x22;Nutzung und Credits&#x22;],
[191, &#x22;Zusammenfassung&#x22;]
]"
/>

## Verwandte Anleitungen [#verwandte-anleitungen]

* [Analysen](/de/docs/operate/analytics)
* [Credits und Nutzung](/de/docs/operate/usage)
* [Tarife und Preise](/de/docs/account/pricing)
* [Sicherheit](/de/docs/account/security)

---

# Ihren Agent erstellen

Source: /de/docs/tutorials/build-agent.md

<TutorialEpisode
  episode="ep01"
  chapters="[
[0, &#x22;Einführung&#x22;],
[14, &#x22;Neuen Agent erstellen&#x22;],
[33, &#x22;Website, Name, Aufgabe und Sprachen&#x22;],
[61, &#x22;Erstellung aus Ihrer Website&#x22;],
[82, &#x22;Drei Schnellprüfungen&#x22;],
[110, &#x22;Festlegen, wo der Agent antwortet&#x22;],
[129, &#x22;Die Agent-Seite&#x22;],
[153, &#x22;Ihren Agent testen&#x22;],
[168, &#x22;Wissen und Fragen & Antworten hinzufügen&#x22;],
[218, &#x22;Zusammenfassung&#x22;]
]"
/>

## Weiterführende Anleitungen [#weiterführende-anleitungen]

* [Einen Agent erstellen](/de/docs/build/create-agent)
* [Wissensquellen](/de/docs/build/knowledge)
* [Schnellstart](/de/docs/getting-started/quickstart)

---

# Ihr Posteingang

Source: /de/docs/tutorials/inbox.md

<TutorialEpisode
  episode="ep06"
  chapters="[
[0, &#x22;Einführung&#x22;],
[14, &#x22;Konversationen und Filter&#x22;],
[37, &#x22;Eine Konversation öffnen&#x22;],
[50, &#x22;Als Mensch antworten&#x22;],
[71, &#x22;Eine Antwort überarbeiten&#x22;],
[95, &#x22;Benachrichtigungen&#x22;],
[117, &#x22;Benachrichtigungen auf Ihrem Smartphone&#x22;],
[134, &#x22;Genehmigungen&#x22;],
[151, &#x22;Tickets&#x22;],
[171, &#x22;Zusammenfassung&#x22;]
]"
/>

## Weiterführende Anleitungen [#weiterführende-anleitungen]

* [Konversationen und Leads](/de/docs/operate/conversations)
* [Benachrichtigungen](/de/docs/operate/notifications)
* [Aktionen ändern](/de/docs/build/change-actions)

---

# Instagram: DMs & Kommentare

Source: /de/docs/tutorials/instagram.md

<TutorialEpisode
  episode="ep05"
  chapters="[
[0, &#x22;Einführung&#x22;],
[15, &#x22;Was Sie benötigen&#x22;],
[32, &#x22;Mit Meta verbinden&#x22;],
[46, &#x22;Konto auswählen&#x22;],
[60, &#x22;DM testen und KI-Antworten aktivieren&#x22;],
[78, &#x22;Ihr Agent in Instagram-DMs&#x22;],
[95, &#x22;Kommentarantworten (demnächst verfügbar)&#x22;],
[134, &#x22;Instagram-Chats unter „Unterhaltungen“&#x22;],
[154, &#x22;Zusammenfassung&#x22;]
]"
/>

## Zugehörige Anleitungen [#zugehörige-anleitungen]

* [Instagram](/de/docs/connectors/instagram)
* [Unterhaltungen und Leads](/de/docs/operate/conversations)

---

# Leads & Vertriebspipeline

Source: /de/docs/tutorials/leads-sales.md

<TutorialEpisode
  episode="ep07"
  chapters="[
[0, &#x22;Einführung&#x22;],
[14, &#x22;Vertriebsaufgabe festlegen&#x22;],
[33, &#x22;Vertriebspipeline und Leads&#x22;],
[62, &#x22;Opportunity-Board&#x22;],
[90, &#x22;Antwortrichtlinie und Kontaktberechtigung&#x22;],
[108, &#x22;Opportunity-Datensatz&#x22;],
[123, &#x22;Vertriebspakete und geführte Pilotprojekte&#x22;],
[146, &#x22;KakaoTalk-Broadcast&#x22;],
[168, &#x22;Zusammenfassung&#x22;]
]"
/>

## Verwandte Anleitungen [#verwandte-anleitungen]

* [Broadcasts](/de/docs/operate/broadcasts)
* [Konversationen und Leads](/de/docs/operate/conversations)

---

# Messenger, Discord & KakaoTalk

Source: /de/docs/tutorials/more-channels.md

<TutorialEpisode
  episode="ep09"
  chapters="[
[0, &#x22;Einführung&#x22;],
[15, &#x22;Überall dasselbe Prinzip&#x22;],
[31, &#x22;Messenger: Wir verbinden ihn für Sie&#x22;],
[55, &#x22;Messenger: Ihre eigenen Zugangsdaten&#x22;],
[67, &#x22;Messenger: Webhook&#x22;],
[89, &#x22;Discord Developer Portal&#x22;],
[107, &#x22;Discord verbinden&#x22;],
[123, &#x22;/ask in Discord verwenden&#x22;],
[145, &#x22;KakaoTalk: Checkliste für Open Builder&#x22;],
[171, &#x22;KakaoTalk: Zugangsdaten und Bot-Secret&#x22;],
[196, &#x22;KakaoTalk in Aktion&#x22;],
[218, &#x22;Zusammenfassung&#x22;]
]"
/>

## Verwandte Anleitungen [#verwandte-anleitungen]

* [Messenger](/de/docs/connectors/messenger)
* [Discord](/de/docs/connectors/discord)
* [KakaoTalk](/de/docs/connectors/kakao)

---

# Telegram: Bots & Gruppen

Source: /de/docs/tutorials/telegram.md

<TutorialEpisode
  episode="ep03"
  chapters="[
[0, &#x22;Einführung&#x22;],
[15, &#x22;Der Plan&#x22;],
[27, &#x22;Channels öffnen&#x22;],
[45, &#x22;Bot mit BotFather erstellen&#x22;],
[80, &#x22;Token einfügen und verbinden&#x22;],
[103, &#x22;Channel-Test und KI-Antworten aktivieren&#x22;],
[132, &#x22;Erster privater Chat&#x22;],
[151, &#x22;Gruppenantworten einschalten&#x22;],
[167, &#x22;Bot zu einer Gruppe hinzufügen&#x22;],
[182, &#x22;Verhalten in Gruppen&#x22;],
[202, &#x22;Gruppenregeln und ein Profi-Tipp&#x22;],
[224, &#x22;Telegram-Chats in Conversations&#x22;],
[243, &#x22;Zusammenfassung&#x22;]
]"
/>

## Weiterführende Anleitungen [#weiterführende-anleitungen]

* [Telegram](/de/docs/connectors/telegram)
* [Konversationen und Leads](/de/docs/operate/conversations)

---

# Auf Ihrer Website einbinden

Source: /de/docs/tutorials/website.md

<TutorialEpisode
  episode="ep02"
  chapters="[
[0, &#x22;Einführung&#x22;],
[13, &#x22;Auf Ihrer Website installieren&#x22;],
[25, &#x22;Zulässige Website-Adressen&#x22;],
[48, &#x22;Code für Ihre Plattform kopieren&#x22;],
[81, &#x22;Das Widget auf Ihrer Website&#x22;],
[92, &#x22;Meine Website prüfen&#x22;],
[108, &#x22;Stilvorlagen und Farben&#x22;],
[128, &#x22;Schwebende Blase&#x22;],
[141, &#x22;Agent-Link und QR-Code&#x22;],
[163, &#x22;Widget ausblenden&#x22;],
[175, &#x22;Zusammenfassung&#x22;]
]"
/>

## Weiterführende Anleitungen [#weiterführende-anleitungen]

* [Übersicht zur Einbindung](/de/docs/embed/overview)
* [Darstellung](/de/docs/build/appearance)
* [Agent-Link](/de/docs/publish/hosted-sites)

---

# WhatsApp

Source: /de/docs/tutorials/whatsapp.md

<TutorialEpisode
  episode="ep04"
  chapters="[
[0, &#x22;Einführung&#x22;],
[15, &#x22;Was Sie benötigen&#x22;],
[31, &#x22;Nummer einrichten und mit Meta verbinden&#x22;],
[49, &#x22;Meta-Registrierung&#x22;],
[65, &#x22;Ihre Nummer auswählen&#x22;],
[78, &#x22;Kanaltest und KI-Antworten aktivieren&#x22;],
[106, &#x22;Ihr Agent auf WhatsApp&#x22;],
[124, &#x22;Das 24-Stunden-Fenster&#x22;],
[140, &#x22;WhatsApp-Chats unter Unterhaltungen&#x22;],
[153, &#x22;Wir richten es gern für Sie ein&#x22;],
[165, &#x22;Zusammenfassung&#x22;]
]"
/>

## Weiterführende Anleitungen [#weiterführende-anleitungen]

* [WhatsApp](/de/docs/connectors/whatsapp)
* [Unterhaltungen und Leads](/de/docs/operate/conversations)