# VEXT-2 · HalloPetra-Spec erheben (API-Vertrag) | | | |---|---| | **Typ** | Setup (Externals — `typ:external`) | | **Owner** | Raffael | | **Phase** | Phase 33 (v2-P11) — Telefonie-Erweiterung (Vorlauf) | | **Cycle/Fenster** | Backlog/agil (Trigger, Ziel 2026-07-29) | | **Status** | umgesetzt · API-Vertrag mit Test-Account erhoben | > ✅ **Spec-Gap geschlossen (2026-08-01):** Vertrag über den bereitgestellten Test-Account, die > authentifizierte HalloPetra-Oberfläche und kontrollierte API-Probes erhoben. Es gibt derzeit keine > öffentlich auffindbare OpenAPI-/Swagger-Referenz. Deshalb trennt diese Spec beobachtete Verträge klar von > nicht belegten Fähigkeiten; spätere Herstelleränderungen werden fixture-first nachgezogen. ## Was zu tun Den **HalloPetra-API-Vertrag erheben** und auf das vorhandene `TelephonyProviderInterface` mappen. Konkret klären: - **Auth** (API-Key / OAuth2 / Webhook-Secret?) → für `connect` - **Webhook-Events** (welche Call-Lifecycle-Events: ringing/answered/ended/missed/voicemail?) → für `subscribeToWebhooks`/`parseWebhookEvent` - **Recording** (liefert HalloPetra eine Aufnahme-URL? Auth-Modus?) → für `getRecordingUrl` - **Call-Lifecycle** (Outbound-Trigger-Endpoint, Status-Übergänge) → für `triggerOutboundCall` - **Signaturprüfung** (Webhook-Signatur-Schema) → für `verifyWebhookSignature` Das Ergebnis ist eine kurze Vorlauf-Spec, die VR-P33 baufähig macht. Der AirCall-Adapter (v1-P15) ist die Referenz für Aufbau und Methodensatz. ## Warum / blockt Ohne den erhobenen API-Vertrag ist der HalloPetra-Adapter (VR-P33) nicht baubar — die Interface-Methoden lassen sich nicht implementieren, solange Auth/Webhook-Events/Recording/Lifecycle offen sind. Schließt einen der beiden in ROADMAP-V2 explizit benannten Specs-Gaps (neben Memberspot/Boobora). ## Abhängigkeiten - **Blocked by:** — (extern: HalloPetra-Hersteller/Vertrag) - **Blocks:** `VR-P33` (HalloPetra-Adapter — braucht den erhobenen Vertrag) - **Parallel:** v1-`TelephonyProviderInterface` + AirCall-Adapter (AK-P15a) stehen als Referenz bereit. ## Definition of Done - [x] **HalloPetra-API-Vertrag erhoben** (Auth/Webhook-Events/Recording/Call-Lifecycle) - [x] **auf `TelephonyProviderInterface` gemappt** (connect/triggerOutboundCall/subscribeToWebhooks/verifyWebhookSignature/parseWebhookEvent/getRecordingUrl) - [x] Vorlauf-Spec abgelegt, VR-P33 baufähig markiert ## Erhobener Vertrag (Test-Account, 2026-08-01) ### Produktgrenze HalloPetra ist für HiveGrid **kein zweiter Cold-Calling-Carrier wie Aircall**, sondern ein Inbound-/Office-Assistant. Der erste Integrationsschnitt ist daher: 1. API-Key als Apps-Engine-Credential, 2. Post-Call-Webhook für Anruf-Match, Logging und Automation, 3. später optional Pre-Call-Anreicherung für Anrufererkennung. HalloPetra bietet daneben im Produkt unter anderem E-Mail, Website, WhatsApp, Formulare, Outbound und Routinen. Diese Funktionen sind **nicht** Teil des Telefonie-Tickets `VR-P33` und werden nicht still über den Adapter-Scope gezogen. ### Auth und API-Key - Schlüssel werden im HalloPetra-Dashboard unter `/dashboard/settings/integrations/api-keys` erstellt und nur einmal angezeigt. - API-Basis: `https://api.hallopetra.de`. - Authentifizierungsheader: `Authorization: Bearer `. `x-api-key` wurde vom Gateway abgewiesen. - Kontrollprobe: Das Gateway authentifiziert den `/v1/*`-Namensraum vor dem Routing. Ohne/mit falschem Key antwortet `/v1/health` mit `401`; der gültige Test-Key erreicht das Routing und antwortet derzeit mit `404`, weil kein öffentlicher Health-Handler existiert. Der Adapter akzeptiert diesen beobachteten Auth-Gateway-Vertrag sowie einen künftigen `2xx`-Health-Handler; Provider-Bodies werden nie geloggt. - Es wurde kein OAuth2-Flow, Refresh-Token oder öffentlicher Account-/Identity-Endpunkt gefunden. ### Webhook-Konfiguration Webhooks werden derzeit **manuell** im HalloPetra-Dashboard unter `/dashboard/settings/integrations/webhooks` angelegt. Konfigurierbar sind Name, HTTPS-URL, frei definierbare Header und Variablen. Für `pre_call`/`post_call` gibt es `ALWAYS` oder `ON_DEMAND`. Beobachtete Webhook-Typen: | Typ | Zweck | VR-P33-Verarbeitung | |---|---|---| | `pre_call` | Anrufer vor Annahme erkennen/anreichern | dokumentiert, separater synchroner Nachzug | | `post_call` | Anruf-ID, Dauer, Rufnummer, Thema, Zusammenfassung, Nachrichten und gesammelte Daten liefern | **jetzt** auf terminales Inbound-Event mappen | | `during_call` | Laufzeit-Funktion mit Parametern; Antwort kann gesprochen oder still sein und Kontakt aktualisieren | außerhalb Telefonie-Scope | | `form_submission` | Formular-, Kontakt- und optionaler Call-Kontext | außerhalb Telefonie-Scope | Post-Call-Kernpayload (HalloPetra stellt das Beispiel teils mit einer zusätzlichen `body`-Hülle dar; der Parser akzeptiert beide Varianten): ```json { "webhook_id": "", "data": { "id": "", "duration": 95, "phone": "+49301234567", "topic": "Terminwunsch", "summary": "Kurzfassung", "messages": [{ "role": "assistant | user", "content": "..." }], "collected_data": { "field": "value" }, "main_task_id": "", "email_send_to": "", "forwarded_to": "", "previous_webhook_calls": [] } } ``` Der dokumentierte Post-Call-Payload enthält keine garantierte Eventzeit. Der HiveGrid-Ingress ergänzt deshalb seine serverseitige Empfangszeit. Falls HalloPetra künftig `date`, `ended_at` oder `start_time` mitsendet, haben diese Felder Vorrang. `duration` rekonstruiert ersatzweise den Startzeitpunkt. ### Webhook-Authentisierung - Es wurde **keine native HalloPetra-HMAC-Signatur** oder ein vom Provider erzeugtes Webhook-Secret gefunden. - HalloPetra erlaubt frei definierbare Request-Header. HiveGrid erzeugt daher ein **separates zufälliges Webhook-Secret** und erwartet `Authorization: Bearer `. - Das Secret wird per Apps Engine verschlüsselt gespeichert; `TelephonyConnection.webhookTokenHash` enthält nur SHA-256 für den öffentlichen RLS-Bootstrap. Vergleich erfolgt konstantzeitlich. - API-Key und Webhook-Secret bleiben getrennt, damit ein Webhook-Konfigurationsleck nicht automatisch den HalloPetra-API-Zugriff kompromittiert. ### Recording und Call-Lifecycle - Der beobachtete `post_call`-Vertrag enthält **keine Recording-URL**. `getRecordingUrl` liefert deshalb `null`; ein optionales zukünftiges HTTPS-Feld `recording_url` kann ohne Persistenzumbau übernommen werden. - HalloPetra liefert in diesem Vertrag nur den abgeschlossenen Inbound-Anruf. Eigenständige `ringing`/`answered`/`missed`/`voicemail`-Events wurden nicht gefunden. - Kein öffentlicher Outbound-Trigger-Endpunkt wurde gefunden. Obwohl HalloPetra ein eigenes Outbound-Modul besitzt, darf der Telefonie-Adapter daraus keinen API-Vertrag erfinden. `triggerOutboundCall` meldet die Fähigkeit explizit als nicht unterstützt; Click-to-Call bleibt für HalloPetra `tel:`-Fallback. Aircall bleibt der Cold-Calling-Provider. ## Mapping auf `TelephonyProviderInterface` | Methode | HalloPetra-Vertrag | |---|---| | `connect` / `probe` | API-Key per Bearer gegen authentifizierten `/v1`-Gateway prüfen | | `disconnect` | lokal Credentials widerrufen; Dashboard-Webhook manuell entfernen | | `listProviderUsers` / `listUserNumbers` | keine öffentliche Ressource gefunden, daher leere Liste | | `triggerOutboundCall` | `capability_unsupported`; kein erfundener Endpoint | | `subscribeToWebhooks` | `capability_unsupported`; manuelle Dashboard-Einrichtung mit URL + Custom Header | | `validateWebhook` | separates Custom-Header-Secret konstantzeitlich vergleichen | | `parseWebhookEvent` | `post_call` → `ended`, `inbound`, E.164, dedupe über Webhook-/Call-ID | | `getRecordingUrl` | aktuell `null`, optionales HTTPS-`recording_url` vorbereitet | ## Quellen und Reproduzierbarkeit - Anbieter-Seite: `https://www.hallopetra.de/` - Authentifizierte Test-Account-Seiten: API-Key- und Webhook-Verwaltung (keine Credentials persistiert oder in Logs ausgegeben) - API-Probes gegen `https://api.hallopetra.de` mit bereitgestelltem Test-Key; ausschließlich Read-/Auth- Probes, keine Providerdaten verändert - Versionierte, synthetische Fixtures und Contract-Tests unter `packages/integrations/src/hallopetra/` ## Umsetzungs-Notiz - **2026-08-01 · 3/3 DoD = 100 % done:** Auth, Webhook-Typen, Signaturgrenze, Recording und Lifecycle mit dem bereitgestellten Test-Account erhoben, auf das vorhandene Provider-Interface gemappt und als synthetische Fixtures/Tests festgehalten. Der Testzugang wurde nur read-only untersucht; weder Schlüssel noch Webhooks oder Testanrufe wurden im Anbieter-Account verändert. Adapter-/Fixture-Proof: `001f56a6e`. `VR-P33` ist damit baufähig. ## Quellen (granular) - `ROADMAP-V2.md` → §v2-P11 (Telefonie-Teil) + §Zwei Gaps (HalloPetra M105) + §Offene Vorlauf-Tasks #2 - `ROADMAP.md` → Phase 33 · Milestones: (M105, Block-2) - `designer-briefs/P33-telefonie-hallopetra.md` (Provider-Interface-Methodensatz, Vorlauf-Hinweis) - abhängig-für: `ticket-docs/VR-P33.md`