Zum Hauptinhalt springen

Die API

FirstReply hat eine REST-API für Konversationen, Nachrichten, Kontakte, Wissen, Posteingänge und Mitglieder. Die Referenz ist als OpenAPI-Spezifikation unter api.firstreply.ai veröffentlicht.

API-Schlüssel​

Die API-Schlüssel eines Workspace

Legen Sie einen Schlüssel unter Einstellungen → Entwicklung → API-Schlüssel an. Das braucht die Administrator-Rolle.

Ein Schlüssel hat einen Namen und optional ein Ablaufdatum. Das Geheimnis wird einmal beim Anlegen angezeigt und nie wieder — FirstReply speichert nur einen Hash davon. Wenn Sie es verlieren, löschen Sie den Schlüssel und legen einen neuen an.

Schlüssel beginnen mit einem sichtbaren Präfix, das die Liste anzeigt. Das genügt, um Schlüssel auseinanderzuhalten, ohne einen davon offenzulegen.

Die Liste zeigt außerdem, wann jeder Schlüssel zuletzt benutzt wurde. So finden Sie die, die niemand mehr braucht.

Authentifizierung​

Senden Sie den Schlüssel als Bearer-Token:

curl https://api.firstreply.ai/v1/organizations \
  -H "Authorization: Bearer fr_live_..."

Ein Schlüssel handelt mit den Berechtigungen des Workspace-Inhabers. Es gibt keinen engeren Geltungsbereich. Behandeln Sie einen Schlüssel wie das Passwort des Inhabers: in einem Secret-Store, nie in einem Repository oder in einem Frontend-Bundle, und geben Sie jeder Integration einen eigenen, damit einer widerrufen werden kann, ohne die anderen zu unterbrechen.

Einen Schlüssel rotieren​

  1. Neuen Schlüssel anlegen.
  2. In der Integration ausrollen.
  3. Prüfen, dass der neue benutzt wird — die Spalte „zuletzt benutzt" am alten bewegt sich nicht mehr.
  4. Alten Schlüssel löschen.

Das Löschen wirkt sofort.

Was damit gebaut wird​

Kundendaten füllen. Schreiben Sie eigene Felder an Kontakte aus dem System, dem sie gehören, damit Agents Tarif und Kundennummer sehen, ohne die Konversation zu verlassen.

Konversationen anlegen. Öffnen Sie eine Konversation aus Ihrer eigenen Anwendung, wenn etwas Support-Aufmerksamkeit braucht, und lassen Sie die Antwort über den normalen Kanal zurückkommen.

Berichte. Ziehen Sie Konversationsstatistiken in das, was Ihre Firma ohnehin für Dashboards nutzt.

Auf Ereignisse reagieren. Für alles Ereignisgesteuerte ist ein Webhook das bessere Mittel als das Abfragen der API.

Client-Bibliotheken​

Java — firstreply-java-api, aus demselben Repository wie das Produkt veröffentlicht.

Node — der MCP-Server enthält einen kleinen REST-Client, den Sie als Referenzimplementierung lesen können.

Für alles andere erzeugt die OpenAPI-Spezifikation unter api.firstreply.ai in den meisten Sprachen einen brauchbaren Client.

Grenzen und Fehler​

Die API liefert übliche HTTP-Statuscodes. 401 bedeutet, dass der Schlüssel fehlt, falsch oder widerrufen ist; in den FirstReply-Apps bedeutet ein 401 auf ein Sitzungstoken konventionell, dass die Sitzung abgelaufen ist, und derselbe Code auf einen API-Schlüssel, dass der Schlüssel nicht mehr gültig ist.

Anfragen sind pro Schlüssel begrenzt. Ein 429 trägt einen Retry-After-Header; warten Sie ab, statt sofort erneut zu versuchen.