Booking Holdings Conversations API
Provides endpoints to retrieve and manage messaging conversations. Use these endpoints to list conversations, fetch conversation details, and track updates.
OpenAPI Specification
openapi: 3.1.0
info:
title: Booking.com Demand Accommodations Conversations API
version: '3.1'
summary: "The Booking.com Demand API enables Affiliate Partners to access Booking.com's travel inventory, including accommodations, car rentals, and flights. \n\nUse Demand API to search, retrieve details, check availability, manage bookings and run reports using orders details.\n\n- RESTful API with JSON responses.\n- Make HTTPS POST requests to interact with endpoints.\n- Requires authentication using your Affiliate ID and token credentials.\n\n[Check the try out guide!](/demand/docs/getting-started/try-out-the-api)\n"
x-last-validated: '2026-06-02'
x-generated-from: documentation
description: This API collection is specific for the stay part of the connected trip. </br></br>Use these endpoints to search for stays such as hotels and apartments, check availability, retrieve reviews, and get detailed property information.
servers:
- url: https://demandapi.booking.com/3.1
description: Production environment
- url: https://demandapi-sandbox.booking.com/3.1
description: Sandbox environment
security:
- BearerAuth: []
tags:
- name: Conversations
x-displayName: Conversations
description: Provides endpoints to retrieve and manage messaging conversations. </br></br>Use these endpoints to list conversations, fetch conversation details, and track updates.
paths:
/messages/conversations:
post:
summary: Booking.com Retrieve a Conversation
description: 'Retrieves a conversation accessible to the authenticated user, including message history and participants.
'
operationId: messagesConversations
tags:
- Conversations
parameters:
- $ref: '#/components/parameters/AffiliateIdHeader'
requestBody:
required: true
content:
application/json:
schema:
title: RetrieveConversationRequest
type: object
properties:
accommodation:
type: string
description: Unique identifier of the property.
required:
- accommodation
oneOf:
- required:
- reservation
title: InputByreservation
properties:
reservation:
type: string
description: Unique identifier of the reservation.
- required:
- conversation
title: InputByconversation
properties:
conversation:
type: string
description: Unique identifier of the conversation.
examples:
InputByconversation:
summary: Retrieve conversation based on accommodation and conversation ID.
value:
accommodation: '6819547'
conversation: c3cc6522-aa63-559d-99f1-94efdd527c3c
InputByreservation:
summary: Retrieve conversation based on accommodation and reservation ID.
value:
accommodation: '6819547'
reservation: '4338284887'
responses:
'200':
description: Conversation retrieved successfully.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: Unique identifier for this request. Provide this ID when contacting support.
data:
type: object
properties:
conversation:
type: object
properties:
id:
type: string
description: Unique identifier of the conversation.
reservation:
type: string
description: Unique identifier of the reservation.
messages:
type: array
description: List of messages in the conversation.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the message.
sender:
type: string
description: Unique identifier of the sender.
reply_to:
type: string
description: Message ID this message replies to (if applicable).
content:
type: string
description: Message text content.
attachments:
type: array
items:
type: string
description: Attachment IDs included with the message.
timestamp:
type: string
format: date-time
description: Timestamp in ISO 8601 format (UTC) when the message was sent.
participants:
type: array
description: List of participants in the conversation.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the participant.
metadata:
type: object
description: Additional participant metadata.
example:
request_id: 7889a8c0-aa43-494c-863d-72d2306849c1
data:
conversation:
id: c3cc6522-aa63-559d-99f1-94efdd527c3c
reservation: '4338284887'
messages:
- id: af3d7fd0-1c50-11f0-81cd-6d243d208da3
sender: 6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f
reply_to: c3cc6522-aa63-559d-99f1-94efdd527c3c
content: Thank you for choosing Demand API Messaging Test Hotel. We are looking forward to your stay
attachments: []
timestamp: '2025-04-18T12:28:51.149Z'
participants:
- id: 5dba2525-2c49-5d2c-91cc-7195526c0c7a
metadata:
type: guest
- id: 6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f
metadata:
type: property
accommodation_id: '6819547'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
parameters:
AffiliateIdHeader:
in: header
name: X-Affiliate-Id
schema:
type: integer
required: true
description: Include here your Affiliate identifier number
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: string
x-tagGroups:
- name: Travel services
tags:
- Accommodations
- Cars
- name: Common
tags:
- Common/locations
- Common/payments
- Common/languages
- name: Orders
tags:
- Orders
- name: Messaging
tags:
- Messages
- Conversations
- Attachments