# Messaging API collection – Migrating to v3.2 Beta 3.2 Beta

**Comprehensive guide for integrating Messaging flows from Demand API v3.1 to v3.2 Beta**

## Introduction

This guide details the changes between **v3.1 and v3.2 Beta** of the Messaging API collection. It explains what your integration must update to remain compatible, including request validation, response parsing, and new fields.

Use this guide to update your integration to the latest schema, ensure field compatibility, and prevent data parsing issues.

### Who this guide is for

Developers and integration partners participating in the early access pilot who integrate the v3.2 Beta endpoints:

- /messages/send
- /messages/latest
- /messages/latest/confirm
- /messages/conversations
- /messages/attachments/upload
- /messages/attachments/download
- /messages/attachments/metadata


## Messaging API – Breaking changes in v3.2 Beta

Messaging API v3.2-Beta introduces **non-backward-compatible changes** in request and response structures. Your integration **must** be updated to prevent request failures or parsing errors.

### Critical breaking changes

Breaking changes 3.2 Beta

| Endpoint | Change / Field | Impact / Action Required |
|  --- | --- | --- |
| **/messages/conversations** | Response: `data.conversations` → `data.conversation` | Parsing logic must be updated to read the singular `conversation` object. |
|  | Request: `accommodation` + one of `conversation` or `reservation` now required | Requests missing these fields will be rejected. Implement `oneOf` logic. |
|  | `messages[].reply_to` removed | Any code relying on message threading via `reply_to` must use `conversation.id` instead. |
|  | `messages[].sender` now a string ID referencing `participants[].id` | Update parsing to map sender from participants array. |
| **/messages/latest/confirm** | Response: `confirmedMessages` added | Optional: parse and store confirmed message IDs if needed for acknowledgement tracking. |


## Breaking changes 3.2 Beta Breaking changes

The following changes in Demand API v3.2 may require modifications to your integration. These are **not backward-compatible** and should be prioritised during migration.

| Endpoint | Change / Field | Impact / Action Required |
|  --- | --- | --- |
| **/messages/conversations** | Response: `data.conversations` → `data.conversation` | Parsing logic must be updated to read the singular `conversation` object. |
|  | Request: `accommodation` + one of `conversation` or `reservation` now required | Requests missing these fields will be rejected. Implement `oneOf` logic. |
|  | `messages[].reply_to` removed | Any code relying on message threading via `reply_to` must use `conversation.id` instead. |
|  | `messages[].sender` now a string ID referencing `participants[].id` | Update parsing to map sender from participants array. |
| **/messages/latest/confirm** | Response: `confirmedMessages` added | Optional: parse and store confirmed message IDs if needed for acknowledgement tracking. |


## Overall Messaging API migration matrix

| Endpoint | v3.1 → v3.2 / Key changes / Migration notes |
|  --- | --- |
| **/messages/conversations** | - Response changed from `data.conversations` (list) → `data.conversation` (single).
- Messages now include `attachments`;
- Request: `conversation` or `reservation` is required (`oneOf`).
- Participants metadata (`type`, `name`) unchanged.

 |
| **/messages/latest** | `message` field renamed to `id`.- `sender.metadata` structure clarified (`type` and `name`).
- Other fields largely unchanged.

 |
| **/messages/latest/confirm** | Added `confirmedMessages` array in response. |
| **/messages/send** | No changes. Fully backward-compatible. |
| **/messages/attachments/download** | New `attachment` field returned in response. |
| **/messages/attachments/metadata** | No changes. Fully backward-compatible. |
| **/messages/attachments/upload** | No changes. Fully backward-compatible. |


## Integration Tips

- Update your response parsing for `/conversations` and `/latest` to handle new `attachments` and renamed fields.
- Implement `oneOf` logic for `/conversations` request: either `conversation` or `reservation` is required.
- Optional: Use `confirmedMessages` from `/latest/confirm` for reliable acknowledgment tracking.
- Existing `/send` and `/attachments` workflows are safe to continue without changes.


See changes in detail:

## /messages/conversations

### Overview of key improvements

