Anruf-Lebenszyklus

Dieses Dokument beschreibt den vollständigen Lebenszyklus eines einzelnen KI-gestützten Telefonanrufs über die Audact-Plattform, von der Compliance-Prüfung vor dem Wählen bis zur Verifikation nach dem Anruf.

Phase 1: Vor dem Wählen (Policy Engine)

POST /v1/evaluate — Statuslose Compliance-Prüfung. Es werden keine Nachweis-Ereignisse geschrieben.

Die Policy Engine bewertet länderspezifische Regeln (Einwilligungsanforderungen, DNC-Register, Ruhezeiten) und gibt ALLOW oder BLOCK mit Gründen zurück. Bei BLOCK darf der Anruf nicht fortgesetzt werden.

GET /v1/policies/{country} — Aktives Regelwerk für ein Land abrufen (ISO 3166-1 alpha-2). Gibt das vollständige Regelschema zurück, einschließlich Ruhezeiten, Einwilligungsanforderungen und DNC-Register-Konfiguration.

Phase 2: Anrufbeginn

POST /v1/events mit event_type: CALL_START

Die Plattform sendet ein CALL_START-Ereignis. Der Evidence Layer erstellt automatisch eine calls-Zeile mit status = 'active', sofern noch keine vorhanden ist.

Phase 3: Erste Gesprächsrunde — Offenlegung erforderlich

POST /v1/validate (Runde 1)

In der ersten Gesprächsrunde wird das Offenlegungs-Gate ausgelöst, da call_state.disclosure_delivered == false. Der Validator gibt verdict: BLOCK zurück, mit dem Originaltext im Feld content. Die verbleibenden 6 Prüfungen werden nicht ausgeführt (Kurzschlussauswertung). Die Plattform muss ihren eigenen Offenlegungstext sprechen und disclosure_delivered = true im Anrufstatus für nachfolgende Gesprächsrunden setzen.

Phase 4: Gespräch — Validator aktiv

POST /v1/validate (Runde N, wiederholt pro Runde)

Der Validator führt 7 Prüfungen innerhalb einer festen Frist von 40 ms durch:

Urteile

Es gibt nur drei Urteile: ALLOW, BLOCK, MODIFY. Es gibt kein ESCALATE-Urteil.

• ALLOW — Originaltext wird in content zurückgegeben. Quittung: input_hash == output_hash.
• MODIFY — Modifizierter Text wird in content zurückgegeben. Quittung: input_hash (Original), output_hash (modifiziert).
• BLOCK — Originaltext in content; der Aufrufer ersetzt ihn durch seine eigene Fallback-Antwort. Quittung: input_hash (Original), output_hash (Fallback).

Antwort-Schema (ACVFResponse)

{
  "call_id": "uuid",
  "turn": 1,
  "verdict": "ALLOW | BLOCK | MODIFY",
  "content": "validated or modified text",
  "fail_open": false,
  "receipt": { "..." },
  "compliance_score": { "..." },
  "checks": [
    {
      "check_id": "pii_scan",
      "verdict": "ALLOW",
      "reason": "",
      "modified_content": "",
      "duration_ms": 2
    }
  ]
}

Der LLM-Proxy schreibt nach jeder Validierung ein VALIDATION_RESULT-Ereignis in den Evidence Layer (über POST /v1/events). Allen Antworten, die nicht auf Fail-Open basieren, wird eine Compliance-Quittung beigefügt.

Fail-Open (Validator-Timeout > 40 ms)

Überschreitet der Validator die 40-ms-Frist: verdict: ALLOW, fail_open: true, content: Originaltext, receipt: nil. Unmittelbar wird ein FAIL_OPEN-Ereignis für die Alarmierung geschrieben und dauerhaft asynchron gespeichert. Das Feld fail_open_meta enthält reason, deadline_ms, elapsed_ms und checks_completed.

PII-Erkennung (Prüfung 4)

Erkennt BSN (niederländische 9-stellige Nummer), IBAN und Kreditkartennummern (Luhn-Algorithmus). Gibt MODIFY oder BLOCK gemäß Mandanten-Konfiguration zurück.

