Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VEXT-2.md
T

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 TelephonyProviderInterface gemappt (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:

  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):

{
  "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