| Area | v3.1 | v3.2 | Migration impact |
|  --- | --- | --- | --- |
| **Tag** | `Messages` | `Conversations` | Update references if you categorise endpoints by tag. |
| **Top-level structure** | Loosely defined | Strict schema with required fields | Update JSON validation logic. |
| **Conversation model** | Mixed plural/singular naming (`conversations`) | Singular and consistent (`conversation`) | Rename in parsing logic. |
| **Message model** | Inconsistent field names (`message` vs `id`) | Unified and validated | Update field mapping. |
| **Participants structure** | Incorrect nesting | Fixed array of objects with `id` and `metadata` | Update participant parsing. |
| **Redundant fields** | `reply_to` | Removed | Remove unused mappings. |


### Request changes

| Change | v3.1 | v3.2 | Action |
|  --- | --- | --- | --- |
| **Request body required** | All fields optional (`accommodation, conversation, reservation`). | ✅ `accommodation` is required. | Always send JSON body. |
| **Required fields** | None | `accommodation` + one of (`conversation` or `reservation`) | Adjust request builder logic. |
| **Validation logic** | No enforcement | ✅ Uses `oneOf` | Ensure your client sends only one identifier type per request. |


#### Example request (v3.2)

Retrieve conversation by conversation ID:


```json
{
  "accommodation": "6819547",
  "conversation": "c3cc6522-aa63-559d-99f1-94efdd527c3c"
}
```

### Response structure overview

v3.1 response

```json
{
  "request_id": "...",
  "data": {
    "conversations": {
      "messages": [...],
      "id": "c3cc...",
      "reservation": "4338...",
      "participants": [...]
    }
  }
}
```

v3.2 response

```json
{
  "request_id": "...",
  "data": {
    "conversation": {
      "id": "c3cc...",
      "reservation": "4338...",
      "messages": [...],
      "participants": [...]
    }
  }
}
```

✅ Action: Rename the object from `data.conversations` → `data.conversation`.

### Field-level comparison

| Path (v3.1) | Path (v3.2) | Change type | Notes / Action |
|  --- | --- | --- | --- |
| `data.conversations` | `data.conversation` | ✅ Rename | Singular naming for consistency. |
| `conversation` (ID string inside `data.conversations`) | `conversation.id` | ✅ Rename and move | ID now lives within the conversation object. |
| `messages[].message` | `messages[].id` | ✅ Rename | Update ID key for each message. |
| `messages[].reply_to` | ❌ Removed | Deprecated | No replacement — remove dependency. |
| `messages[].content` | `messages[].content` | No change | Still plain text message body. |
| `messages[].sender` | `messages[].sender` | Same meaning, cleaner description | No structural change. |
| `messages[].timestamp` | `messages[].timestamp` | Same ISO-8601 format | No change, still required. |
| `participants[].participant` | `participants[].id` | ✅ Rename | Standardised naming. |
| `participants[].metadata.type` | `participants[].metadata.type` | Same values (`guest`, `property`) | Enum unchanged. |
| `participants[].metadata.name` | `participants[].metadata.name` | Clarified description | Represents participant name or property ID. |
| `data.request_id` | `request_id` (top level) | ✅ Flattened consistency | Still top-level, no rename needed. |


### Message object: Before → after

| Field | v3.1 | v3.2 | Action |
|  --- | --- | --- | --- |
| `message` | Unique message ID | → `id` | Rename field in mapping. |
| `sender` | Sender ID | ✅ No change | — |
| `reply_to` | Reply message ID | ❌ Removed | Drop from schema. |
| `content` | Message text | ✅ No change | — |
| `timestamp` | ISO-8601 format | ✅ No change | — |


### Participants object: Before → after

| Field | v3.1 | v3.2 | Action |
|  --- | --- | --- | --- |
| `participant` | Participant ID | → `id` | Rename. |
| `metadata.type` | `guest` or `property` | ✅ Same | No change. |
| `metadata.name` | Identifier string | ✅ Same, clarified | Usually the property ID. |
| `metadata` nesting | Incorrect (`properties` instead of `items`) | ✅ Fixed array structure | Adjust parsing for arrays. |


### Integration checklist

| Task | Description | Status |
|  --- | --- | --- |
| ☐ | Rename `data.conversations` → `data.conversation` |  |
| ☐ | Update `message` → `id` |  |
| ☐ | Remove `reply_to` |  |
| ☐ | Update participant parsing (`participant` → `id`) |  |
| ☐ | Add attachment support (`attachments[]`) |  |
| ☐ | Validate that request includes `accommodation` and only one of `conversation`/`reservation` |  |
| ☐ | Adjust unit tests and mock data to v3.2 examples |  |
| ☐ | Update documentation / SDK mappings |  |


