Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M12-telefonie.md
T

20 KiB
Raw Blame History

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
12 Telefonie (AirCall) 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-7
LP-9
LP-10
LP-11
LP-13
requirements-pur

Modul 12 — Telefonie (AirCall)

Detail-Spec gemäß LP-9. Phase 1 ausschließlich AirCall (User-Korrektur — Sipgate erst Phase 2). Click-to-Call aus Kontakt-/Deal-/Lead-Karte, eingehende Anrufe über Webhook → Auto-Match auf Kontakt + Activity-Stream-Eintrag, Trigger für Automation-Engine. Adapter-Pattern (LP-11) ermöglicht spätere Sipgate-Anbindung ohne Code-Umbau. AirCall ist laut LP-7 ein USP-Tool, das bei Geerkens bleibt (also keine Ablöse, sondern saubere Anbindung).

Themenblöcke

A. Datenmodell
B. Connect-Flow (OAuth AirCall)
C. Click-to-Call
D. Eingehende Anrufe (Webhook + Auto-Match)
E. Anruf-Logging und Activity-Stream
F. Trigger für Automation-Engine
G. Permissions
H. Provider-Adapter (LP-11)
I. Phase 2

Block A — Datenmodell

TelephonyConnection

Pro Tenant max. 1 aktive Connection. Tenant-scoped (RLS).

  • id, tenant_id, created_at, updated_at
  • provider (Enum: aircall — Phase 1 only; sipgate Phase 2)
  • oauth_access_token_encrypted, oauth_refresh_token_encrypted, oauth_token_expires_at
  • oauth_scope_granted (Liste)
  • provider_company_id (AirCall-Company-ID)
  • provider_company_name (Klartext-Name aus AirCall)
  • connection_status (Enum: connecting | active | error | revoked)
  • last_health_check_at, last_error_text
  • webhook_secret_encrypted (für Webhook-Signatur-Verifikation)
  • connected_by_user_id (FK auf TenantUser — wer hat verbunden)
  • archived_at

Indizes: (tenant_id, provider) unique, (tenant_id, connection_status).

TelephonyUserBinding

Verknüpft AirCall-User (in der AirCall-Org) mit HiveGrid-TenantUser. Pflicht für Click-to-Call und Anruf-Zuordnung.

  • id, tenant_id, connection_id (FK)
  • tenant_user_id (FK auf TenantUser)
  • provider_user_id (AirCall-User-ID)
  • provider_user_email (Snapshot — für Match-Visualisierung)
  • provider_user_name
  • is_active (Boolean — wird false bei AirCall-User-Deaktivierung)
  • bound_at, unbound_at

Indizes: (tenant_id, tenant_user_id), (tenant_id, provider_user_id) unique pro Connection.

TelephonyCallSession

Pro Anruf 1 Eintrag. Auch outbound Click-to-Call.

  • id, tenant_id, connection_id, created_at, updated_at
  • provider_call_id (AirCall-Call-ID — unique pro Connection)
  • direction (Enum: inbound | outbound)
  • status (Enum: ringing | in_progress | done | missed | voicemail | failed)
  • from_number (E.164 normalisiert)
  • to_number (E.164 normalisiert)
  • started_at, answered_at (nullable), ended_at (nullable)
  • duration_seconds (Integer, nullable bis abgeschlossen)
  • tenant_user_id (FK — wer hat den Anruf geführt; bei Inbound: wer hat angenommen, bei Outbound: wer hat angerufen)
  • matched_contact_id (FK auf Contact, nullable)
  • matched_lead_id (FK auf Lead, nullable)
  • matched_deal_id (FK auf Deal, nullable)
  • matched_project_id (FK auf Project, nullable)
  • match_confidence (Enum: high | medium | low | manual | none)
  • manual_override_at, manual_override_user_id
  • note_text (User-editierbar nach Anruf — Markdown)
  • note_updated_at, note_updated_by_user_id
  • recording_url (AirCall-Recording, optional — Phase 1 nur Link, kein Download/Storage)
  • recording_available_until (AirCall-Recordings haben Retention)
  • tags[] (für Auswertung — Phase 1 manuell)
  • archived_at

