489 lines
20 KiB
Markdown
489 lines
20 KiB
Markdown
---
|
||
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
|