Phase 4b: Audiobasierte Validierung (alternativer Pfad)

POST /v1/validate-audio — Audio-Validator

Für Sprachgespräche, bei denen die Plattform rohe Audiodaten statt vorab transkribiertem Text sendet. Der Audio-Validator:

1. Nimmt base64-kodiertes PCM-Audio entgegen (16-Bit LE, 16 kHz, Mono).
2. Führt ASR-Transkription durch (Deepgram, Whisper oder AssemblyAI — pro Mandant über BYOK konfigurierbar).
3. Segmentiert das Audio nach einer von zwei Strategien:
   • asr_first (Standard) — Streaming-ASR steuert die Satzsegmentierung.
   • prosodic_first — VAD-Stille-Erkennung erzeugt Segmente, dann transkribiert Batch-ASR jedes Segment.
4. Wendet dieselbe 7-Prüfungs-Pipeline auf den Transkriptionstext an (delegiert an den Validator).
5. Bestimmt das Audio-Routing: forward (ALLOW), substitute (MODIFY — ersetzt durch vorgenerierten TTS) oder block.
6. Gibt Ergebnisse pro Segment zurück mit doppelten Hashes (audio_hash + text_hash) und einer Compliance-Quittung mit HMAC-Integritätskennzeichen.

Parallele ASR

Wenn parallel_asr: true, sendet der Audio-Validator das Audio gleichzeitig an mehrere ASR-Modelle, speichert alle Ergebnisse in der Nachweis-Kette und wählt die Transkription mit der höchsten Konfidenz aus.

Anfrage-Schema

{
  "call_id": "uuid",
  "audio_data": "base64-encoded PCM bytes",
  "audio_format": "pcm_s16le_16000",
  "turn_number": 1,
  "configuration_id": "uuid",
  "call_context": {
    "language": "nl",
    "disclosure_delivered": true
  },
  "segmentation_method": "asr_first",
  "parallel_asr": false
}

Antwort-Schema

{
  "verdict": "ALLOW",
  "segments": [
    {
      "segment_index": 0,
      "audio_hash": "sha256hex",
      "transcribed_text": "ASR output",
      "text_hash": "sha256hex",
      "verdict": "ALLOW",
      "check_results": [...],
      "segmentation_method": "asr_first",
      "asr_confidence": 0.97,
      "asr_model_id": "deepgram:nova-2",
      "action": "forward"
    }
  ],
  "fail_open": false,
  "evidence_event_id": "uuid",
  "evidence_hash": "sha256hex",
  "receipt": {
    "input_hash": "sha256hex (original audio)",
    "output_hash": "sha256hex (forwarded/substituted audio)",
    "text_hash": "sha256hex (transcription)",
    "verdict": "ALLOW",
    "signature": "HMAC-SHA256"
  }
}

Phase 5: Ereignisse während des Anrufs

POST /v1/events — Der Evidence Layer akzeptiert beliebige event_type-Zeichenketten. Häufige Typen:

Alle Ereignisse werden unabhängig vom Typ an die kryptografische Hash-Kette angehängt. Benutzerdefinierte Ereignistypen (z. B. tool_call, consent_granted) können frei gesendet werden.

Phase 5b: LLM-Proxy

POST /v1/proxy/openai — Nicht-Streaming-komplianter LLM-Proxy. POST /v1/proxy/openai/stream — Streaming-komplianter LLM-Proxy.

Der LLM-Proxy sitzt zwischen der Plattform und dem vorgelagerten LLM-Anbieter. Für jede Anfrage:

1. Validiert die Anfrage über den Validator.
2. Leitet zugelassene Anfragen an das vorgelagerte LLM weiter (OpenAI-kompatible API).
3. Validiert die LLM-Antwort, bevor sie an die Plattform zurückgegeben wird.
4. Schreibt Nachweis-Ereignisse für die Validierung von Anfrage und Antwort.
5. Unterstützt die Generierung mehrerer Kandidaten: sendet dasselbe Prompt gleichzeitig an N Endpunkte, validiert alle Kandidaten und gibt die beste konforme Antwort zurück.