Indizes:

  • (tenant_id, started_at DESC) — Listen-View
  • (tenant_id, matched_contact_id, started_at DESC) — Activity am Kontakt
  • (tenant_id, tenant_user_id, started_at DESC) — pro User-Anruf-Liste
  • (tenant_id, provider_call_id) unique

TelephonyWebhookEvent

Roh-Log der eingegangenen Webhooks von AirCall. Append-only.

  • id, tenant_id, connection_id, received_at
  • provider (Enum)
  • event_type (Enum: call.created | call.ringing_on_agent | call.answered | call.hungup | call.commented | call.tagged | user.created | etc.)
  • provider_event_id (für Idempotenz — AirCall liefert eindeutige IDs)
  • event_payload (JSONB — kompletter Webhook-Body)
  • signature_valid (Boolean)
  • processing_status (Enum: received | processing | done | failed | discarded)
  • processed_at, error_text
  • derived_call_session_id (FK, nullable)

Retention: 30 Tage, danach gelöscht (außer failed → 90 Tage).


Block B — Connect-Flow (OAuth AirCall)

Setup unter /{tenant}/settings/integrations/telephony/

Schritt 1 — AirCall verbinden:

  1. Tenant-Admin (oder integrations.admin) klickt „AirCall verbinden"
  2. Redirect zu AirCall-OAuth mit Scopes: public_api (Read+Write Calls/Users/Numbers/Tags)
  3. Callback → Tokens encrypted gespeichert
  4. System legt Webhook-Subscription bei AirCall an für Events: call.*, user.*
  5. AirCall liefert Webhook-Secret → wird encrypted gespeichert
  6. connection_status = active

Schritt 2 — User-Bindings:

  • System listet alle AirCall-User der Connection-Company (über AirCall-API GET /users)
  • Tenant-Admin sieht Liste mit Auto-Match-Vorschlag (basiert auf Email-Adresse: AirCall-User-Email vs. TenantUser-Email)
  • Manuelle Korrektur möglich
  • Pro User: Bindung-Bestätigen-Button → TelephonyUserBinding-Eintrag
  • Klartext: „X von Y AirCall-Usern automatisch zugeordnet. [Y] manuell zuordnen."

Schritt 3 — Klartext-Test:

  • Tenant-Admin klickt „Verbindung testen" → System ruft AirCall-Health-API → grünes Häkchen
  • Bei Fehler: spezifische Diagnose (Token abgelaufen / Scope fehlend / Network)

Reconnect / Token-Refresh

  • AirCall-Tokens haben langen Lebenszeit, aber Refresh-Worker prüft alle 24h und erneuert <72h Restlaufzeit
  • Bei Refresh-Fehler → connection_status = revoked, Klartext-Notification an Tenant-Admin: „Deine AirCall-Verbindung wurde unterbrochen — bitte erneut verbinden. [Verbindung erneuern]"

Disconnect

  • „Verbindung trennen" mit Bestätigungs-Dialog: „Click-to-Call wird deaktiviert. Bisherige Anruf-Logs bleiben erhalten. Eingehende Anrufe werden nicht mehr verknüpft."
  • System ruft AirCall-OAuth-Revoke auf, Webhook-Subscription gekündigt
  • connection_status = revoked
  • Tokens und Webhook-Secret aus DB gelöscht

Klartext-Diagnose im Connection-Status (LP-10)

  • connecting: „AirCall-Verbindung wird eingerichtet, das dauert wenige Sekunden..."
  • active: „Verbunden mit AirCall-Company [Name]. Letzte Health-Check: [Zeit]"
  • error: „AirCall meldet [konkreter Fehler] — wir versuchen es erneut. [Manuell prüfen]"
  • revoked: „Verbindung getrennt. [Erneut verbinden]"

Block C — Click-to-Call

Auslöse-Punkte

  • Kontakt-Detail-View → „Anrufen"-Funktion
  • Deal-Detail-View → „Anrufen" (verwendet primären Kontakt am Deal)
  • Lead-Detail-View → „Anrufen" (verwendet Lead.phone)
  • Kontakt-Liste (Bulk: nur Single-Call, kein Bulk-Call in Phase 1)

