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:

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

Response structure overview

{
  "request_id": "...",
  "data": {
    "conversations": {
      "messages": [...],
      "id": "c3cc...",
      "reservation": "4338...",
      "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:

{
  "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"
      }
    ]
  }
}

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

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

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

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

✅ 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.

Handle /messages/latest/confirm response:

Example - v3.2 Beta request

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 for a quick guide.
Review the Step-by step messages guide and use cases.
Check the Troubleshooting guide.

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

Introduction

Who this guide is for

Messaging API – Breaking changes in v3.2 Beta

Critical breaking changes

Breaking changes 3.2 Beta Breaking changes

Overall Messaging API migration matrix

Integration Tips

/messages/conversations

Overview of key improvements

Request changes

Example request (v3.2)

Response structure overview

Field-level comparison

Message object: Before → after

Participants object: Before → after

Integration checklist

/messages/latest/

Message object changes

Summary of migration actions

/messages/latest/confirm

Response structure changes

Migration actions

/messages/attachments endpoints

Overview

Example - /messages/attachments/download response

Summary

Endpoint details

/messages/conversations

Example - v3.2 Beta request

Quick migration checklist

Need help?

What´s next

Was this helpful?