Phase 6: Lieferattest

POST /v1/delivery-confirmation — Lieferbestätigung einreichen.

Nachdem die validierte Antwort dem menschlichen Gesprächspartner zugestellt wurde, sendet die Plattform (oder Audacts eigenes Audio-Monitor) eine Lieferbestätigung. Dadurch entsteht eine manipulationserkennbare Verbindung zwischen dem validierten Inhalt und dem tatsächlich Zugestellten — jede Abweichung ist durch Neuberechnung gegen das gespeicherte Commitment erkennbar:

• DC-1 (webhook): Die Plattform sendet einen Webhook mit dem Hash des zugestellten Inhalts.
• DC-2 (api_query): Audact fragt die Plattform-API nach dem Lieferstatus ab.
• DC-3 (tts_completion): Die TTS-Engine signalisiert den Abschluss mit dem Inhalts-Hash.
• DC-4 (audio_monitoring): Audacts eigenes ASR erfasst das Gesprochene (unabhängig von der auditierten Plattform).

Jede Bestätigung enthält:

• linking_hash = SHA-256(validation_event_hash || confirmation_hash) — manipulationserkennbarer Nachweis-Ketten-Link.
• confirmation_grade: independent (DC-4), platform_sourced (DC-1/2/3) oder unconfirmed (Timeout).
• content_match: ob der zugestellte Inhalt mit dem validierten Inhalt übereinstimmt.

Lieferbestätigungen, die nicht innerhalb von 30 Sekunden eingehen, werden automatisch als unconfirmed markiert.

GET /v1/calls/{call_id}/delivery — Lieferattest-Status pro Gesprächsrunde für einen Anruf abrufen.

Phase 7: Anrufbeendigung

Die Plattform sendet ein abschließendes Ereignis über POST /v1/events:

• CALL_END — Setzt calls.status = 'completed' und calls.ended_at atomisch in derselben Transaktion wie das Nachweis-Ereignis.
• CALL_FAILED — Setzt calls.status = 'failed' und calls.ended_at atomisch in derselben Transaktion wie das Nachweis-Ereignis.

Wichtig: Es gibt KEINEN Hintergrund-Sweep-Job. Anrufe, die nie ein CALL_END- oder CALL_FAILED-Ereignis erhalten, verbleiben dauerhaft im Status status = 'active'. Die Plattform ist dafür verantwortlich, abschließende Ereignisse zu senden.

Phase 7b: C2PA-Inhaltsberechtigungsnachweise

POST /v1/calls/{call_id}/c2pa — C2PA-Manifest für einen abgeschlossenen Anruf generieren.

Nach Abschluss eines Anrufs können Mandanten einen C2PA-kompatiblen Inhaltsberechtigungsnachweis anfordern. Das Manifest enthält:

• Claim: Anruf-Metadaten, Zusammenfassung der Nachweis-Kette, Config-Seal-Hash.
• Assertions: Hashverweise pro Ereignis (keine Rohdaten der Ereignisse), Kettenintegritätsbeweis.
• Signature: HMAC-SHA256 über kanonisches JSON (RFC 8785) aus Claim + Assertions mit dem KMS-verwalteten Schlüssel des Mandanten.
• Merkle-Nachweis-Referenz: Falls die Nachweise des Anrufs in einer mandantenübergreifenden Aggregation enthalten waren, verweist das Manifest auf den Branch-Beweis und die Merkle-Wurzel.

Der Endpunkt prüft die Anruf-Eigentümerschaft vor der Manifest-Generierung. HMAC-Schlüsselmaterial wird niemals in der Antwort zurückgegeben.

Phase 7c: Mandantenübergreifende Aggregation

Der Aggregator-Dienst sammelt regelmäßig Nachweis-Hashes über alle Mandanten hinweg und erstellt einen Merkle-Baum für Manipulationserkennung und Auditierbarkeit durch Dritte.

