Daten-API: Gästenachrichten lesen und senden

Die Nachrichten deiner Gäste sind über die Daten-API les- und schreibbar. Damit beantwortest du die Booking.com-, Airbnb- und anderen Unterhaltungen, die in Xentra auflaufen, auch aus einem eigenen Tool heraus.

Die Feldliste steht unter https://rest.myxentra.com/docs.

Was beim Senden gilt

• Recht „Nachrichten an Gäste“. Zum Lesen braucht der Schlüssel dort Lesen, zum Senden Lesen und schreiben; ohne dieses Recht bekommt er 403. Siehe API-Key: Rechte, Gültigkeit, Rotieren.
• Aktives Abo. Ohne aktives Abo antwortet die API mit 402; lesen geht trotzdem.
• Fertiger Text. Die API setzt keine Platzhalter ein. Enthält der Text {{…}}, lehnt sie die Nachricht mit 400 ab, statt die geschweiften Klammern an den Gast zu schicken.
• Eigener Betreff für E-Mails. Schickst du die Nachricht mit channel = email, kannst du subject mitgeben: Der Gast bekommt die E-Mail dann mit genau diesem Betreff. Erlaubt ist eine Zeile (Zeilenumbrüche werden zu Leerzeichen) mit höchstens 150 Zeichen, ohne Links und ohne {{…}}. Sonst, oder bei einem anderen Kanal, antwortet die API mit 400. Ohne subject heißt die E-Mail „Nachricht“.
• Höchstens 4000 Zeichen je Nachricht.
• Höchstens 10 Nachrichten pro Minute über die API. Darüber kommt 429; so schickt eine fehlerhafte Automation nicht Dutzende Nachrichten an echte Gäste.
• Idempotenz-Schlüssel mitschicken, damit eine wiederholte Anfrage dieselbe Nachricht nicht zweimal sendet.

Xentra stellt die Nachricht über denselben Weg zu wie eine Antwort aus dem Posteingang: über das Portal, sonst per E-Mail, SMS oder WhatsApp. Im Posteingang siehst du sie danach mit dem Hinweis, dass sie über die API kam.

Wer hat geschrieben, und kam es an?

Jede Nachricht hat zwei Felder dazu:

• origin sagt, wie sie entstanden ist: manual (jemand hat sie in Xentra geschrieben), automation, bot, api (über die API gesendet) oder inbound (vom Gast). Leer ist es bei Nachrichten, die Xentra nicht selbst gesendet, sondern nur aus deinem PMS übernommen hat, etwa eine Antwort direkt im PMS oder im Extranet.
• sent_by nennt die Person, die sie in Xentra geschrieben hat, du oder jemand aus deinem Team: { user_id, name }. Bei Automationen, dem Bot und Gastnachrichten ist es leer. sender_name ist nur die Bezeichnung, die der Kanal anzeigt, oft dein Kontoname oder „Host“.

delivery_status ist eine Quittung des Kanals. E-Mail meldet delivered oder failed, WhatsApp sent, delivered, read oder failed. Airbnb, Booking.com und die PMS-Unterhaltungen melden nichts zurück, dort bleibt das Feld leer. Steht bei einer über die API gesendeten Nachricht sent, hat der Kanal sie angenommen; ob sie beim Gast ankam, sagt nur eine Quittung.

Sofort von neuen Nachrichten erfahren

Statt /messages ständig abzufragen, abonniere den Webhook „Neue Gästenachricht“ (message_received) unter API / MCP, Reiter Webhooks.

Das Ereignis „Neue Gästenachricht“ im Webhook-Editor Er kommt bei jeder neuen Nachricht eines Gastes, auf jedem Kanal; importierte ältere Nachrichten lösen ihn nicht aus. Den Text des Gastes schickt er nur mit, wenn du im Webhook in der Gruppe Nachrichten „Nachrichtentext des Gastes“ auswählst. Siehe Webhooks: Ereignisse, Felder und Signatur und Daten-API: Limits, 403-Sperre und richtig synchronisieren.