## /messages/latest/

### Message object changes

| **Field** | **v3.1** | **v3.2** | **Action required** |
|  --- | --- | --- | --- |
| `reply_to` | ✅ Present (referencing previous message) | ❌ Removed | If your integration relies on message threading via `reply_to`, you’ll need to adapt to use only `conversation.id` for linking messages. |
| `conversation` | `id`, `accommodation`, `reservation` | Same | No change. |
| `content` | Message body | Same | No change. |
| `id` | Message unique ID | Same | No change, but renamed in example from `message` → `id`. |
| `sender.participant` | Participant unique ID | Same | No change. |
| `sender.metadata` | `$ref: '#/metadata'` (unspecified) | Explicit object with `type` and `name` | You must now explicitly parse `sender.metadata.type` (either `guest` or `property`) and `sender.metadata.name` (display name). |
| `attachments[]` | Array of attachment IDs | Same | No change. |
| `timestamp` | ISO-8601 timestamp | Same | No change. |


Example comparison:

v3.1 response

```json
{
  "request_id": "0248d85a-17e0-44b3-a37c-7d4b5c03f58b",
  "data": {
    "messages": [
      {
        "reply_to": "daca26da-4ce3-519d-b9eb-623eeb674800",
        "conversation": {
          "id": "b2364f9b-6466-599a-a947-0d35cff4f492",
          "reservation": "4439608993",
          "accommodation": "5589515"
        },
        "content": "Hello Pega, welcome...",
        "message": "52100000-2be9-11f0-bced-bdc849c480b6",
        "sender": {
          "participant": "930d9af8-2390-5e43-a4d7-235b52a30a14",
          "metadata": {
            "type": "property",
            "name": "CS Training Test Hotel Sloterdijk 10"
          }
        },
        "attachments": [],
        "timestamp": "2025-05-08T08:49:15.000Z"
      }
    ]
  }
}
```

v3.2 response

```json
{
  "request_id": "0248d85a-17e0-44b3-a37c-7d4b5c03f58b",
  "data": {
    "messages": [
      {
        "conversation": {
          "id": "b2364f9b-6466-599a-a947-0d35cff4f492",
          "reservation": "4439608993",
          "accommodation": "5589515"
        },
        "content": "Hello Pega, welcome...",
        "id": "52100000-2be9-11f0-bced-bdc849c480b6",
        "sender": {
          "participant": "930d9af8-2390-5e43-a4d7-235b52a30a14",
          "metadata": {
            "type": "property",
            "name": "CS Training Test Hotel Sloterdijk 10"
          }
        },
        "attachments": [],
        "timestamp": "2025-05-08T08:49:15.000Z"
      }
    ]
  }
}
```

### Summary of migration actions

| **Change** | **Required action** |
|  --- | --- |
| `reply_to` removed | Remove this field from message parsing and storage logic. |
| `sender.metadata` now explicitly typed | Update your data model to handle `type` and `name` fields. |
| `message` → `id` in example | Ensure you reference `id` instead of `message`. |
| Other fields | No change — existing parsing logic should continue to work. |


## /messages/latest/confirm

| Category | v3.1 | v3.2 | Migration notes |
|  --- | --- | --- | --- |
| **Purpose** | Confirm receipt of messages to continue receiving new messages from `/messages/latest`. | Same | No change in usage. |
| **Request body** | `messages[]` (array of message IDs) | Same | No change — request remains identical. |
| **Response** | `{ request_id }` | `{ request_id, confirmedMessages[] }` | New array `confirmedMessages` added to explicitly list confirmed message IDs. |


There are no changes in request.

### Response structure changes

v3.1 response

```json
{
  "request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f"
}
```

v3.2 response

```json
{
  "request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f",
  "confirmedMessages": [
    "8586a789-44f4-5521-9f27-f5efd097cba"
  ]
}
```

✅ Key changes:

* `confirmedMessages` array added – explicitly lists the messages that were successfully confirmed.
* `request_id` remains for support and tracing.
* No changes to request payload.


### Migration actions

