Einführung - homie Documentation

Mit der homie REST API erstellst du Chats, sendest Nachrichten an einen Assistenten und empfängst Antworten programmatisch. Nutze sie, wenn du eine eigene Integration bauen möchtest statt des einbettbaren Widgets.

Der API-Zugang ist ausschließlich für Enterprise-Kunden verfügbar. API-Keys werden von homie erstellt und vergeben — du kannst sie nicht selbst erzeugen. Wende dich an dein homie-Account-Team, um Zugang anzufragen.

Authentifizierung

Jede Anfrage muss deinen API-Key im x-api-key-Header enthalten. Keys werden von homie an deine Organisation vergeben — halte sie geheim und nutze sie nur serverseitig.

curl https://api.yourhomie.ai/v1/chats \
  -H "x-api-key: homie_sk_live_8f3a..." \
  -H "Content-Type: application/json"

Halte deinen API-Key geheim. Er gewährt Zugriff auf die Daten deiner Organisation, nutze ihn also nur serverseitig und gib ihn niemals im Browser oder in einer Mobile-App preis.

Der Chat-Ablauf

Eine typische Integration folgt drei Schritten:

Chat erstellen

Rufe Chat erstellen mit deiner chatbotId auf. Du erhältst eine chatId, die die Konversation identifiziert.

Nachricht hinzufügen

Rufe Nachricht hinzufügen mit der chatId, der message des Nutzers und der currentUrl auf. Der Assistent beginnt, eine Antwort zu generieren.

Events abhören

Öffne den Nachrichten-Events-Stream für die chatId, um die Antwort des Assistenten und Tool-Aktivität in Echtzeit über Server-Sent Events zu empfangen.

Fehlerformat

Fehler liefern einen HTTP-Status außerhalb des 2xx-Bereichs und einen JSON-Body mit einer message, die beschreibt, was schiefgelaufen ist:

{
  "message": "Chat not found"
}

Häufige Statuscodes:

Status	Bedeutung
`401`	Fehlender oder ungültiger API-Key.
`404`	Die angeforderte Ressource existiert nicht.
`422`	Der Request-Body hat die Validierung nicht bestanden.
`429`	Das Nachrichtenkontingent deines Plans ist aufgebraucht.

Die API-Nutzung zählt auf das monatliche Nachrichtenkontingent deines Plans. Ist das Kontingent erreicht, liefern die Nachrichten-Endpunkte einen Fehler, bis es zurückgesetzt wird oder du deinen Plan upgradest. Den Verbrauch siehst du unter Nutzung auf der Plattform.

Paginierung

List-Endpunkte liefern einen paginierten Umschlag zurück. Das items-Array enthält die Ergebnisse der aktuellen Seite, die übrigen Felder beschreiben die Gesamtmenge:

{
  "items": [],
  "totalItems": 42,
  "size": 20,
  "totalPages": 3,
  "currentPage": 1,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}

prevPage und nextPage sind null, wenn es keine vorherige bzw. nächste Seite gibt.

Bezeichner

Alle Ressourcen-IDs (chatId, chatbotId, userId, organizationId) sind eindeutige String-IDs, zum Beispiel 5e9c1a2b-3d4e-4f60-b2f2-9f4b1c2d3e4f.

Endpunkte

Chat erstellen

Starte eine neue Konversation für einen Chatbot.

Chat abrufen

Rufe einen Chat anhand seiner ID ab.

Nachricht hinzufügen

Sende eine Nutzernachricht an den Assistenten.

Nachrichten auflisten

Blättere durch den Nachrichtenverlauf eines Chats.

Nachrichten-Events

Streame Assistenten-Antworten über SSE.

PDP-Fragenset abrufen

Rufe öffentliche Produktfragen für eine Seite ab.

​Authentifizierung

​Der Chat-Ablauf

​Fehlerformat

​Paginierung

​Bezeichner

​Endpunkte

Chat erstellen

Chat abrufen

Nachricht hinzufügen

Nachrichten auflisten

Nachrichten-Events

PDP-Fragenset abrufen

Authentifizierung

Der Chat-Ablauf

Fehlerformat

Paginierung

Bezeichner

Endpunkte