Conversations & Messages

Access all guest conversation threads for your property — including messages received via Email, Booking.com, Airbnb, and other OTA channels — from a single API.

---

List Conversations

Retrieve a paginated list of conversation threads for your property. Each result includes a preview of the latest message.

Endpoint

GET /api/v1/client/conversations

Feature availability: This endpoint returns 404 if the Conversations/Messaging feature is not enabled for your property. Contact [email protected] to enable it.

Query Parameters

Parameter	Type	Description
limit	integer	Number of results to return. Min 1, max 100. Default 20.
offset	integer	Number of results to skip (for pagination). Default 0.
booking_id	UUID	Optional. Filter conversations by a specific booking.
channel	string	Optional. Filter by channel: EMAIL, BOOKING_COM, AIRBNB, HOSTELWORLD, or WHATSAPP.
search	string	Optional. Search by guest name, subject, booking ID, or message content.

Example Request

curl "/api/v1/client/conversations?limit=20&offset=0&channel=BOOKING_COM" \
  -H "X-API-Key: <your_api_key>"

Example Response

{
  "pagination": {
    "total": 84,
    "limit": 20,
    "offset": 0,
    "has_more": true
  },
  "results": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "booking_id": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
      "channel": "BOOKING_COM",
      "guest_name": "John Smith",
      "subject": null,
      "is_read": false,
      "unread_count": 2,
      "status": "OPEN",
      "last_message": {
        "content": "What time is check-in?",
        "direction": "INBOUND",
        "created_at": "2025-11-04T14:22:10Z"
      },
      "created_at": "2025-10-28T09:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
pagination.total	integer	Total number of conversations matching the query.
pagination.limit	integer	The limit applied to this request.
pagination.offset	integer	The offset applied to this request.
pagination.has_more	boolean	true if there are more results beyond this page.
results[].id	UUID	Unique thread ID (use this to fetch messages).
results[].booking_id	UUID	The booking this conversation belongs to.
results[].channel	string	The channel the conversation is on.
results[].guest_name	string	Guest's name, if available.
results[].subject	string	Email subject line. null for OTA channels.
results[].is_read	boolean	false if the thread has unread messages.
results[].unread_count	integer	Number of unread messages in the thread.
results[].status	string	OPEN or ARCHIVED.
results[].last_message	object	Preview of the most recent message. null if no messages yet.
results[].created_at	string	ISO 8601 timestamp when the thread was created.

---

Get Messages in a Conversation

Retrieve the full message history for a specific conversation thread, ordered oldest to newest.

Endpoint

GET /api/v1/client/conversations/{threadId}/messages

Path Parameters

Parameter	Type	Description
threadId	UUID	The conversation thread ID, obtained from the List Conversations endpoint.

Query Parameters

Parameter	Type	Description
limit	integer	Number of messages to return. Max 100. Default 50.
offset	integer	Number of messages to skip. Default 0.

Example Request

curl "/api/v1/client/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/messages" \
  -H "X-API-Key: <your_api_key>"

Example Response

{
  "thread": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "booking_id": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
    "channel": "BOOKING_COM",
    "guest_name": "John Smith"
  },
  "pagination": {
    "total": 6,
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "results": [
    {
      "id": "f1e2d3c4-b5a6-7890-abcd-123456789abc",
      "content": "Hello, we look forward to your stay!",
      "direction": "OUTBOUND",
      "source": "MANUAL",
      "sender": "[email protected]",
      "is_read": true,
      "created_at": "2025-10-28T09:05:00Z"
    },
    {
      "id": "a9b8c7d6-e5f4-3210-abcd-fedcba987654",
      "content": "What time is check-in?",
      "direction": "INBOUND",
      "source": "GUEST",
      "sender": "guest",
      "is_read": false,
      "created_at": "2025-11-04T14:22:10Z"
    }
  ]
}

Response Fields

Field	Type	Description
thread.id	UUID	The thread ID.
thread.booking_id	UUID	The booking this thread belongs to.
thread.channel	string	The channel for this thread.
thread.guest_name	string	Guest name, if available.
results[].id	UUID	Unique message ID.
results[].content	string	The message body.
results[].direction	string	INBOUND (guest → property) or OUTBOUND (property → guest).
results[].source	string	MANUAL, AUTOMATED, GUEST, VERIFICATION, or CHECK_IN.
results[].sender	string	Sender identifier — an email address for email threads, or "guest" for OTA.
results[].is_read	boolean	Whether this message has been read in the Hostel Mate inbox.
results[].created_at	string	ISO 8601 timestamp. For OTA messages, this reflects the original timestamp from the OTA platform.

---

Pagination Example

To page through all conversations 20 at a time:

# Page 1
curl "/api/v1/client/conversations?limit=20&offset=0" -H "X-API-Key: <your_api_key>"

# Page 2
curl "/api/v1/client/conversations?limit=20&offset=20" -H "X-API-Key: <your_api_key>"

# Page 3
curl "/api/v1/client/conversations?limit=20&offset=40" -H "X-API-Key: <your_api_key>"

Continue incrementing offset by limit until has_more is false.

---

Channel Values

Value	Description
EMAIL	Direct email thread
BOOKING_COM	Booking.com messaging
AIRBNB	Airbnb messaging
WHATSAPP	WhatsApp messaging

---

Error Responses

Status	Error	Meaning
404	not_found	Thread not found or does not belong to your property.
503	messaging_unavailable	The messaging service is temporarily unavailable. Retry after a moment.