Zum Inhalt springen
Live-Webinar, mittwochs um 16 Uhr: So nimmt Petra jeden Anruf an. Kostenlos, 45 Minuten. Live-Webinar, mittwochs 16 Uhr Platz sichern

Integrationen

HalloPetra API: Petra aus deinem eigenen Programm steuern

Mit der HalloPetra API greifst du aus deinem eigenen Programm auf dein HalloPetra-Konto zu: mit Petra chatten, Kontakte, Mitarbeiter und Aufgaben verwalten und mitbekommen, was Petra vor, während und nach einem Anruf tut.

  • 3 Min. Lesezeit
  • Aktualisiert am

Was du mit der API tun kannst

BereichWas geht
Chat auf deiner WebsiteBesucher chatten mit Petra, ohne API-Key im Browser. Eine Sitzung starten, eine Nachricht schicken, einen Verlauf wieder laden.
KontakteKontakte anlegen und ändern, samt eigener Felder.
FelderDie Felder auflisten, die Petra im Anruf erfasst und die an deinen Kontakten hängen.
MitarbeiterAuflisten, anlegen, abrufen, ändern und löschen: Telefonnummern, Arbeitszeiten und ob Petra Anrufe an sie durchstellen darf.
AufgabenEine Aufgabe für das Team anlegen. Mit einem Befehl wird daraus ein geplanter Auftrag an Petra, auf Wunsch wiederkehrend.
WebhooksWebhooks anlegen und löschen. HalloPetra ruft dann dein System auf, wenn etwas passiert.
Abläufe und FormulareAblä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

  1. Öffne im Dashboard Einstellungen → Integrationen → API-Keys.

  2. Leg einen Key an. Er beginnt mit hp_ck_ und gilt nur für deinen Betrieb.

  3. Kopier den Key sofort. HalloPetra zeigt ihn genau einmal im Klartext.

  4. 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

ThemaRegel
VersionDie 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.
Limit300 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 WiederholungSchick 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.
ListenJede Liste antwortet gleich: items, totalCount und nextCursor. Blättern kannst du mit page und limit oder der Reihe nach mit cursor und limit.
Leere WerteEin Feld ohne Wert fehlt in der Antwort. Es kommt nie als null.
Gleichzeitige ÄnderungenBeim 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).
FehlerJeder 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:

  1. POST /v1/widget/sessions mit der customerId aus deinem Einbau-Code. Die Antwort enthält ein Widget-Token sowie Name und Logo deines Betriebs für den Kopf des Chats.

  2. POST /v1/widget/chat mit diesem Token schickt eine Nachricht. Petras Antwort kommt als Stream. Beim ersten Mal legt HalloPetra den Kontakt des Besuchers an und gibt im Header X-HP-Widget-Token ein neues Token zurück. Speicher es, dann behält ein wiederkehrender Besucher seinen Verlauf.

  3. 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:

EreignisWannWartet Petra?
call.incomingEin Anruf geht ein, bevor Petra abnimmt.Ja, höchstens 2,5 Sekunden. Danach läuft der Anruf ohne deine Daten weiter.
call.toolPetra 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.finishedNach jedem Anruf, sobald Zusammenfassung und erfasste Daten fertig sind.Nein.
form.submittedNach 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.

Probier Petra selbst aus.

Leg ein Konto an und sieh dir im Dashboard an, wie Petra in deinem Betrieb arbeitet.

Petras Notizblock