# 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 <contact@hostelmate.co> 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: <your_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: <your_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: <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. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hostelmate.co/api-documentation/conversations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.