Ereignisse

AíPowerDesk sendet Ereignisse („FpEvents") an andere Fluxpunkt-Module und — über EventBridge — an Drittsysteme. Zwei Anwendungsfälle stehen dahinter: Die frei konfigurierbaren Aktionsschaltflächen der Rufliste übergeben ein Gespräch samt Zusammenfassung und Transkript per Klick an Branchensoftware, Ticket- oder CRM-Systeme; die Zusammenfassungs-Ereignisse melden jede fertiggestellte oder nachträglich korrigierte KI-Gesprächszusammenfassung und ermöglichen so eine automatische Gesprächsdokumentation in nachgelagerten Systemen — ohne Polling und ohne Datenbankzugriff.

Grundlagen

Typ: FpEvents — der modulübergreifende Ereignismechanismus der Fluxpunkt-Module auf dem anlageninternen Ereignisbus. Es handelt sich um keine Netzwerkschnittstelle: Ereignisse sind nur innerhalb der Anlage erreichbar; nach außen gelangen sie über EventBridge.
Identifikator: der Ereignisname — ActionButtonEvent, TranscriptionSummaryReadyEvent oder TranscriptionSummaryChangedEvent.
Nutzlast: ein JSON-Objekt. Felder ohne Wert (null) entfallen in der Nutzlast; unbekannte Felder werden beim Empfang ignoriert.
Konsum: EventBridge abonniert Ereignisse per Konfiguration und reicht sie als Webhook, E-Mail, Syslog-Meldung oder Datenbankeintrag weiter. Eigene STARFACE-Module verwenden die Modulfunktionen FpEvent abonnieren / FpEvent abbestellen (FpRegisterEvents / FpUnregisterEvents) — Download und Anleitung im Artikel Schnittstellen & APIs.
Richtung: AíPowerDesk sendet ausschließlich; Steuerereignisse empfängt das Modul nicht.
Voraussetzung: eine aktive, lizenzierte Modulkonfiguration.

ActionButtonEvent

Wird veröffentlicht, wenn ein Benutzer eine Aktionsschaltfläche drückt („Aktionsschaltfläche gedrückt"). Administratoren definieren bis zu 255 Schaltflächen (Indizes 0–254) mit Beschriftung, Icon und Tooltip im Modul-Backend; sie erscheinen in der Ruflisten-Seitenleiste und in den Schnellaktionsleisten der Rufliste. Das Ereignis transportiert den vollständigen Kontext des Ruflisteneintrags, auf dem der Klick erfolgte — Gesprächsmetadaten, KI-Zusammenfassung und Transkript.

Auslösezeitpunkt: unmittelbar beim Klick, nachdem das Modul-Backend den angemeldeten STARFACE-Benutzer und die Modullizenz geprüft hat. Für als privat markierte Gespräche wird der Klick abgewiesen, wenn der Benutzer nicht auf die Gesprächsinhalte zugreifen darf — in diesem Fall wird kein Ereignis veröffentlicht, denn die Nutzlast trägt Transkript und Zusammenfassung aus dem System hinaus.

Feld	Typ	Bedeutung
`moduleId`	String	Kennung des sendenden Moduls; bei AíPowerDesk konstant `AiPowerDesk`. Das Ereignis ist modulübergreifend definiert — filtern Sie auf dieses Feld, wenn Sie nur AíPowerDesk-Klicks verarbeiten wollen.
`moduleName`	String	Anzeigename des sendenden Moduls; derzeit ebenfalls `AiPowerDesk`.
`buttonUuid`	String	Stabile UUID (v4) der Schaltfläche, einmalig bei ihrer Anlage erzeugt und danach unveränderlich. Empfohlener Schlüssel für Regeln in EventBridge: Er übersteht Umbenennungen und Umsortierungen. Die Administrationsoberfläche zeigt je Schaltfläche die Kurzform der UUID und bietet das Kopieren des vollen Werts an.
`buttonIndex`	Integer	0-basierte Position der Schaltfläche (0–254). Ändert sich beim Umsortieren — nicht als Schlüssel geeignet.
`buttonName`	String	Beschriftung der Schaltfläche zum Zeitpunkt des Klicks.
`accountId`	Integer	STARFACE-Account-ID des klickenden Benutzers.
`timestamp`	Integer	Zeitpunkt der Veröffentlichung (Epoch-Millisekunden).
`payload`	Objekt	AíPowerDesk-spezifische Nutzlast — der vollständige Kontext des Ruflisteneintrags (siehe unten).

Die Nutzlast `payload`

Die Felder der Nutzlast sind der verbindliche Vertrag für moduleId = AiPowerDesk. Die Anreicherung erfolgt best-effort: Existiert (noch) keine Zusammenfassung oder Transkription oder schlägt ein Nachschlagen fehl, entfallen die betreffenden Felder — das Ereignis wird dennoch gesendet.

Feld	Typ	Bedeutung
`callId`	Integer	STARFACE-Call-ID des Gesprächs.
`callListEntryId`	Integer	ID des Ruflisteneintrags.
`callerName`	String	Name des Anrufers.
`callerNumber`	String	Rufnummer des Anrufers.
`calleeName`	String	Name des Angerufenen.
`calleeNumber`	String	Rufnummer des Angerufenen.
`startTime`	Integer	Gesprächsbeginn (Epoch-Millisekunden).
`endTime`	Integer	Gesprächsende (Epoch-Millisekunden, aus dem Ergebniszeitpunkt des Ruflisteneintrags).
`resultTime`	Integer	Zeitpunkt des Gesprächsergebnisses (Epoch-Millisekunden).
`incoming`	Boolean	`true` = eingehendes Gespräch.
`voicemail`	Boolean	`true` = Voicemail-Eintrag.
`comment`	String	Aktueller Kommentar des Ruflisteneintrags.
`commentAuthor`	String	Autor des Kommentars.
`calledBack`	Boolean	Ob der Eintrag als „zurückgerufen" markiert ist.
`summaryBrief`	String	Kurzzusammenfassung (Markdown). Nur vorhanden, wenn eine Zusammenfassung existiert — das gilt für alle `summary…`-Felder.
`summaryDetailed`	String	Detailzusammenfassung (Markdown).
`summaryInvoiceText`	String	Als Rechnungs-/Belegtext geeignete Zusammenfassung.
`summaryNoteWorthy`	String	Auffälligkeiten des Gesprächs.
`summaryReason`	String	Wahrscheinlicher Anrufgrund.
`summaryCategories`	String	Kommaseparierte Kategorien (z. B. „Vertrieb, Support").
`summaryToneMood`	String	Tonalität und Stimmung des Gesprächs.
`summaryEntities`	String	Kommaseparierte Liste genannter Produkte, Firmen oder Dritter.
`summaryConfidenceDescription`	String	Erläuterung der Konfidenzeinschätzung.
`summaryConfidenceValue`	Zahl	Konfidenz von Transkription und Zusammenfassung (0–100).
`summaryJson`	String (JSON)	Die vollständige Zusammenfassung als JSON-Text — Struktur siehe `TranscriptionSummaryReadyEvent`.
`transcriptionJson`	String (JSON)	Das vollständige Transkript als JSON-Text (Absätze, Sprecher, Zeitpositionen; siehe folgende Tabelle). Nur vorhanden, wenn eine Transkription existiert.
`transcriptionText`	String	Das Transkript als Klartext, Absätze durch Zeilenumbrüche getrennt.

Der JSON-Text in transcriptionJson enthält folgende Struktur:

Feld	Typ	Bedeutung
`time`	Integer	Zeitstempel der Transkription (Epoch-Millisekunden).
`confidence`	Zahl	Gesamtkonfidenz der Transkription.
`paragraphs`	Array	Absätze des Transkripts, je Eintrag: `text` (String), `channel` (Integer), `speaker` (Integer — Sprecherindex innerhalb des Kanals), `start`/`end` (Zahl — Zeitversatz innerhalb der Aufzeichnung), `confidence` (Zahl).
`source`	Objekt	Herkunft der Transkription: `provider` (String), `model` (String), `speakerLayout` (String — `channel_per_side`, `channel_per_side_heuristic`, `diarized` oder `single_speaker`; beschreibt, ob `channel` verlässlich die Gesprächsseite kennzeichnet: 0 = Anruferseite, 1 = angerufene Seite). Kann bei älteren Transkriptionen fehlen.

Beispiel: ActionButtonEvent
{
  "moduleId": "AiPowerDesk",
  "moduleName": "AiPowerDesk",
  "buttonUuid": "7c8f3a2b-9d4e-4f6c-a1b8-2e9f0d5b7a31",
  "buttonIndex": 0,
  "buttonName": "Ticket erstellen",
  "accountId": 42,
  "timestamp": 1785829000000,
  "payload": {
    "callId": 123456,
    "callListEntryId": 654321,
    "callerName": "Erika Musterfrau",
    "callerNumber": "+4972112345678",
    "calleeName": "Vertrieb",
    "calleeNumber": "+497219876543",
    "startTime": 1785828600000,
    "endTime": 1785828840000,
    "resultTime": 1785828840000,
    "incoming": true,
    "voicemail": false,
    "comment": "Telefonische Beratung zu Produkt X\nAngebot bis Freitag zugesagt.",
    "commentAuthor": "System",
    "calledBack": false,
    "summaryBrief": "**Erika Musterfrau** bittet um ein **Angebot** für Produkt X. …",
    "summaryDetailed": "Frau Musterfrau erkundigt sich nach … ",
    "summaryInvoiceText": "Telefonische Beratung zu Produkt X",
    "summaryNoteWorthy": "",
    "summaryReason": "Angebotsanfrage",
    "summaryCategories": "Vertrieb, Pre-Sales",
    "summaryToneMood": "freundlich, sachlich",
    "summaryEntities": "Beispiel GmbH, Produkt X",
    "summaryConfidenceDescription": "Transkript weitgehend eindeutig; Namen durch Anruferdaten gestützt.",
    "summaryConfidenceValue": 93.0,
    "summaryJson": "{\"brief\":\"**Erika Musterfrau** bittet um ein **Angebot** für Produkt X. …\", … }",
    "transcriptionJson": "{\"time\":1785828900000,\"confidence\":0.95,\"paragraphs\":[{\"text\":\"Guten Tag, mein Name ist Musterfrau …\",\"channel\":0,\"speaker\":0,\"start\":0.4,\"end\":6.8,\"confidence\":0.97}, … ],\"source\":{\"provider\":\"deepgram\",\"model\":\"nova-2\",\"speakerLayout\":\"channel_per_side\"}}",
    "transcriptionText": "Guten Tag, mein Name ist Musterfrau von der Beispiel GmbH.\nGuten Tag, was kann ich für Sie tun?"
  }
}

Anwendungsbeispiel

Ein Systemhaus legt eine Schaltfläche „Ticket erstellen" an. EventBridge matcht auf die buttonUuid und ruft per Webhook die Ticketsystem-API auf — mit payload.summaryInvoiceText als Ticketbetreff und payload.transcriptionText als Beschreibung. Der Agent dokumentiert ein Gespräch mit einem einzigen Klick.

TranscriptionSummaryReadyEvent

Wird veröffentlicht, sobald eine KI-Gesprächszusammenfassung erstellt und gespeichert wurde („Zusammenfassung fertig") — für Gespräche wie für Voicemails. Nachträgliche manuelle Korrekturen meldet separat das TranscriptionSummaryChangedEvent.

Auslösezeitpunkt: nach jeder Zusammenfassungserstellung, unabhängig vom Auslöser — automatisch durch den Hintergrundprozess des Moduls (prüft etwa alle 30 Sekunden auf Transkriptionen ohne Zusammenfassung), manuell aus der Oberfläche oder nach der automatischen Neuerzeugung im Zuge einer Feldkorrektur mit der Option „auf alle Zusammenfassungen anwenden". Voraussetzung ist eine vorhandene Transkription (aus der Live-Transkription oder Call Recording); für Voicemails erstellt das Modul die Transkription bei Bedarf selbst. Leere Zusammenfassungen — etwa bei unverwertbarer KI-Antwort oder inhaltsleerer Transkription — werden nicht gemeldet.

Die Felder ab callerNumber wiederholen Anrufkontext, der sich auch über die callId auflösen ließe. Sie sind enthalten, damit Konsumenten außerhalb der STARFACE — etwa eine EventBridge-Regel, die direkt in ein Drittsystem schreibt — allein mit dem Ereignis arbeiten können. Aufgenommen sind nur Werte, die für das ganze Gespräch stabil sind.

Feld	Typ	Bedeutung
`callId`	Integer	STARFACE-Call-ID des Gesprächs.
`voicemail`	Boolean	`true` = Zusammenfassung einer Voicemail.
`timestamp`	Integer	Zeitpunkt der Veröffentlichung (Epoch-Millisekunden).
`summaryJson`	String (JSON)	Die vollständige Zusammenfassung als JSON-Text — Struktur siehe unten.
`callerNumber`	String	Rufnummer des Anrufers; leer, wenn unbekannt.
`calledNumber`	String	Gewählte Rufnummer; leer, wenn unbekannt.
`incoming`	Boolean	`true` = eingehendes Gespräch.
`startTime`	Integer	Gesprächsbeginn (Epoch-Millisekunden), `0` wenn unbekannt.
`endTime`	Integer	Gesprächsende (Epoch-Millisekunden), `0` wenn unbekannt.
`recordedAccountId`	Integer	STARFACE-Account des Gesprächsabschnitts, zu dem die Aufzeichnung gehört. Bewusst nicht `accountId` genannt: An einem Gespräch können durch Weiterleitungen mehrere Accounts beteiligt sein; eine Aufzeichnung beginnt jedoch auf einem Abschnitt — eine Weiterleitung erzeugt eine neue Aufzeichnung und damit ein eigenes Ereignis.

Beispiel: TranscriptionSummaryReadyEvent
{
  "callId": 123456,
  "voicemail": false,
  "timestamp": 1785828900000,
  "summaryJson": "{\"brief\":\"**Erika Musterfrau** bittet um ein **Angebot** für Produkt X. …\", … }",
  "callerNumber": "+4972112345678",
  "calledNumber": "+497219876543",
  "incoming": true,
  "startTime": 1785828600000,
  "endTime": 1785828840000,
  "recordedAccountId": 17
}

Struktur von `summaryJson`

summaryJson transportiert die vollständige Zusammenfassungsstruktur als JSON-Text (dieselbe Struktur wie das gleichnamige Feld der Aktionsschaltflächen-Nutzlast). Dekodiert:

Feld	Typ	Bedeutung
`brief`	String	Kurzzusammenfassung (rund 100 Wörter, Markdown; Kernpunkte fett).
`detailed`	String	Detailzusammenfassung (bis rund 400 Wörter, Markdown).
`noteworthy`	String	Auffälligkeiten (z. B. ungewöhnliche Anrufzeit); kann leer sein.
`keysPerSpeaker`	Array	Kernaussagen je Sprecher (siehe folgende Tabelle).
`categories`	String	Kommaseparierte Kategorien des Gesprächs (z. B. „Vertrieb, Support, Finanzen").
`reason`	String	Wahrscheinlicher Anrufgrund.
`invoiceText`	String	Als Rechnungs-/Belegtext geeignete Zusammenfassung.
`ticketRefs`	Array von String	Im Gespräch genannte Ticket-/Vorgangsnummern.
`contactRefs`	Array von String	Im Gespräch genannte E-Mail-Adressen und Rufnummern.
`entities`	String	Kommaseparierte Liste genannter Produkte, Dienstleistungen, Firmen oder Dritter.
`toneMood`	String	Tonalität, Stimmung und Gesprächsklima.
`confidenceValue`	Integer	Konfidenz von Transkription und Zusammenfassung (0–100).
`confidenceDescription`	String	Erläuterung der Konfidenzeinschätzung.

Jeder Eintrag in keysPerSpeaker beschreibt einen Gesprächsteilnehmer:

Feld	Typ	Bedeutung
`channel`	Integer	Kanal aus dem Transkript; bei kanalgetrennten Transkriptionen: `0` = Anruferseite, `1` = angerufene Seite.
`speakerId`	Integer	Sprecherindex innerhalb des Kanals (unterscheidet mehrere Personen derselben Seite).
`name`	String	Name des Sprechers, sofern bekannt — sonst die Rolle (Anrufer/Angerufener).
`side`	String	`caller` oder `callee`.
`actions`	Objekt	Kernaussagen bzw. nächste Schritte des Sprechers als Schlüssel; Wert ist je Aussage ein Array von Tags: `important`, `task`, `done`, `agreements`, `todo`.

summaryJson (dekodiert)
{
  "brief": "**Erika Musterfrau** bittet um ein **Angebot** für Produkt X. **Rückmeldung bis Freitag** vereinbart.",
  "detailed": "Frau Musterfrau erkundigt sich nach den Konditionen für Produkt X. …",
  "noteworthy": "",
  "keysPerSpeaker": [
    {
      "channel": 0,
      "speakerId": 0,
      "name": "Erika Musterfrau",
      "side": "caller",
      "actions": { "Erwartet Angebot für Produkt X": ["important"] }
    },
    {
      "channel": 1,
      "speakerId": 0,
      "name": "Max Mustermann",
      "side": "callee",
      "actions": { "Angebot bis Freitag erstellen": ["todo"] }
    }
  ],
  "categories": "Vertrieb, Pre-Sales",
  "reason": "Angebotsanfrage",
  "invoiceText": "Telefonische Beratung zu Produkt X",
  "ticketRefs": [],
  "contactRefs": ["erika.musterfrau@beispiel.de", "+4972112345678"],
  "entities": "Beispiel GmbH, Produkt X",
  "toneMood": "freundlich, sachlich",
  "confidenceValue": 93,
  "confidenceDescription": "Transkript weitgehend eindeutig; Namen durch Anruferdaten gestützt."
}

TranscriptionSummaryChangedEvent

Wird veröffentlicht, wenn ein Benutzer eine bestehende Zusammenfassung nachträglich ändert — etwa falsch erkannte Namen oder Formulierungen über die Inline-Bearbeitung korrigiert. Das Ereignis nennt das geänderte Feld mit Vorher-/Nachher-Wert, sodass Konsumenten die Korrektur in bereits übertragene Datensätze nachziehen oder auditieren können. Es trägt denselben Anrufkontext wie das TranscriptionSummaryReadyEvent, damit ein Drittsystem den zugehörigen Datensatz ohne Rückfrage an die STARFACE wiederfindet.

Auslösezeitpunkt: nach jeder gespeicherten Feldänderung durch einen Benutzer. Wählt der Benutzer dabei die Option, die Korrektur auf alle Zusammenfassungsfelder zu übertragen, folgt zusätzlich ein neues TranscriptionSummaryReadyEvent mit der neu erzeugten Gesamtstruktur.

Feld	Typ	Bedeutung
`callId`	Integer	STARFACE-Call-ID des Gesprächs.
`voicemail`	Boolean	`true` = Zusammenfassung einer Voicemail.
`timestamp`	Integer	Zeitpunkt der Veröffentlichung (Epoch-Millisekunden).
`changedField`	String	Name des geänderten Felds innerhalb der Zusammenfassungsstruktur: `brief`, `detailed`, `invoiceText`, `reason`, `categories` oder `entities`.
`before`	String	Wert des Felds vor der Änderung.
`after`	String	Wert des Felds nach der Änderung.
`changedByAccountId`	Integer	STARFACE-Account-ID des Benutzers, der die Änderung vorgenommen hat.
`callerNumber`	String	Rufnummer des Anrufers; leer, wenn unbekannt.
`calledNumber`	String	Gewählte Rufnummer; leer, wenn unbekannt.
`incoming`	Boolean	`true` = eingehendes Gespräch.
`startTime`	Integer	Gesprächsbeginn (Epoch-Millisekunden), `0` wenn unbekannt.
`endTime`	Integer	Gesprächsende (Epoch-Millisekunden), `0` wenn unbekannt.
`recordedAccountId`	Integer	STARFACE-Account des aufgezeichneten Gesprächsabschnitts (siehe `TranscriptionSummaryReadyEvent`).

Beispiel: TranscriptionSummaryChangedEvent
{
  "callId": 123456,
  "voicemail": false,
  "timestamp": 1785832500000,
  "changedField": "invoiceText",
  "before": "Telefonische Beratung zu Produkt X",
  "after": "Telefonische Beratung zu Produkt X, Angebot zugesagt",
  "changedByAccountId": 42,
  "callerNumber": "+4972112345678",
  "calledNumber": "+497219876543",
  "incoming": true,
  "startTime": 1785828600000,
  "endTime": 1785828840000,
  "recordedAccountId": 17
}

Versionierung & Kompatibilität

Ereignisnamen und Feldnamen sind stabile Verträge; Erweiterungen erfolgen additiv (neue Ereignisse, neue optionale Felder). Verarbeiten Sie Nutzlasten daher tolerant gegenüber zusätzlichen Feldern.

ActionButtonEvent: verfügbar seit Modulversion 26.5.21.
TranscriptionSummaryReadyEvent und TranscriptionSummaryChangedEvent: verfügbar seit Modulversion 26.6.10; die Anrufkontext-Felder (callerNumber bis recordedAccountId) seit Modulversion 26.7.28.

Den anlagenweiten Ereigniskatalog führt die Ereignisliste der EventBridge-Dokumentation; Änderungen an den Ereignissen dokumentieren die Release Notes der jeweiligen Modulversion.

Grundlagen​

ActionButtonEvent​

Die Nutzlast payload​

TranscriptionSummaryReadyEvent​

Struktur von summaryJson​

TranscriptionSummaryChangedEvent​

Versionierung & Kompatibilität​