Click-to-Call-Flow

  1. User klickt „Anrufen" auf Kontakt mit Telefonnummer
  2. System prüft:
    • Tenant hat aktive TelephonyConnection?
    • User hat TelephonyUserBinding?
    • Kontakt hat normalisierte Telefonnummer?
  3. Bei allen ✓: System sendet AirCall-API-Call POST /users/{user_id}/calls mit to: contact.phone
  4. AirCall klingelt am AirCall-Phone des Users (Web-App / Mobile-App / Desk-Phone)
  5. User nimmt Anruf in AirCall an, AirCall ruft Kontakt
  6. AirCall sendet Webhook call.created → System legt TelephonyCallSession an mit direction = outbound, tenant_user_id = self, matched_contact_id = contact

Edge-Cases

  • Kontakt hat mehrere Telefonnummern: Modal mit Auswahl der Nummer (Primary vorausgewählt) — falls nur 1 Nummer existiert, direkt anrufen
  • User hat keine TelephonyUserBinding: Klartext: „Du hast keine AirCall-Zuordnung. [Tenant-Admin kontaktieren]"
  • Tenant hat keine Connection: Funktion ausgegraut + Tooltip: „AirCall ist nicht verbunden. [Verbinden — nur für Admins]"
  • AirCall-API-Fehler: Klartext: „AirCall meldet [Fehler]. [Erneut versuchen]"
  • Telefonnummer ungültig: Klartext: „Telefonnummer [wert] ist ungültig. [Korrigieren]"

Telefonnummern-Normalisierung

  • Beim Speichern: Nummer wird zu E.164 normalisiert (z.B. 0211 1234567 → +492111234567)
  • Annahme Default-Country: Tenant-Country aus Tenant.country (default DE)
  • Validierung über libphonenumber
  • Anzeige im UI bleibt user-freundlich, intern E.164

Nicht-AirCall-Fallback

  • Falls Tenant keine AirCall-Connection hat: Click-to-Call-Funktion zeigt tel:-Link (Browser/OS öffnet Default-Telefon-App)
  • Kein Logging, keine Activity (Browser-tel: ist außerhalb HiveGrid)

Block D — Eingehende Anrufe (Webhook + Auto-Match)

Webhook-Endpoint

  • AirCall pusht an /api/v1/webhooks/telephony/aircall/{tenant_slug}
  • Signatur-Verifikation über webhook_secret_encrypted
  • Bei Signatur-Fehler: Event in TelephonyWebhookEvent mit signature_valid=false + processing_status=discarded, kein Verarbeitungs-Pfad

Event-Verarbeitung

call.created (eingehender Anruf, klingelt):

  1. TelephonyCallSession anlegen mit direction=inbound, status=ringing
  2. Auto-Match auf Kontakt/Lead über from_number starten

call.answered:

  1. status=in_progress, answered_at=now, tenant_user_id=lookup(provider_user_id)

call.hungup:

  1. status=done, ended_at=now, duration_seconds=calculated
  2. Activity-Stream-Eintrag erzeugen (siehe Block E)
  3. Falls recording_url im Event: in CallSession speichern

call.commented (User schreibt in AirCall-App Notiz):

  1. note_text aktualisiert + Activity-Update

call.tagged:

  1. tags[] synchronisiert

user.created:

  • Neue AirCall-User in der Org → Auto-Match-Vorschlag in Setup-UI

Auto-Match-Logik (eingehende Anrufe)

Match auf Kontakt (über Telefonnummer):

  1. Normalisiere from_number zu E.164
  2. Suche in ContactPhone (Tenant-scoped) nach exakter Übereinstimmung
  3. Hard-Match: exakter E.164-Match → matched_contact_id + match_confidence=high
  4. Soft-Match: suffix-Match (letzte 8 Ziffern) → match_confidence=medium, Klartext-Hinweis im UI: „Vermutlich [Kontakt-Name] — manuell bestätigen?"
  5. No-Match: keine Zuordnung, im UI sichtbar als „Unbekannte Nummer"

