--- module: 12 title: Telefonie (AirCall) phase: 1 status: detail-spec-draft last_updated: 2026-05-08 session_source: brainstorming-session-2026-05-07-2206.md related_lps: [LP-7, LP-9, LP-10, LP-11, LP-13] spec_style: 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