| Change | Action required |
|  --- | --- |
| `confirmedMessages` added | Update parsing logic to include and optionally store `confirmedMessages` to confirm which messages were acknowledged. |
| Response `request_id` | No change, continue using as before. |
| Request body | No action needed. Existing requests remain compatible. |


## /messages/attachments endpoints

These endpoints:

- /messages/attachments/download
- /messages/attachments/metadata
- /messages/attachments/upload


### Overview

| Endpoint | v3.1 | v3.2 | Migration notes |
|  --- | --- | --- | --- |
| `/download` | Returns `request_id` and `data.file_content` | Returns `request_id`, `data.file_content`, and now includes `data.attachment` | New `attachment` field explicitly returns the attachment ID. Update parsing if you need it. |
| `/metadata` | Returns `request_id` and `data.metadata` with `file_name`, `file_size`, `file_type` | Same | No change. Fully backward-compatible. |
| `/upload` | Accepts `conversation`, `accommodation`, `file_size`, `file_name`, `file_type`, `file_content` and returns `request_id` + `data.attachment` | Same | No change. Fully backward-compatible. |


### Example - /messages/attachments/download response

v3.1 response

```json
{
  "request_id": "773e2c0d-1ab3-449b-b88a-3d6b5ce09ae7",
  "data": {
    "conversation": "8586a789-44f4-5521-9f27-f5efd097cba6",
    "file_content": "/9j/4AAQSkZJRgABAQACWAJYAAD/2wCEAAgGBgc"
  }
}
```

v3.2 response

```json
{
  "request_id": "773e2c0d-1ab3-449b-b88a-3d6b5ce09ae7",
  "data": {
    "conversation": "8586a789-44f4-5521-9f27-f5efd097cba6",
    "file_content": "/9j/4AAQSkZJRgABAQACWAJYAAD/2wCEAAgGBgc",
    "attachment": "9635be40-1dc6-11f0-8893-0130f0cdef6d" 
  }
}
```

✅ Migration action: Add parsing for `data.attachment` if needed; no breaking changes.

### Summary

* /attachments/download → new `attachment` field in response (optional, non-breaking).
* /attachments/metadata and /attachments/upload → no changes; fully backward-compatible.


All existing integrations will continue working in v3.2 without modification.

## Endpoint details

### /messages/conversations

**Key structural improvements**

* Read `sender` as string ID.
* Map `message` → `id`, and `reply_to`/`conversation` → `id`.
* Retrieve sender metadata from `participants` if needed.
* Previously `participant` (or nested id) → now `participants[].id`.


1. **Handle /messages/latest/confirm response**:


#### Example - v3.2 Beta request

1. **Tests & validation**


* Validate request body against stricter required fields.
* Use sandbox hotel and environment for testing.


## Quick migration checklist

Use this checklist to ensure your Messaging API integration is fully compatible with **v3.2-Beta**.

| Checklist |
|  --- |
| ☑ | Update all `/messages/conversations` requests to **include the `accommodation` field** (now required). |
| ☑ | Ensure requests **contain either `conversation` or `reservation`** — one is now mandatory. |
| ☑ | Replace response parsing for `messages[].sender` - it is now a **string ID** referencing `participants[].id` instead of an object. |
| ☑ | Update your message model: `id` replaces the older `message` field. |
| ☑ | Use the new `id` field instead of `reply_to` or `conversation`. |
| ☑ | Update participant structure: `participant` → `id`, and include optional metadata (`type`, `name`). |
| ☑ | Handle the new optional array `confirmedMessages` in `/messages/latest/confirm` responses. |
| ☑ | Validate requests and responses against new **required fields and stricter schema rules**. |
| ☑ | If you handle attachments, note minor schema refinements (e.g., `contentEncoding: base64`). |


## Need help?

If you have questions about your Messaging integration migration, contact your **Booking.com technical account manager**.

By following these guidelines and making the required updates, you can smoothly transition to **Demand API v3.2** and continue to provide a seamless Messaging experience for your travellers.

## What´s next

* Explore the [Messaging Try out guide](/demand/docs/messaging/try-out-messages) for a quick guide.
* Review the [Step-by step messages guide](/demand/docs/messaging/manage-messages) and use cases.
* Check the [Troubleshooting guide](/demand/docs/messaging/messaging-troubleshooting).