Was du mit der API tun kannst
| Bereich | Was geht |
|---|---|
| Chat auf deiner Website | Besucher chatten mit Petra, ohne API-Key im Browser. Eine Sitzung starten, eine Nachricht schicken, einen Verlauf wieder laden. |
| Kontakte | Kontakte anlegen und ändern, samt eigener Felder. |
| Felder | Die Felder auflisten, die Petra im Anruf erfasst und die an deinen Kontakten hängen. |
| Mitarbeiter | Auflisten, anlegen, abrufen, ändern und löschen: Telefonnummern, Arbeitszeiten und ob Petra Anrufe an sie durchstellen darf. |
| Aufgaben | Eine Aufgabe für das Team anlegen. Mit einem Befehl wird daraus ein geplanter Auftrag an Petra, auf Wunsch wiederkehrend. |
| Webhooks | Webhooks anlegen und löschen. HalloPetra ruft dann dein System auf, wenn etwas passiert. |
| Abläufe und Formulare | Abläufe und Formulare auflisten, um einen Webhook auf bestimmte davon zu beschränken. |
Die Adresse der API ist https://hallopetra-api.hallopetra.de. Alle Endpunkte liegen unter /v1.
Anmeldung mit API-Key
Öffne im Dashboard Einstellungen → Integrationen → API-Keys.
Leg einen Key an. Er beginnt mit
hp_ck_und gilt nur für deinen Betrieb.Kopier den Key sofort. HalloPetra zeigt ihn genau einmal im Klartext.
Schick ihn bei jeder Anfrage als Bearer-Token mit.
Wichtig:Der Chat auf deiner Website braucht keinen API-Key. Er läuft im Browser eines anonymen Besuchers, und dort darf nie ein Key stehen. Stattdessen bekommt jeder Besucher ein eigenes Widget-Token.
Grundregeln
| Thema | Regel |
|---|---|
| Version | Die Version steht im Pfad (/v1). Neue Endpunkte, neue optionale Parameter und neue Antwortfelder können jederzeit dazukommen. Bau dein Programm so, dass es unbekannte Felder ignoriert. Änderungen, die etwas brechen, kommen nur als neue Pfad-Version. |
| Limit | 300 Anfragen pro 60 Sekunden je Key, über alle Endpunkte zusammen. Jede Antwort nennt in RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset, wie viel übrig ist. Darüber kommt 429 RATE_LIMIT_EXCEEDED mit Retry-After. |
| Sichere Wiederholung | Schick bei schreibenden Anfragen einen Idempotency-Key mit. Eine Wiederholung mit demselben Key liefert dieselbe Antwort, ohne den Vorgang noch einmal auszuführen. Keys gelten 24 Stunden. Nimm einen Key pro Vorgang, nicht pro Versuch. |
| Listen | Jede Liste antwortet gleich: items, totalCount und nextCursor. Blättern kannst du mit page und limit oder der Reihe nach mit cursor und limit. |
| Leere Werte | Ein Feld ohne Wert fehlt in der Antwort. Es kommt nie als null. |
| Gleichzeitige Änderungen | Beim Abrufen eines einzelnen Eintrags bekommst du ein ETag. Schickst du es beim Ändern als If-Match mit, lehnt die API ab, wenn der Eintrag inzwischen geändert wurde (412 PRECONDITION_FAILED). |
| Fehler | Jeder Fehler hat dieselbe Form mit code, message und requestId, dazu oft reason und details. Richte dein Programm nach code und reason, nicht nach message. Der Text ist für Menschen und kann sich ändern. |
Chat mit Petra auf deiner Website
Der Chat für Besucher deiner Website läuft in drei Aufrufen:
POST /v1/widget/sessionsmit dercustomerIdaus deinem Einbau-Code. Die Antwort enthält ein Widget-Token sowie Name und Logo deines Betriebs für den Kopf des Chats.POST /v1/widget/chatmit diesem Token schickt eine Nachricht. Petras Antwort kommt als Stream. Beim ersten Mal legt HalloPetra den Kontakt des Besuchers an und gibt im HeaderX-HP-Widget-Tokenein neues Token zurück. Speicher es, dann behält ein wiederkehrender Besucher seinen Verlauf.GET /v1/widget/threads/{threadId}liefert den Verlauf, zum Beispiel nach dem Neuladen der Seite.
Besucher schreiben reinen Text, ohne Dateien. Ein Gespräch fasst 80 Nachrichten, Besucher und Petra zusammen. Ein Betrieb kann standardmäßig 100 neue Gespräche pro Tag eröffnen.
Wie du den fertigen Chat ohne eigene Programmierung einbaust, steht in der Anleitung Chat-Widget auf deiner Website einrichten.
Webhooks: HalloPetra ruft dein System auf
Mit POST /v1/webhooks meldest du eine Adresse an. Vier Ereignisse stehen zur Wahl:
| Ereignis | Wann | Wartet Petra? |
|---|---|---|
call.incoming | Ein Anruf geht ein, bevor Petra abnimmt. | Ja, höchstens 2,5 Sekunden. Danach läuft der Anruf ohne deine Daten weiter. |
call.tool | Petra ruft im Gespräch ein Werkzeug auf, das du für bestimmte Abläufe angemeldet hast. | Ja, bis zu 10 Sekunden. Petra liest dem Anrufer deine Antwort vor. |
call.finished | Nach jedem Anruf, sobald Zusammenfassung und erfasste Daten fertig sind. | Nein. |
form.submitted | Nach jedem abgeschickten Formular. | Nein. |
Wichtig:HalloPetra wiederholt eine Zustellung nie. Jeder Aufruf trägt die Signatur X-HalloPetra-Signature. Prüf sie mit dem Secret, das du beim Anlegen des Webhooks bekommst, und lehne Aufrufe ab, die älter als 5 Minuten sind.
Wie du Webhooks im Dashboard einrichtest, steht in der Anleitung Webhooks. Ohne Programmierung geht es mit Make oder n8n.
Häufige Fragen
Wo finde ich meinen API-Key?
Im Dashboard unter Einstellungen → Integrationen → API-Keys. HalloPetra zeigt den Key nur einmal beim Anlegen im Klartext.
Wie viele Anfragen darf ich schicken?
300 Anfragen pro 60 Sekunden je Key. Eine Chat-Nachricht zählt als eine Anfrage, egal wie lange die Antwort läuft.
Was passiert, wenn mein System bei einem Anruf zu langsam antwortet?
Bei call.incoming wartet HalloPetra höchstens 2,5 Sekunden. Kommt bis dahin nichts, läuft der Anruf ohne deine Daten weiter.
Bleibt die Verbindung zum Kontakt erhalten, wenn ich einen Mitarbeiter lösche?
Ja. Gelöscht wird nur der Mitarbeiter. Der dazugehörige Kontakt und seine Gruppen bleiben bestehen.