Match auf Lead:

  • Falls keine Contact-Match: Suche in Lead.phone
  • Hard-Match → matched_lead_id

Match auf Deal (über Kontakt-Verknüpfung):

  • Falls matched_contact_id UND der Kontakt hat genau 1 offenen Deal → Deal automatisch zuordnen mit match_confidence=medium

Manuelle Override:

  • Im Call-Detail-View kann User Match überschreiben
  • manual_override_at + manual_override_user_id werden gesetzt

Eingehender Anruf-Push-Notification

  • Bei call.ringing_on_agent für einen User mit TelephonyUserBinding: Push-Notification an HiveGrid-Mobile-App des Users (über Modul 8 Notifications)
  • Inhalt: „Eingehender Anruf von [Name oder Nummer]. [Kontakt öffnen]"
  • Klick öffnet Kontakt-Detail-View — User kann Notizen vorbereiten während Anruf läuft

Block E — Anruf-Logging und Activity-Stream

Anruf-Liste am Kontakt

  • Aufgeführt im Activity-Stream der gematchten Entity
  • Activity-Typ: call_inbound oder call_outbound
  • summary_text Beispiel: „Eingehender Anruf von Max Mustermann (3:45 Min)" / „Verpasster Anruf von +49..."
  • metadata: provider_call_id, duration_seconds, tenant_user_id, recording_url

Notiz-Editor nach Anruf

Aktivierung:

  • Nach Anruf-Ende (Webhook call.hungup): UI-Notification an User: „Anruf beendet (3:45 Min) — Notiz hinzufügen?"
  • User klickt → öffnet Note-Editor in Call-Session-Detail
  • Editor: Markdown-Textarea + Save-Button
  • Save → note_text, note_updated_at, Activity-Update

Editierbar bis:

  • Phase 1: jederzeit editierbar (mit Audit-Log bei Änderung)
  • Edge: nach 30 Tagen Read-Only (Phase 2 Setting)

Verpasste Anrufe

  • status=missed (kein User hat angenommen)
  • Activity-Typ call_inbound mit summary_text: „Verpasster Anruf von [Name/Nummer] um [Zeit]"
  • Notification an Tenant-User mit telephony.read_all ODER an User in der AirCall-Ring-Group (basierend auf AirCall-Konfiguration)

Recording-Anzeige

  • Falls recording_url vorhanden: Link im Call-Detail-View „Aufzeichnung anhören (öffnet AirCall)"
  • Phase 1: kein Download / kein Re-Hosting
  • Phase 2 (mit Whisper-EU-Transkription): Auto-Transkript

Activity-Stream-Aggregat

  • Kontakt-Detail zeigt Anruf-Stats: „12 Anrufe geführt (8 outbound, 4 inbound), Durchschnitt 4:23 Min"
  • Klick auf Anruf-Activity → öffnet Call-Session-Detail mit Notiz-Editor

Block F — Trigger für Automation-Engine

Trigger-Typen die M12 publiziert

  • call.received — Anruf eingegangen (Webhook call.created)
  • call.answered — Anruf wurde angenommen
  • call.completed — Anruf abgeschlossen (Webhook call.hungup)
  • call.missed — Anruf verpasst (kein Annehmer in Ring-Time)

Trigger-Payload

{
  "trigger_type": "call.completed",
  "call_session_id": "...",
  "tenant_user_id": "...",
  "matched_contact_id": "...",
  "matched_deal_id": "...",
  "direction": "inbound",
  "duration_seconds": 225,
  "from_number": "+49...",
  "to_number": "+49...",
  "started_at": "2026-05-08T10:23:00Z",
  "ended_at": "2026-05-08T10:26:45Z",
  "has_note": true,
  "tags": ["follow-up"]
}

Use-Cases (Geerkens-relevant)

  • „Wenn Anruf > 2 Min mit unbekannter Nummer → Lead anlegen"
  • „Wenn verpasster Anruf während Bürozeit → Task für Backoffice ‚Rückruf'"
  • „Wenn Anruf-Tag = ‚Wartung' → Deal in Pipeline ‚Service' anlegen"

