> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.kychospitality.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Legacy v1 payload

> The temporary payload version for integrations built on the older KYC API v1.

> [!WARNING]
>
> `legacy-v1` is temporary. It will be removed when KYC API v1 is retired, expected in 2027, and KYC will give you notice first.

If your system already reads guest messages from KYC API v1, KYC can set up your endpoint on the `legacy-v1` payload version.
You then receive each message in the same shape API v1 returns it, so you can switch from polling to webhooks without changing how you parse messages.

## What stays the same

Everything except the resource works exactly as described in the rest of the Webhooks guide:

* The headers and the [signature](https://api-docs.kychospitality.com/webhooks/verifying-signatures.md).
* The `{ data, meta }` envelope, and every field of `data` except `resource`. `data.apiVersion` is `legacy-v1`.
* The [receiver requirements](https://api-docs.kychospitality.com/webhooks/receiver-requirements.md) and [retries](https://api-docs.kychospitality.com/webhooks/retries.md).

Only `guestcomm.message.created` is available on `legacy-v1`.

## Example

```json theme={null}
{
  "data": {
    "object": "event",
    "id": "0193b2f0-7c1e-7a4b-9f3d-2e6c8a1b5d40",
    "type": "guestcomm.message.created",
    "apiVersion": "legacy-v1",
    "occurredAt": "2026-11-06T12:14:41.939Z",
    "propertyId": "4a2f0c10-2e7a-4b9d-9b3a-1f0c9e8d7a6b",
    "resource": {
      "object": "guestcomm.message",
      "_id": "AYq3k9TbWm2xZr7cLp0d",
      "body": "Could we get a late checkout on Sunday?",
      "created": "2026-11-06T12:14:41+00:00",
      "updated": "2026-11-06T12:14:41+00:00",
      "direction": "incoming",
      "threadId": "AYq1Fh8sQe4Vn2KjXo6u",
      "guestId": "AYp9Rm5wHc0Lt3BdZy7g",
      "type": "web-app",
      "typeId": null,
      "propertyId": "AVz4Nx2Ge8Pk6Uq1Js9a",
      "employeeId": null,
      "image": null,
      "attachment": null
    }
  },
  "meta": {
    "deliveryId": "0193b2f0-7c20-7d11-8e2a-3f4b5c6d7e8f",
    "attempt": 1,
    "timestamp": "2026-11-06T12:14:42.157Z"
  }
}
```

## Resource fields

`data.resource` is the message exactly as KYC API v1 returns it, plus `object` and `guestId`.

| Field | Description |
| - | - |
| `object` | Always `guestcomm.message`. |
| `_id` | The message ID, as in API v1. |
| `body` | The message text. |
| `created`, `updated` | When the message was created and last updated: ISO 8601 to the second, with a `+00:00` offset. |
| `direction` | `incoming` (from the guest) or `outgoing` (from the hotel). |
| `threadId` | The conversation ID, as in API v1, or `null`. |
| `guestId` | The guest's ID, as in API v1. |
| `type` | The channel, such as `sms`, `whatsapp`, `email` or `web-app`. New values are added without notice. |
| `typeId` | The messaging provider's ID for the message, or `null` when it isn't known. |
| `propertyId` | The property's API v1 ID. |
| `employeeId` | The API v1 ID of the staff member who sent the message, or `null`. |
| `image` | The message's first image, as API v1 returns it, or `null`. |
| `attachment` | The message's attachments, each with `url`, `type` and `name`, or `null` when there are none. |

> [!NOTE]
>
> There are two property IDs.
> `data.propertyId` is the property's UUID, the same in every payload version.
> `data.resource.propertyId` is its API v1 ID, which is what your existing integration uses.

## Handling the message text

Unlike the current version, a `legacy-v1` payload contains the guest's message text, and may contain links to images and attachments.
Treat every payload as guest personal data: follow the [PII guidance](https://api-docs.kychospitality.com/pii.md), store it only as long as you need it, and never log it.

## Moving to the current version

Before `legacy-v1` is removed, ask KYC to set up a second endpoint on `2026-11-01`, with its own URL.
Run both while you switch over. Both endpoints receive the same event with the same `webhook-id`, so deduplicate per endpoint, not across them.
When you're ready, KYC removes the `legacy-v1` endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.