airbnb Experience Messages API

openapi: 3.1.0
info:
  title: Airbnb Activities Bookings Experience 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: Experience Messages
  description: Operations for sending and retrieving messages between experience hosts and booked guests.
paths:
  /bookings/{booking_id}/messages:
    get:
      operationId: listBookingMessages
      summary: List Booking Messages
      description: Retrieves the message thread for a specific booking, including all messages exchanged between the host and guest.
      tags:
      - Experience Messages
      parameters:
      - $ref: '#/components/parameters/bookingIdParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: A paginated list of messages in the booking thread.
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExperienceMessage'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The booking was not found.
    post:
      operationId: sendBookingMessage
      summary: Send a Booking Message
      description: Sends a new message in the booking thread from the host to the guest regarding the experience booking.
      tags:
      - Experience Messages
      parameters:
      - $ref: '#/components/parameters/bookingIdParam'
      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/ExperienceMessage'
        '400':
          description: The message content is invalid or exceeds length limits.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The booking 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
    bookingIdParam:
      name: booking_id
      in: path
      required: true
      description: The unique identifier of the booking.
      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.
    ExperienceMessage:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the message.
        booking_id:
          type: string
          description: The identifier of the associated booking.
        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/