Trigger-Filter

  • Pro Trigger: Filter-Definition (analog M17)
  • Beispiel: direction=inbound AND duration_seconds>120 AND matched_contact_id=null

Permission

  • Trigger-Konfiguration: automation.write + telephony.read_all
  • Auslösung: System-Actor

Block G — Permissions

Permission-IDs

Permission Erlaubt
telephony.click_to_call Click-to-Call-Funktion nutzen (Outbound) — eigene Anrufe sichtbar
telephony.read_own Eigene Anrufe sehen (Activity-Stream am Kontakt + eigene Anruf-Liste)
telephony.read_all Alle Tenant-Anrufe sehen
telephony.write_notes_own Notizen zu eigenen Anrufen schreiben/editieren
telephony.write_notes_all Notizen zu allen Anrufen schreiben/editieren
telephony.admin Connection-Setup, User-Bindings verwalten, Trigger-Konfiguration

Bundle-Mapping

Bundle Atomare Permissions
telephony.none (keine)
telephony.user telephony.click_to_call + telephony.read_own + telephony.write_notes_own
telephony.read_all telephony.user + telephony.read_all
telephony.admin alle obigen + telephony.write_notes_all + telephony.admin

Anwendung in Routes / Funktionen

  • Click-to-Call-Funktion in Kontakt/Deal/Lead-Detail: telephony.click_to_call + verbundene Connection + User-Binding
  • Anruf-Liste am Kontakt: telephony.read_own (nur eigene) oder telephony.read_all
  • Notiz-Editor: telephony.write_notes_own (nur eigene) oder telephony.write_notes_all
  • /{tenant}/settings/integrations/telephony/ (Setup): tenant.admin ODER integrations.admin (oder telephony.admin)

Owner-Check für read_own

  • User mit telephony.read_own sieht nur Calls mit tenant_user_id = self
  • Anrufe ohne tenant_user_id (Auto-Match noch nicht erfolgt) sichtbar nur mit telephony.read_all

Klartext-Fehler

  • Click-to-Call ohne Connection: „AirCall ist nicht verbunden. [Tenant-Admin: Verbindung einrichten]"
  • Click-to-Call ohne User-Binding: „Du bist keinem AirCall-User zugeordnet. [Admin kontaktieren]"
  • Notiz-Edit ohne Permission: Editor read-only mit Tooltip „Berechtigung zum Bearbeiten fehlt"

Block H — Provider-Adapter (LP-11)

TelephonyProviderInterface

Gemeinsames Interface für AirCall (Phase 1) und spätere Provider:

  • connect(authCode) → ConnectionInfo
  • disconnect(connectionId) → void
  • listProviderUsers(connectionId) → ProviderUser[]
  • triggerOutboundCall(providerUserId, toNumber) → ProviderCallId
  • subscribeToWebhooks(connectionId, eventTypes[]) → SubscriptionInfo
  • verifyWebhookSignature(payload, signature, secret) → Boolean
  • parseWebhookEvent(payload) → NormalizedCallEvent
  • getRecordingUrl(providerCallId) → URL | null

Implementierung Phase 1

  • AirCallAdapter: spricht AirCall-Public-API + AirCall-Webhooks
  • Phase 2: SipgateAdapter — selbes Interface, eigene Implementierung

Klartext-Diagnose pro Adapter (LP-10)

  • AirCall 401 unauthorized → „AirCall-Verbindung abgelaufen — bitte erneut verbinden."
  • AirCall 403 forbidden → „AirCall meldet ‚Zugriff verweigert' — möglicherweise wurde dein AirCall-Account aus der Company entfernt. [Admin kontaktieren]"
  • AirCall 404 user not found → „Dein AirCall-User existiert nicht mehr. [User-Binding aktualisieren]"
  • Generisch unbekannter Fehler → „AirCall hat einen unbekannten Fehler gemeldet. Wir versuchen es erneut. [Logs anzeigen]" (Logs-Permission telephony.admin)

Activity-Stream-Integration

