20 KiB
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 |
|
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_atprovider(Enum:aircall— Phase 1 only;sipgatePhase 2)oauth_access_token_encrypted,oauth_refresh_token_encrypted,oauth_token_expires_atoauth_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_textwebhook_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_nameis_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_atprovider_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_idnote_text(User-editierbar nach Anruf — Markdown)note_updated_at,note_updated_by_user_idrecording_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_atprovider(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_textderived_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:
- Tenant-Admin (oder
integrations.admin) klickt „AirCall verbinden" - Redirect zu AirCall-OAuth mit Scopes:
public_api(Read+Write Calls/Users/Numbers/Tags) - Callback → Tokens encrypted gespeichert
- System legt Webhook-Subscription bei AirCall an für Events:
call.*,user.* - AirCall liefert Webhook-Secret → wird encrypted gespeichert
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
- User klickt „Anrufen" auf Kontakt mit Telefonnummer
- System prüft:
- Tenant hat aktive
TelephonyConnection? - User hat
TelephonyUserBinding? - Kontakt hat normalisierte Telefonnummer?
- Tenant hat aktive
- Bei allen ✓: System sendet AirCall-API-Call
POST /users/{user_id}/callsmitto: contact.phone - AirCall klingelt am AirCall-Phone des Users (Web-App / Mobile-App / Desk-Phone)
- User nimmt Anruf in AirCall an, AirCall ruft Kontakt
- AirCall sendet Webhook
call.created→ System legtTelephonyCallSessionan mitdirection = 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
TelephonyWebhookEventmitsignature_valid=false+processing_status=discarded, kein Verarbeitungs-Pfad
Event-Verarbeitung
call.created (eingehender Anruf, klingelt):
TelephonyCallSessionanlegen mitdirection=inbound,status=ringing- Auto-Match auf Kontakt/Lead über
from_numberstarten
call.answered:
status=in_progress,answered_at=now,tenant_user_id=lookup(provider_user_id)
call.hungup:
status=done,ended_at=now,duration_seconds=calculated- Activity-Stream-Eintrag erzeugen (siehe Block E)
- Falls
recording_urlim Event: in CallSession speichern
call.commented (User schreibt in AirCall-App Notiz):
note_textaktualisiert + Activity-Update
call.tagged:
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):
- Normalisiere
from_numberzu E.164 - Suche in
ContactPhone(Tenant-scoped) nach exakter Übereinstimmung - Hard-Match: exakter E.164-Match →
matched_contact_id+match_confidence=high - Soft-Match: suffix-Match (letzte 8 Ziffern) →
match_confidence=medium, Klartext-Hinweis im UI: „Vermutlich [Kontakt-Name] — manuell bestätigen?" - 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_idUND der Kontakt hat genau 1 offenen Deal → Deal automatisch zuordnen mitmatch_confidence=medium
Manuelle Override:
- Im Call-Detail-View kann User Match überschreiben
manual_override_at+manual_override_user_idwerden gesetzt
Eingehender Anruf-Push-Notification
- Bei
call.ringing_on_agentfür einen User mitTelephonyUserBinding: 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_inboundodercall_outbound summary_textBeispiel: „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_inboundmitsummary_text: „Verpasster Anruf von [Name/Nummer] um [Zeit]" - Notification an Tenant-User mit
telephony.read_allODER an User in der AirCall-Ring-Group (basierend auf AirCall-Konfiguration)
Recording-Anzeige
- Falls
recording_urlvorhanden: 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 (Webhookcall.created)call.answered— Anruf wurde angenommencall.completed— Anruf abgeschlossen (Webhookcall.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) odertelephony.read_all - Notiz-Editor:
telephony.write_notes_own(nur eigene) odertelephony.write_notes_all /{tenant}/settings/integrations/telephony/(Setup):tenant.adminODERintegrations.admin(odertelephony.admin)
Owner-Check für read_own
- User mit
telephony.read_ownsieht nur Calls mittenant_user_id = self - Anrufe ohne
tenant_user_id(Auto-Match noch nicht erfolgt) sichtbar nur mittelephony.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) → ConnectionInfodisconnect(connectionId) → voidlistProviderUsers(connectionId) → ProviderUser[]triggerOutboundCall(providerUserId, toNumber) → ProviderCallIdsubscribeToWebhooks(connectionId, eventTypes[]) → SubscriptionInfoverifyWebhookSignature(payload, signature, secret) → BooleanparseWebhookEvent(payload) → NormalizedCallEventgetRecordingUrl(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 Anrufcall_outbound— ausgehender Anrufcall_missed— verpasster Anrufcall_note_added— Notiz hinzugefügtcall_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 nurcrm.read_*ohnetelephony.*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