9.0 KiB
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
- HalloPetra-API-Vertrag erhoben (Auth/Webhook-Events/Recording/Call-Lifecycle)
- auf
TelephonyProviderInterfacegemappt (connect/triggerOutboundCall/subscribeToWebhooks/verifyWebhookSignature/parseWebhookEvent/getRecordingUrl) - 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:
- API-Key als Apps-Engine-Credential,
- Post-Call-Webhook für Anruf-Match, Logging und Automation,
- 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-keyserstellt und nur einmal angezeigt. - API-Basis:
https://api.hallopetra.de. - Authentifizierungsheader:
Authorization: Bearer <api-key>.x-api-keywurde vom Gateway abgewiesen. - Kontrollprobe: Das Gateway authentifiziert den
/v1/*-Namensraum vor dem Routing. Ohne/mit falschem Key antwortet/v1/healthmit401; der gültige Test-Key erreicht das Routing und antwortet derzeit mit404, weil kein öffentlicher Health-Handler existiert. Der Adapter akzeptiert diesen beobachteten Auth-Gateway-Vertrag sowie einen künftigen2xx-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):
{
"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.webhookTokenHashenthä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.getRecordingUrlliefert deshalbnull; ein optionales zukünftiges HTTPS-Feldrecording_urlkann 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.
triggerOutboundCallmeldet die Fähigkeit explizit als nicht unterstützt; Click-to-Call bleibt für HalloPetratel:-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.demit 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-P33ist damit baufähig.
Quellen (granular)
ROADMAP-V2.md→ §v2-P11 (Telefonie-Teil) + §Zwei Gaps (HalloPetra M105) + §Offene Vorlauf-Tasks #2ROADMAP.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