Activity-Typen die M12 produziert

  • call_inbound — eingehender Anruf
  • call_outbound — ausgehender Anruf
  • call_missed — verpasster Anruf
  • call_note_added — Notiz hinzugefügt
  • call_note_edited — Notiz editiert (Audit)

Verknüpfungen

  • Activities erscheinen am gematchten Contact / Deal / Lead / Project
  • Aggregat in Contact-Detail: „12 Anrufe insgesamt"

Permission-Wirkung

  • Activities sichtbar nur mit passender telephony.*-Permission
  • Notiz-Inhalt visible mit telephony.read_own/all (User mit nur crm.read_* ohne telephony.* sieht nur „Anruf am [Datum] (3:45 Min)" ohne Notiz-Detail)

Klartext-Hinweise/-Fehler (Querschnitt)

  • AirCall-Connection-Status:
    • Setup-noch-nicht-fertig: „AirCall-Verbindung läuft — letzter Check: [Zeit]"
    • Connection-revoked: „Deine AirCall-Verbindung wurde unterbrochen. [Erneut verbinden]"
  • Click-to-Call-Fehler:
    • Kontakt-ohne-Phone: „Dieser Kontakt hat keine Telefonnummer hinterlegt. [Nummer hinzufügen]"
    • Phone-ungültig: „Die Nummer [wert] konnte nicht angewählt werden. [Korrigieren]"
  • Webhook-Probleme:
    • Signatur-Fehler (sichtbar nur in Logs-View): „Webhook-Signatur ungültig — möglicherweise wurde Webhook-Secret rotiert. [Verbindung neu prüfen]"

Phase 2 / spätere Features

  • Sipgate-Adapter — zweiter Provider über selbes Interface
  • Voicemail-Transkription über Whisper-EU (Scaleway-Inferenz, LP-13) — automatische Text-Notiz aus Recording
  • In-App-Calling — Anruf direkt aus HiveGrid-Browser ohne externe AirCall-App (über AirCall Phone Embedded SDK)
  • Bulk-Click-to-Call — Anruf-Listen abarbeiten (Power-Dialer-Light)
  • Anruf-Skripte / Cheat-Sheets — Vertriebsleitfaden im Kontext beim Click-to-Call
  • Auto-Tag basierend auf Anruf-Outcome — KI klassifiziert Notizen und setzt Tags
  • Reporting-Dashboard — Call-Volume pro Team, durchschnittliche Anrufdauer, Conversion-Rate

Architektur-Vorschriften (Querschnitt)

  • LP-7: AirCall bleibt — keine Ablöse, saubere Anbindung
  • LP-9: Requirements-pur, kein Layout
  • LP-10: Klartext-Diagnose bei jedem Webhook-Fehler, OAuth-Disconnect, Click-to-Call-Fehler
  • LP-11: Adapter-Pattern, AirCall = erste Implementierung, Sipgate-Phase 2
  • LP-13: AirCall ist EU-konform (Server in EU), Phase-2-Whisper läuft auf Scaleway-EU
  • AV #5 Permissions-aware-Default: Anruf-Liste filtert nach Permission
  • AV #6 Audit-Trail: Connection-Setup, User-Bindings, Notiz-Edits geloggt

Detail-Spec-Status: DRAFT

Erste vollständige Detail-Spec für Modul 12. Vor Bau: AirCall-OAuth-Setup im Geerkens-Konto testen, Webhook-Events live prüfen, Telefonnummer-Normalisierung mit deutschen/österreichischen/schweizer Nummern testen.

Offene Detail-Punkte (nicht-blockierend):

  • AirCall-Public-API-Pricing (nutzen wir Standard-API oder benötigen wir Higher-Tier)
  • Recording-Retention bei AirCall (welche Stufe — beeinflusst recording_available_until)
  • Default-Ring-Group-Konfiguration für Auto-Match-Notification (welche User-Gruppe wird bei Inbound benachrichtigt)
  • Subframe-UI-Designs (separat)
  • Verknüpfung mit Modul 8 Notifications für Push-Push-Benachrichtigung bei Inbound