List the messages of a booking

GET/api/v1/bookings/{booking_id}/messages

Requires messages.read

The conversation of a booking with its guest, oldest message first and paged with next_cursor. Each message gives its direction, its author (the guest, the host or a team member, Zenny, an automation or an App, named), its channel, its text, its attachments and its delivery status.

A booking without any message answers an empty list. Scheduled Messages not sent yet are not listed. The author never carries the guest email or phone, nor the name of the team member: those stay out of reach, and the guest contact details stay under guests.read on GET /bookings. The text is the message as written, so it holds whatever the guest or the host typed.

Download an attachment from its url, with the access token of the App Connection. A booking outside the Connection Scope answers not_found, exactly like a missing one.

Request

curl https://app.zenhost.com/api/v1/bookings/7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7/messages \
  -H "Authorization: Bearer zh_at_..."

const response = await fetch('https://app.zenhost.com/api/v1/bookings/7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7/messages', {
  headers: {
    Authorization: 'Bearer zh_at_...',
  },
});
const data = await response.json();

import requests

response = requests.get(
    "https://app.zenhost.com/api/v1/bookings/7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7/messages",
    headers={"Authorization": "Bearer zh_at_..."},
)
data = response.json()

Response

{
  "data": [
    {
      "id": "7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7",
      "direction": "inbound",
      "author": {
        "type": "guest",
        "app_name": "string"
      },
      "channel": "platform",
      "text": "Hello Camille, your apartment is ready from 4 pm.",
      "subject": "string",
      "attachments": [
        {
          "index": 1,
          "type": "image",
          "file_name": "string",
          "content_type": "string",
          "url": "string"
        }
      ],
      "delivery_status": "received",
      "sent_at": "2026-10-10T08:00:00.000Z",
      "created_at": "2026-10-10T08:00:00.000Z"
    }
  ],
  "next_cursor": null
}

{
  "error": {
    "code": "unauthorized",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "subscription_blocked",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "app_suspended",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "A human-readable explanation",
    "details": {}
  }
}

Parameters

Path parameters

booking_idstring (uuid)required
Booking id.

Query parameters

cursorstring
next_cursor of the previous page.
limitinteger
Page size.
min 1 · max 500 · default 100

Responses

200One page of the messages of the booking.

application/jsonMessageList

dataMessage[]required
Show 10 child attributesHide child attributes
- idstring (uuid)required
- directionstringrequired
  inbound from the guest, outbound to the guest.
  One of: inbound outbound
- authorMessageAuthorrequired
  Who wrote the message. Never carries a guest email or phone, nor the name of the team member.
  Show 2 child attributesHide child attributes
  typestringrequired
  guest (inbound), host (the host or a team member), zenny (written by Zenny, the ZenHost assistant), automation (a Scheduled Message) or app (an App, see app_name). Version 1 may add values.
  One of: guest host zenny automation app
  app_namestring
  Name of the App that sent the message, when type is app.
- channelstringrequired
  platform is the messaging of the Sales Channel of the booking (Airbnb, Booking.com…). Version 1 may add values.
  One of: platform email sms
- textstringrequired
- subjectstring | nullrequired
  Email subject.
- attachmentsMessageAttachment[]required
  Show 5 child attributesHide child attributes
  indexintegerrequired
  Position of the file in the message, as in the download URL. Files that cannot be downloaded are left out, so indexes may skip.
  min 0
  typestringrequired
  Only images in version 1; other types may be added.
  One of: image
  file_namestring | nullrequired
  content_typestring | nullrequired
  MIME type when known; the download answers with the actual one.
  urlstring (uri)required
  Download URL of the file. Call it with the access token of the App Connection, like any other endpoint.
- delivery_statusstringrequired
  received for an inbound message. For an outbound one: pending while it is not confirmed sent (in flight, or its fate is not known yet), sent, or rejected when it did not reach the guest: the Sales Channel refused it, or its send failed or stayed unconfirmed for a minute, as the ZenHost inbox shows it. Version 1 may add values.
  One of: received pending sent rejected
- sent_atstring (date-time)required
- created_atstring (date-time)required
  When ZenHost recorded the message; the list is sorted on it.
next_cursorstring | nullrequired
Pass it as cursor to read the next page; null on the last page.

401Error code: unauthorized, connection_revoked.

Error codes

unauthorized The access token is missing, unknown, expired or revoked, or was issued before the account connected the App again. Refresh it; if refreshing fails, ask the owner to connect again.
connection_revoked The owner revoked the App Connection (or your App revoked its own refresh token). Stop calling for this account and drop its tokens.

402Error code: subscription_blocked.

Error codes

subscription_blocked The ZenHost subscription of the account is blocked (unpaid, cancelled…). The connection is kept: tell your customer, calls work again once the subscription is restored.

403Error code: app_suspended, forbidden_permission.

Error codes

app_suspended ZenHost suspended your App, or no longer allows it on this account. Stop calling and contact ZenHost.
forbidden_permission Your App was not granted the Permission this endpoint requires.

404Error code: not_found.

Error codes

not_found The resource does not exist or is outside the Connection Scope (both look the same), or the path is not an endpoint of /api/v1.

422Error code: validation_failed.

Error codes

validation_failed The query, headers or body are invalid; details.issues points at each problem (path, message, and maximum when a value or list is too big).

429Error code: rate_limited.

Header Retry-After — Seconds to wait before the next call is allowed. Limits per App Connection: 60 reads (GET), 10 writes (other POST) and 30 messages sent to guests per minute.

Error codes

rate_limited Too many calls on this App Connection. Wait for the number of seconds in Retry-After.

500Error code: internal_error.

Error codes

internal_error ZenHost failed to answer. Retry later with a back-off.

Every error code and what to do