openapi: 3.1.0
info:
  title: Airbnb Activities Bookings Messages API
  description: The Airbnb Activities API allows approved partners to integrate with Airbnb Experiences, the platform's marketplace for hosted activities and tours. It provides endpoints for managing experience listings, handling bookings, and synchronizing availability for activities offered by local hosts. Partners can use the API to build integrations that help experience hosts manage their offerings alongside other tour and activity platforms, enabling centralized management of schedules, pricing, and guest communications.
  version: 2025.03.31
  contact:
    name: Airbnb Developer Support
    url: https://developer.withairbnb.com/
  termsOfService: https://www.airbnb.com/terms
servers:
- url: https://api.airbnb.com/v2
  description: Airbnb Production API Server
security:
- oauth2: []
tags:
- name: Messages
  description: Operations for sending and retrieving guest and host messages within reservation threads.
paths:
  /reservations/{reservation_id}/messages:
    get:
      operationId: listReservationMessages
      summary: List Reservation Messages
      description: Retrieves the message thread for a specific reservation, including all messages exchanged between the host and guest.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: A paginated list of messages in the reservation thread.
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
    post:
      operationId: sendReservationMessage
      summary: Send a Reservation Message
      description: Sends a new message in the reservation thread from the host to the guest. Messages are delivered through the Airbnb messaging system.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
                  description: The text content of the message to send.
                  maxLength: 5000
      responses:
        '201':
          description: The message was successfully sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: The message content is invalid or exceeds length limits.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
components:
  parameters:
    limitParam:
      name: limit
      in: query
      description: The maximum number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    offsetParam:
      name: offset
      in: query
      description: The number of results to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    reservationIdParam:
      name: reservation_id
      in: path
      required: true
      description: The unique identifier of the reservation.
      schema:
        type: string
  schemas:
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: The total number of results available.
        limit:
          type: integer
          description: The number of results returned per page.
        offset:
          type: integer
          description: The current offset in the result set.
        has_more:
          type: boolean
          description: Whether more results are available beyond this page.
    Message:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the message.
        reservation_id:
          type: string
          description: The identifier of the associated reservation.
        sender_type:
          type: string
          description: Whether the message was sent by the host or guest.
          enum:
          - host
          - guest
        message:
          type: string
          description: The text content of the message.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the message was sent.
  securitySchemes:
    oauth2:
      type: oauth2
      description: Airbnb uses OAuth 2.0 for authentication. Partners must register their application to receive a client ID and secret, then obtain access tokens through the authorization code flow.
      flows:
        authorizationCode:
          authorizationUrl: https://www.airbnb.com/oauth2/auth
          tokenUrl: https://api.airbnb.com/v2/oauth2/authorizations
          scopes:
            experiences:read: Read experience information
            experiences:write: Create and update experiences
            bookings:read: Read booking information
            bookings:write: Confirm and cancel bookings
            messages:read: Read booking messages
            messages:write: Send messages to guests
externalDocs:
  description: Airbnb Developer Documentation
  url: https://developer.withairbnb.com/