164 lines
9.0 KiB
Markdown
164 lines
9.0 KiB
Markdown
# 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 <api-key>`. `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": "<webhook-id>",
|
|
"data": {
|
|
"id": "<call-id>",
|
|
"duration": 95,
|
|
"phone": "+49301234567",
|
|
"topic": "Terminwunsch",
|
|
"summary": "Kurzfassung",
|
|
"messages": [{ "role": "assistant | user", "content": "..." }],
|
|
"collected_data": { "field": "value" },
|
|
"main_task_id": "<task-id>",
|
|
"email_send_to": "<email>",
|
|
"forwarded_to": "<phone>",
|
|
"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 <webhook-secret>`.
|
|
- 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`
|