Aggregations-Pipeline (automatisch oder manuell)

POST /v1/admin/aggregate — Nur-Admin-Endpunkt zum manuellen Auslösen der Aggregation für ein Zeitfenster. Erfordert die Rolle owner. Wenn kein Fenster angegeben wird, wird das vorherige abgeschlossene Intervall aggregiert.

Die Pipeline:

1. Sammelt aggregierte Hashes pro Mandant (SHA-256 aller Nachweis-Hashes im Fenster).
2. Erstellt einen ausgeglichenen binären Merkle-Baum mit mindestens 16 Blättern als Auffüllung.
3. Fordert einen RFC-3161-Zeitstempel-Token von einem TSA für die Merkle-Wurzel an.
4. Hängt die Wurzel an die Meta-Kette (Kette der Ketten) an.

Beweis-Abruf (authentifiziert)

Branch-Beweise werden auf Anfrage aus gespeicherten Metadaten rekonstruiert. Beweisschritte enthalten nur opake Geschwister-Hashes und Position — es werden keine Mandanten-Kennungen preisgegeben.

Öffentliche Verifikation (ohne Authentifizierung)

Die Meta-Kette ermöglicht es jedem, die aggregationsübergreifende Integrität zu prüfen:

• chain_hash = SHA-256(sequence || merkle_root || previous_hash)
• Genesis-Eintrag: previous_hash = 64 Nullen
• Die Kette erzwingt Integrität bei jedem Anhängen

Der Verify-Inclusion-Endpunkt ist vollständig offline — kein Datenbankzugriff, keine Authentifizierung. Das branch_proof-Objekt aus GET /v1/proofs/{window_id} kann direkt eingespeist werden.

Phase 8: Verifikation nach dem Anruf

Transkript-Abgleich

POST /v1/transcript-reconciliation — Transkript-Abgleich nach dem Anruf.

Nach Abschluss eines Anrufs kann die Plattform das vollständige Nachtranskript zum Abgleich mit der Nachweis-Kette einreichen. Der Reconciler vergleicht jedes Transkript-Segment mit validierten Ausgabe-Ereignissen:

• MATCHED: Der Hash des Transkript-Segments stimmt mit dem validierten Ausgabe-Hash überein — bestätigte Zustellung.
• MISMATCHED: Der Hash des Transkript-Segments weicht ab — ein transcript_mismatch-Nachweis-Ereignis wird generiert.
• UNVALIDATED: Das Transkript-Segment hat kein entsprechendes Validierungs-Ereignis — ein unvalidated_content-Ereignis wird generiert (erkennt Plattform-Einfügungen, die Audact umgangen haben).

Audio-Abgleich

POST /v1/audio-reconciliation — Audio-Abgleich nach dem Anruf.

Kombiniert ASR-Transkription und Transkript-Abgleich in einem einzigen synchronen Endpunkt. Der Aufrufer sendet die vollständige Anrufaufzeichnung; der Dienst transkribiert sie per ASR und gleicht die Transkription dann mit der Nachweis-Kette ab. Dies ist der bevorzugte Endpunkt, wenn die Plattform rohe Audiodaten, aber kein Texttranskript hat.

Dies ist ein synchroner Endpunkt — der Aufrufer blockiert, bis Transkription und Abgleich abgeschlossen sind. Bei langen Aufzeichnungen kann dies mehrere Sekunden dauern.

Anfrage-Schema

{
  "call_id": "uuid",
  "audio_data": "base64-encoded audio bytes",
  "audio_format": "pcm_s16le_16000 | wav | mp3",
  "language": "nl",
  "asr_provider": "deepgram"
}

• audio_data: Standardmäßig base64-kodierte Audiodaten. Das Body-Limit beträgt 64 MiB (~34 Min. PCM bei 16 kHz Mono).
• audio_format: Eines von pcm_s16le_16000 (rohes PCM 16-Bit LE, 16 kHz, Mono), wav oder mp3.
• language: BCP-47-Tag (optional, Standard nl).
• asr_provider: Überschreibt den Standard-ASR-Anbieter (optional).
• Kein tenant_id-Feld — die Mandanten-Identität stammt aus dem Authentifizierungskontext.

