Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,488 @@
|
||||
---
|
||||
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
|
||||
Reference in new issue
Block a user