List the Message Threads of the Connection Scope

GET/api/v1/message-threads

Requires messages.read

One conversation per booking that has at least one message, on the Properties of the Connection Scope, latest message first and paged with next_cursor. Each gives the booking, its Property and Sales Channel, a preview of the latest message GET /bookings/{booking_id}/messages lists (a Scheduled Message not sent yet is left out) and its author, the number of unread messages and whether the conversation is closed.

The author never carries the guest email or phone: those stay under guests.read on GET /bookings. The preview is the message text as written, so it holds whatever the guest or the host typed.

Incremental sync: read every page, keep next_updated_since, and pass it as updated_since next time. A new message, a message read or unread in ZenHost, or a closed or reopened conversation brings the thread back. A thread whose latest message changes while you page through may move ahead of your cursor: the next poll returns it. Some threads may come twice: upsert them by booking_id.

Request

curl -G https://app.zenhost.com/api/v1/message-threads \
  -H "Authorization: Bearer zh_at_..." \
  -d "property_id[]=3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10" \
  -d "property_id[]=9b2e7d41-c3a8-4f65-8e1d-0a7f3c9b5e62"

const params = new URLSearchParams([
  ['property_id[]', '3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10'],
  ['property_id[]', '9b2e7d41-c3a8-4f65-8e1d-0a7f3c9b5e62'],
]);

const response = await fetch(`https://app.zenhost.com/api/v1/message-threads?${params}`, {
  headers: {
    Authorization: 'Bearer zh_at_...',
  },
});
const data = await response.json();

import requests

response = requests.get(
    "https://app.zenhost.com/api/v1/message-threads",
    params={"property_id[]": ["3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10", "9b2e7d41-c3a8-4f65-8e1d-0a7f3c9b5e62"]},
    headers={"Authorization": "Bearer zh_at_..."},
)
data = response.json()

Repeat property_id[] once per value, up to 100 per call.

Response

{
  "data": [
    {
      "booking_id": "7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7",
      "property_id": "3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10",
      "sales_channel": {
        "code": "ABB",
        "name": "string"
      },
      "latest_message": {
        "id": "7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7",
        "preview": "string",
        "author": {
          "type": null,
          "app_name": null
        },
        "created_at": "2026-10-10T08:00:00.000Z",
        "attachments_count": 1
      },
      "unread_count": 1,
      "is_closed": false,
      "updated_at": "2026-10-10T08:00:00.000Z"
    }
  ],
  "next_cursor": null,
  "next_updated_since": "2026-10-10T08:00:00.000Z"
}

{
  "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": "property_out_of_scope",
    "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

Query parameters

property_id[]string (uuid)[]
Only these Properties (repeat the parameter, at most 100). Each must be in the Connection Scope. Leave it out to list the whole Connection Scope, page by page.
at most 100 items
updated_sincestring (date-time)
Only Message Threads changed at or after this instant. Use next_updated_since of your previous listing.
cursorstring
next_cursor of the previous page.
limitinteger
Page size.
min 1 · max 500 · default 100

Responses

200One page of Message Threads.

application/jsonMessageThreadList

dataMessageThread[]required
Show 7 child attributesHide child attributes
- booking_idstring (uuid)required
  The booking of the conversation; a booking has at most one Message Thread.
- property_idstring (uuid)required
- sales_channelobjectrequired
  Where the booking was made.
  Show 2 child attributesHide child attributes
  codestringrequired
  direct, website, other, or the Sales Channel shortcode, as on GET /bookings.
  namestringrequired
- latest_messageLatestMessagerequired
  The latest message of the conversation.
  Show 5 child attributesHide child attributes
  idstring (uuid)required
  previewstringrequired
  First 200 characters of the message text.
  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.
  created_atstring (date-time)required
  attachments_countintegerrequired
  min 0
- unread_countintegerrequired
  Messages of the conversation not read in ZenHost yet.
  min 0
- is_closedbooleanrequired
  In ZenHost a conversation is closed once its latest message is read; a new guest message reopens it.
- updated_atstring (date-time)required
  Last change of the conversation: a message added, changed or removed, or its read state.
next_cursorstring | nullrequired
Pass it as cursor, with the same filters, to read the next page; null on the last page.
next_updated_sincestring (date-time)required
Once the last page is read, pass it as updated_since to receive every Message Thread changed since this listing began. Some may come again: upsert them by booking_id.

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.

422Error code: property_out_of_scope, validation_failed.

Error codes

property_out_of_scope A requested Property is outside the Connection Scope; details.property_ids lists them.
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