> For the complete documentation index, see [llms.txt](https://docs.hostelmate.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostelmate.co/api-documentation/conversations.md). # 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 ```http GET /api/v1/client/conversations ``` > **Feature availability**: This endpoint returns `404` if the Conversations/Messaging feature is not enabled for your property. Contact 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 ```bash curl "/api/v1/client/conversations?limit=20&offset=0&channel=BOOKING_COM" \ -H "X-API-Key: " ``` #### Example Response ```json { "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 ```http GET /api/v1/client/conversations/{threadId}/messages ``` #### Path Parameters | Parameter | Type | Description | | ---------- | ---- | ------------------------------------------------------------------------------------------------- | | `threadId` | UUID | The conversation thread ID, obtained from the [List Conversations](#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 ```bash curl "/api/v1/client/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/messages" \ -H "X-API-Key: " ``` #### Example Response ```json { "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": "hostel@example.com", "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: ```bash # Page 1 curl "/api/v1/client/conversations?limit=20&offset=0" -H "X-API-Key: " # Page 2 curl "/api/v1/client/conversations?limit=20&offset=20" -H "X-API-Key: " # Page 3 curl "/api/v1/client/conversations?limit=20&offset=40" -H "X-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. |