Antwort-Schema

{
  "call_id": "uuid",
  "asr_model_id": "mock:deterministic-v1",
  "asr_confidence": 0.95,
  "total_segments": 5,
  "matched_segments": 4,
  "mismatched_segments": 1,
  "unvalidated_segments": 0,
  "segment_results": [
    {
      "sequence_number": 1,
      "status": "matched",
      "similarity_score": 1.0,
      "validated_hash": "sha256hex",
      "transcript_hash": "sha256hex"
    }
  ]
}

Ablauf

1. Authentifizierung über API-Schlüssel.
2. Anruf-Eigentümerschaft prüfen.
3. Base64-Audiodaten dekodieren.
4. Vollständiges Audio per ASR transkribieren (derselbe ASR-Client wie /v1/validate-audio).
5. Abgleich-Segmente aus der ASR-Ausgabe erstellen.
6. Mit der Nachweis-Kette abgleichen (derselbe Reconciler wie /v1/transcript-reconciliation).
7. Segment-für-Segment-Ergebnisse zurückgeben.

Mandantenverwaltung

Diese Endpunkte verwalten Mandanten, API-Schlüssel und Konfigurationen. Sie sind nicht Teil des Anruf-Ablaufs, werden aber für die Einrichtung benötigt.

Mandanten

API-Schlüssel

Konfigurationen

Konfigurationen umfassen:

• Richtlinienregeln (Blocklist-Muster, PII-Erkennung, Preisbänder, Eskalations-Schlüsselwörter, Einwilligungs-Gates)
• Multi-Kandidaten-LLM-Endpunkte (BYOK: URL + API-Schlüssel pro Anbieter, sicher gespeichert)
• Ausgabe-Beschränkungen (Antwortlängenlimits mit Erhalt compliance-kritischer Inhalte)
• ASR-Anbieter-Schlüssel (BYOK: Deepgram, Whisper, AssemblyAI — API-Schlüssel sicher gespeichert)

Authentifizierung

Nutzung

Vollständige Endpunkt-Übersicht

Nachweis-Eigenschaften

Alle Nachweis-Ereignisse sind:

• Nur anhängbar — Keine Aktualisierungen, keine Löschungen
• Kryptografisch verkettet — SHA-256 über pipe-getrennte Vorbilder: event_id|call_id|sequence|event_type|timestamp|canonicalJSON(data)|previous_hash
• Server-gestempelt — time.Now().UTC(), niemals vom Client
• Schreibgeschützt — Gleichzeitige Schreibvorgänge auf demselben call_id werden serialisiert
• Konfigurations-gebunden — Jedes Ereignis enthält config_seal_hash (SHA-256 des kanonischen RFC-8785-JSON der Mandanten-Konfiguration)

Der Anruf-Status-Cache ist abgeleitet aus der Nachweis-Kette, nicht unabhängig. Bei Cache-Miss: Ereignisse aus dem Speicher replizieren, Status rekonstruieren, Cache aktualisieren.

Sicherheitsmodell

• Mandanten-Isolation: Jede Anfrage wird per API-Schlüssel authentifiziert → Mandanten-Identität aus dem Authentifizierungskontext extrahiert. Kein tenant_id im Anfrage-Body.
• Anruf-Eigentümerschaft: Die call_id wird vor der Verarbeitung verifiziert, dass sie zum authentifizierten Mandanten gehört.
• Nachweis-Integrität: Ketten-Spalten sind nur anhängbar; jede Manipulation ist durch Neuberechnung gegen gespeicherte Commitments erkennbar.
• Geheimnisverwaltung: LLM- und ASR-API-Schlüssel werden sicher gespeichert; Schlüssel werden in GET-Antworten zu has_key: true geschwärzt.
• Kein PII in Logs: Transkripte, Telefonnummern und Audioinhalte werden niemals protokolliert. In strukturierten Logs nur Hashes und Metadaten.