messages.anhang_lesen
Read what a guest attached to a message: a photo comes back as an image (long side 1568 px), a voice message as its transcript, a PDF as its text with page count, a video only as metadata. A scanned PDF is read by OCR on first access; if that takes longer than ~40 s the answer is empty with a `hinweis` that it is still running — ask again in a minute or two, the text is stored. Get the attachment id from the `attachments` array of `messages.listByStay` / `inbox.list_by_stay`. Only message attachments of this property — check-in ID photos are not reachable here.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
attachmentId | string | yes |
Output fields
One of 4 shapes, depending on the outcome:
Shape 1
| Field | Type | Required | Notes |
|---|---|---|---|
art | literal | yes | One of: foto |
mimeType | string | yes | |
breite | number | yes | |
hoehe | number | yes | |
nachricht | object | yes | |
nachricht.id | string | yes | |
nachricht.text | string · nullable | yes | |
nachricht.gesendetAm | string | yes | |
bild | object | yes | |
bild.data | string | yes | |
bild.mimeType | literal | yes | One of: image/jpeg |
Shape 2
| Field | Type | Required | Notes |
|---|---|---|---|
art | literal | yes | One of: sprachnachricht |
abschrift | string · nullable | yes | |
hinweis | string | no | |
nachricht | object | yes | |
nachricht.id | string | yes | |
nachricht.text | string · nullable | yes | |
nachricht.gesendetAm | string | yes |
Shape 3
| Field | Type | Required | Notes |
|---|---|---|---|
art | literal | yes | One of: dokument |
dateiname | string · nullable | yes | |
seiten | number · nullable | yes | |
text | string | yes | |
gekuerzt | boolean | yes | |
quelle | enum · nullable | yes | One of: textebene, texterkennung |
verfahren | string | no | |
hinweis | string | no | |
nachricht | object | yes | |
nachricht.id | string | yes | |
nachricht.text | string · nullable | yes | |
nachricht.gesendetAm | string | yes |
Shape 4
| Field | Type | Required | Notes |
|---|---|---|---|
art | literal | yes | One of: video |
hinweis | string | yes | |
nachricht | object | yes | |
nachricht.id | string | yes | |
nachricht.text | string · nullable | yes | |
nachricht.gesendetAm | string | yes |
messages.anrufe
Calls belonging to this stay, for the timeline in the thread. Read-only query.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
Returns array of object. Fields of each element:
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
startedAt | string | yes | |
durationSec | number · nullable | yes | |
summary | string · nullable | yes | |
outcome | string · nullable | yes | |
quelle | enum | yes | One of: bot, anlage |
richtung | number · nullable | yes | |
nummer | string · nullable | yes | |
rueckrufStatus | string · nullable | yes | |
waNummer | string · nullable | yes |
messages.antwortUebersetzen
Translates your own reply into the guest's language; nothing is sent or stored. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes | |
text | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
text | string | yes | |
ziel | string | yes |
messages.ereignisse
What happened to the booking — booking, payments, extras, cancellation, changes, online check-in, guest-portal requests — as rows for the thread. Read-only query.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
Returns array of object. Fields of each element:
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
art | enum | yes | One of: buchung, upsell_bezahlt, upsell_erstattet, zahlung, erstattung, storno, datum_geaendert, zimmer_geaendert, preis_geaendert, online_checkin, portal_wunsch, rechnung_verschickt, bewertung |
zeit | string | yes | |
betragCents | number · nullable | yes | |
waehrung | string | yes | |
angaben | object | yes | |
roh | object | no |
messages.erledigtSetzen
Mark a conversation as done (or undo that): it needs no further reply, e.g. because the guest only wrote "Danke" (thanks) or the question was settled by phone. It disappears from "Unbeantwortet" (Unanswered) (inbox, handover, `inbox.list_unanswered`) and shows no waiting time UNTIL the next message arrives, at which point it reopens by itself. In the UI: swipe left. `geaendert: false` means "was already that way", not an error. Every change is recorded in audit_log. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
conversationId | string | yes | |
erledigt | boolean | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
erledigt | boolean | yes | |
geaendert | boolean | yes |
messages.faden
Reads a message thread by conversationId, even if it is not assigned to a booking: header (channel, platform, sender name, phone number, last message, stayId if present) and all sent messages including attachments in chronological order. Drafts are not included. Any signed-in role. Read-only; a foreign or unknown id yields NOT_FOUND.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
conversationId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
kopf | object | yes | |
kopf.conversationId | string | yes | |
kopf.stayId | string · nullable | yes | |
kopf.exConversationId | string · nullable | yes | |
kopf.platform | string · nullable | yes | |
kopf.kanal | string · nullable | yes | |
kopf.name | string · nullable | yes | |
kopf.telefon | string · nullable | yes | |
kopf.lastMessageAt | string · nullable | yes | |
nachrichten | array of object | yes | |
nachrichten.id | string | yes | |
nachrichten.tenantId | string | yes | |
nachrichten.conversationId | string | yes | |
nachrichten.channel | enum | yes | One of: whatsapp, email, hospitable, voice, channex, beds24 |
nachrichten.direction | enum | yes | One of: inbound, outbound |
nachrichten.sender | string · nullable | yes | |
nachrichten.body | string · nullable | yes | |
nachrichten.languageDetected | string · nullable | yes | |
nachrichten.aiLayer | enum · nullable | yes | One of: rule, llm, manual, escalated, auto_received |
nachrichten.aiConfidence | string · nullable | yes | Decimal as string — numeric column, not an IEEE-754 double |
nachrichten.aiReplyToMessageId | string · nullable | yes | |
nachrichten.attachmentUrl | string · nullable | yes | |
nachrichten.attachmentKind | enum · nullable | yes | One of: audio, image, file |
nachrichten.externalMessageId | string · nullable | yes | |
nachrichten.sentReferenceId | string · nullable | yes | |
nachrichten.externalThreadRefs | array of string · nullable | yes | |
nachrichten.subject | string · nullable | yes | |
nachrichten.bodyHtml | string · nullable | yes | |
nachrichten.state | enum | yes | One of: draft, sent |
nachrichten.sentAt | string | yes | |
nachrichten.providerName | string · nullable | yes | |
nachrichten.providerSource | string · nullable | yes | |
nachrichten.deliveryStatus | enum | yes | One of: queued, sent, beobachtet, provider_acked, delivered, read, failed, sync_unknown |
nachrichten.lastReconciledAt | string · nullable | yes | |
nachrichten.invoiceRequested | boolean | yes | |
nachrichten.attachments | array of object | yes | |
nachrichten.reaktion | string · nullable | no | |
nachrichten.reaktionAt | string · nullable | no | |
nachrichten.antwortAufWamid | string · nullable | no | |
nachrichten.antwortAufText | string · nullable | no | |
nachrichten.sprache | string · nullable | no | |
nachrichten.automatisch | boolean | no | |
nachrichten.regelName | string · nullable | no | |
nachrichten.restOffen | array of string · nullable | no | |
nachrichten.kiUrteil | object | no |
messages.fadenAntworten
Replies to a thread WITHOUT a booking, via WhatsApp. Optional `antwortAufId` (a WhatsApp message of this thread): the reply then goes out as a quote; otherwise `antwort_ziel_ungueltig` is returned and nothing is sent. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
conversationId | string | yes | |
body | string | yes | |
antwortAufId | string | no | |
bild | object | no | |
bild.base64 | string | yes | |
bild.name | string | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
messageId | string | yes | |
externalMessageId | string · nullable | yes |
messages.fadenVorschlag
Which booking does this unassigned thread belong to? A suggestion, not an action. Read-only query.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
conversationId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string · nullable | yes | |
guestName | string · nullable | yes | |
room | string · nullable | yes | |
checkIn | string · nullable | yes | |
grund | string · nullable | yes |
messages.fadenZuordnen
Attaches the unassigned thread to a booking: the visible click that follows the suggestion. Sets ONLY `conversations.stay_id`. Messages stay where they are; the booking page now reads all threads of a stay and labels them by channel, so the WhatsApp history appears alongside the channel's history instead of replacing it. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
conversationId | string | yes | |
stayId | string · nullable | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
messages.kanalVorschau
Via which channel a reply would go out right now, shown at the reply field. Same choice as when sending (`ermittleKanal`); creates nothing. Read-only query.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
The whole object may be null.
| Field | Type | Required | Notes |
|---|---|---|---|
kanal | enum | yes | One of: whatsapp, email, hospitable, voice, channex, beds24 |
plattform | string · nullable | yes | |
waFensterZu | boolean | yes | |
fehlt | enum · nullable | yes | One of: email, telefon |
messages.kiUrteil
The team's verdict on an AI reply: "good" or "bad", for "bad" optionally a short reason (at most 200 characters). A new verdict replaces the old one. The verdicts feed the evaluation of which replies the AI may send on its own in future. NOT_FOUND if the message is not an AI reply of this property. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
messageId | string | yes | |
urteil | enum | yes | One of: gut, schlecht |
grund | string | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
messages.listByStay
List all messages for a single stay's conversation thread.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
Returns array of object. Fields of each element:
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
tenantId | string | yes | |
conversationId | string | yes | |
channel | enum | yes | One of: whatsapp, email, hospitable, voice, channex, beds24 |
direction | enum | yes | One of: inbound, outbound |
sender | string · nullable | yes | |
body | string · nullable | yes | |
languageDetected | string · nullable | yes | |
aiLayer | enum · nullable | yes | One of: rule, llm, manual, escalated, auto_received |
aiConfidence | string · nullable | yes | Decimal as string — numeric column, not an IEEE-754 double |
aiReplyToMessageId | string · nullable | yes | |
attachmentUrl | string · nullable | yes | |
attachmentKind | enum · nullable | yes | One of: audio, image, file |
externalMessageId | string · nullable | yes | |
sentReferenceId | string · nullable | yes | |
externalThreadRefs | array of string · nullable | yes | |
subject | string · nullable | yes | |
bodyHtml | string · nullable | yes | |
state | enum | yes | One of: draft, sent |
sentAt | string | yes | |
providerName | string · nullable | yes | |
providerSource | string · nullable | yes | |
deliveryStatus | enum | yes | One of: queued, sent, beobachtet, provider_acked, delivered, read, failed, sync_unknown |
lastReconciledAt | string · nullable | yes | |
invoiceRequested | boolean | yes | |
attachments | array of object | yes | |
attachments.id | string | yes | |
attachments.messageId | string | yes | |
attachments.kind | enum | yes | One of: photo, audio, video, document |
attachments.url | string | yes | |
attachments.mimeType | string · nullable | yes | |
attachments.sizeBytes | integer · nullable | yes | |
attachments.seiten | integer · nullable | no | |
attachments.textInhalt | string · nullable | no | |
attachments.textQuelle | enum · nullable | no | One of: textebene, texterkennung |
reaktion | string · nullable | no | |
reaktionAt | string · nullable | no | |
antwortAufWamid | string · nullable | no | |
antwortAufText | string · nullable | no | |
sprache | string · nullable | no | |
automatisch | boolean | no | |
regelName | string · nullable | no | |
restOffen | array of string · nullable | no | |
kiUrteil | object | no | |
kiUrteil.urteil | enum · nullable | yes | One of: gut, schlecht |
kiUrteil.grund | string · nullable | yes |
messages.listConversations
List guest message conversations (inbox threads).
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
filter | enum | no | One of: all, unanswered, alarme, vorschlaege — Default: "all" |
kanal | array of enum | no | |
aufenthalt | enum | no | One of: anreisend, im_haus, abgereist |
anreiseVon | string | no | |
anreiseBis | string | no | |
sprache | array of string | no | |
status | array of enum | no | |
search | string | no | |
limit | integer | no | Default: 25 |
cursor | string | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
items | array of object | yes | |
items.conversationId | string | yes | |
items.stayId | string · nullable | yes | |
items.exConversationId | string · nullable | yes | |
items.externalRef | string · nullable | yes | |
items.guestName | string | yes | |
items.channel | enum | yes | One of: whatsapp, email, hospitable, voice, channex, beds24 |
items.lastBody | string · nullable | yes | |
items.lastAt | string | yes | |
items.lastDirection | enum | yes | One of: inbound, outbound |
items.lastDeliveryStatus | string · nullable | no | |
items.needsReply | boolean | yes | |
items.wartetMinuten | integer · nullable | no | |
items.erledigt | boolean | no | |
items.ungelesen | boolean | no | |
items.kiVorschlag | boolean | no | |
items.kiVorschlagPruefen | boolean | no | |
items.room | string · nullable | yes | |
items.stayStatus | string · nullable | yes | |
items.platform | string · nullable | yes | |
items.isInquiry | boolean | yes | |
items.hatAnruf | boolean | yes | |
items.verlangtRueckruf | boolean | yes | |
items.kanaele | array of string | no | |
items.einordnung | object · nullable | yes | |
nextCursor | string · nullable | yes |
messages.listUnconfirmed
outbound sends whose delivery is not yet confirmed. Surfaces the "Bestätigung fehlt" UI section. Cutoff is 30 minutes: fresh sends (<30min) are noisy because Postmark webhooks haven't had time to fire. Beyond that, anything still in sent / provider_acked / sync_unknown deserves operator attention. Read-only query.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
limit | integer | no | Default: 100 |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
items | array of object | yes | |
items.messageId | string | yes | |
items.conversationId | string | yes | |
items.channel | enum | yes | One of: whatsapp, email, hospitable, voice, channex, beds24 |
items.providerName | string · nullable | yes | |
items.deliveryStatus | enum | yes | One of: queued, sent, beobachtet, provider_acked, delivered, read, failed, sync_unknown |
items.subject | string · nullable | yes | |
items.body | string · nullable | yes | |
items.externalMessageId | string · nullable | yes | |
items.sentAt | string | yes | |
items.lastReconciledAt | string · nullable | yes | |
count | integer | yes | |
notCheckableCount | integer | yes | |
notCheckableProviders | array of string | yes |
messages.markDelivered
Operator marks a previously-unconfirmed message as verified-delivered. Used after the operator visually checked the provider's dashboard and confirmed the guest got it. Removes the row from "Bestätigung fehlt" without triggering a resend. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
messageId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
messages.offeneKiVorschlaegeAnzahl
How many conversations have an open AI suggestion (draft awaiting approval): the counter for "Heute" (Today). Same rule as the badge and the "Vorschläge" (Suggestions) filter in the inbox, scoped to the tenant. Read-only query.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
anzahl | integer | yes |
messages.send
Send a message to the guest on a reservation's conversation thread. This contacts the guest for real over the booking channel (Airbnb/Booking/email/WhatsApp). Optional `antwortAufId` (id of a WhatsApp message in this reservation's thread) sends it as a quoted reply when the message goes out over WhatsApp; otherwise rejected with `antwort_ziel_ungueltig` and nothing is sent. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes | |
body | string | yes | |
bild | object | no | |
bild.base64 | string | yes | |
bild.name | string | no | |
antwortAufId | string | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
messageId | string | yes |
messages.uebersetzen
Translates a guest message into German, once, then stored. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
messageId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
text | string | yes | |
quelle | string · nullable | yes |
messages.uebersetzungAktiv
Is a translation service set up? Without one, the UI shows no buttons. Read-only query.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
aktiv | boolean | yes |
messages.ungelesenSetzen
Mark a conversation as unread (or back as read): its row in the inbox then appears in bold with a dot until someone opens the thread. The target is EXACTLY ONE of `conversationId` (one conversation) or `stayId` (all conversations of the booking, which is how the UI reports opening it). Per conversation, not per user. `geaendert` = number of conversations whose state changed; every change is recorded in audit_log. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
conversationId | string | no | |
stayId | string | no | |
ungelesen | boolean | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ungelesen | boolean | yes | |
geaendert | integer | yes |
messages.whatsappVorlagen
WhatsApp templates of this stay for the thread: display only, alongside the messages, like the calls. Deliberately NOT `messages` rows, otherwise later rule messages would inherit WhatsApp as their channel. The text carries the codes, so it is available to operations roles only, like the queue. Read-only query.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
Returns array of object. Fields of each element:
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
createdAt | string | yes | |
raum | string | yes | |
vorlage | string | yes | |
text | string · nullable | yes | |
status | string | yes | |
grund | string · nullable | yes | |
zustellung | string · nullable | yes | |
zustellFehler | string · nullable | yes | |
reaktion | string · nullable | yes | |
aktuelleNummer | string · nullable | yes | |
nachschickbar | boolean | yes |