Hostaway MCP Server

openapi: 3.1.0 info: title: Hostaway Guest Communication API description: Guest communication endpoints for messaging and conversation history version: 1.0.0 contact: name: Hostaway API Support url: https://api.hostaway.com/documentation servers: - url: https://api.hostaway.com/v1 description: Hostaway Production API security: - bearerAuth: [] paths: /messages: post: operationId: sendGuestMessage summary: Send message to guest description: | Send a message to a guest associated with a booking through their preferred communication channel (email, SMS, or platform messaging). The system will automatically route the message through the appropriate channel based on guest preferences and booking source. Rate Limits: - 15 requests per 10 seconds per IP address - 20 requests per 10 seconds per account tags: - Guest Communication requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendMessageRequest' examples: emailMessage: summary: Send email to guest value: reservationId: 67890 message: "Hi John, thank you for booking with us! Here are your check-in instructions..." channel: "email" subject: "Check-in Instructions for Your Stay" smsMessage: summary: Send SMS to guest value: reservationId: 67890 message: "Your check-in code is 1234. Check-in after 3pm." channel: "sms" platformMessage: summary: Send platform message value: reservationId: 67890 message: "Looking forward to hosting you! Let me know if you need anything." channel: "airbnb" responses: '200': description: Message sent successfully content: application/json: schema: $ref: '#/components/schemas/SendMessageResponse' examples: success: value: status: "success" result: messageId: "msg_98765" reservationId: 67890 guestId: 11111 channel: "email" status: "sent" sentAt: "2025-01-10T14:30:00Z" deliveredAt: null readAt: null '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingMessage: value: status: "error" message: "Message content is required" code: "MISSING_REQUIRED_FIELD" invalidChannel: value: status: "error" message: "Invalid communication channel specified" code: "INVALID_CHANNEL" messageTooLong: value: status: "error" message: "Message exceeds maximum length of 5000 characters" code: "MESSAGE_TOO_LONG" '401': description: Unauthorized - invalid or missing access token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Reservation or guest not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: reservationNotFound: value: status: "error" message: "Reservation with ID 67890 not found" code: "RESERVATION_NOT_FOUND" guestNotFound: value: status: "error" message: "Guest contact information not available" code: "GUEST_NOT_FOUND" '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimitExceeded: value: status: "error" message: "Too many requests. Maximum 15 per 10 seconds per IP or 20 per 10 seconds per account." code: "RATE_LIMIT_EXCEEDED" retryAfter: 10 '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: deliveryFailed: value: status: "error" message: "Failed to deliver message. Please try again later." code: "DELIVERY_FAILED" /conversations: get: operationId: getConversations summary: List conversations description: | Retrieve a list of all conversations with guests, optionally filtered by reservation or date range. tags: - Guest Communication parameters: - name: limit in: query description: Maximum number of results per page schema: type: integer minimum: 1 maximum: 100 default: 50 example: 50 - name: offset in: query description: Number of results to skip for pagination schema: type: integer minimum: 0 default: 0 example: 0 - name: reservationId in: query description: Filter by specific reservation ID schema: type: integer example: 67890 - name: startDate in: query description: Filter conversations starting from this date (YYYY-MM-DD) schema: type: string format: date example: "2025-01-01" - name: endDate in: query description: Filter conversations up to this date (YYYY-MM-DD) schema: type: string format: date example: "2025-01-31" - name: unreadOnly in: query description: Show only conversations with unread messages schema: type: boolean default: false example: false responses: '200': description: Successfully retrieved conversations content: application/json: schema: $ref: '#/components/schemas/ConversationsResponse' examples: success: value: status: "success" result: - conversationId: "conv_12345" reservationId: 67890 guestId: 11111 guestName: "John Doe" listingName: "Beautiful Beachfront Villa" lastMessageAt: "2025-01-10T14:30:00Z" lastMessage: "Thank you for the check-in instructions!" unreadCount: 1 messageCount: 5 - conversationId: "conv_12346" reservationId: 67891 guestId: 11112 guestName: "Jane Smith" listingName: "Downtown Modern Apartment" lastMessageAt: "2025-01-09T10:15:00Z" lastMessage: "Looking forward to our stay!" unreadCount: 0 messageCount: 3 count: 2 limit: 50 offset: 0 '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - invalid or missing access token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /reservations/{id}/messages: get: operationId: getConversationHistory summary: Get conversation history for booking description: | Retrieve the complete message history for a specific reservation, including all messages sent to and received from the guest. Messages are returned in chronological order (oldest first). tags: - Guest Communication parameters: - name: id in: path required: true description: Unique identifier for the reservation schema: type: integer example: 67890 - name: limit in: query description: Maximum number of messages per page schema: type: integer minimum: 1 maximum: 100 default: 50 example: 50 - name: offset in: query description: Number of messages to skip for pagination schema: type: integer minimum: 0 default: 0 example: 0 responses: '200': description: Successfully retrieved conversation history content: application/json: schema: $ref: '#/components/schemas/ConversationHistoryResponse' examples: success: value: status: "success" result: conversationId: "conv_12345" reservationId: 67890 guestId: 11111 guestName: "John Doe" messages: - messageId: "msg_98761" sender: "host" senderName: "Property Manager" recipient: "guest" recipientName: "John Doe" content: "Welcome! We're excited to host you." channel: "email" sentAt: "2025-01-05T09:00:00Z" deliveredAt: "2025-01-05T09:00:15Z" readAt: "2025-01-05T10:30:00Z" status: "read" - messageId: "msg_98762" sender: "guest" senderName: "John Doe" recipient: "host" recipientName: "Property Manager" content: "Thank you! What time is check-in?" channel: "email" sentAt: "2025-01-05T11:00:00Z" deliveredAt: "2025-01-05T11:00:10Z" readAt: "2025-01-05T11:15:00Z" status: "read" - messageId: "msg_98763" sender: "host" senderName: "Property Manager" recipient: "guest" recipientName: "John Doe" content: "Check-in is after 3pm. Here are your instructions..." channel: "email" sentAt: "2025-01-05T11:30:00Z" deliveredAt: "2025-01-05T11:30:12Z" readAt: null status: "delivered" messageCount: 3 limit: 50 offset: 0 '401': description: Unauthorized - invalid or missing access token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Reservation not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: value: status: "error" message: "Reservation with ID 67890 not found" code: "RESERVATION_NOT_FOUND" '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: OAuth 2.0 access token obtained from /v1/accessTokens schemas: SendMessageRequest: type: object required: - reservationId - message properties: reservationId: type: integer description: Reservation ID to send message to example: 67890 guestId: type: integer description: Guest ID (optional - will be inferred from reservation) example: 11111 message: type: string description: Message content (max 5000 characters) maxLength: 5000 example: "Hi John, thank you for booking with us! Here are your check-in instructions..." channel: type: string enum: [email, sms, whatsapp, airbnb, vrbo, bookingCom, auto] description: | Communication channel to use. 'auto' will select the best channel based on guest preferences and booking source. default: auto example: "email" subject: type: string description: Email subject line (required for email channel) maxLength: 200 example: "Check-in Instructions for Your Stay" templateId: type: string description: Optional message template ID for pre-formatted messages example: "template_checkin_001" templateVariables: type: object description: Variables to substitute in template additionalProperties: type: string example: guestName: "John" checkInCode: "1234" propertyAddress: "123 Ocean Drive" SendMessageResponse: type: object required: - status - result properties: status: type: string enum: [success] description: Response status result: $ref: '#/components/schemas/MessageDelivery' MessageDelivery: type: object required: - messageId - reservationId - channel - status properties: messageId: type: string description: Unique message identifier example: "msg_98765" reservationId: type: integer description: Associated reservation ID example: 67890 guestId: type: integer description: Recipient guest ID example: 11111 channel: type: string enum: [email, sms, whatsapp, airbnb, vrbo, bookingCom] description: Delivery channel used example: "email" status: type: string enum: [queued, sent, delivered, failed, read] description: Current message status example: "sent" sentAt: type: string format: date-time description: Timestamp when message was sent example: "2025-01-10T14:30:00Z" deliveredAt: type: string format: date-time nullable: true description: Timestamp when message was delivered (null if not yet delivered) example: null readAt: type: string format: date-time nullable: true description: Timestamp when message was read (null if not yet read) example: null errorMessage: type: string description: Error details if delivery failed example: null ConversationsResponse: type: object required: - status - result properties: status: type: string enum: [success] description: Response status result: type: array description: Array of conversation summaries items: $ref: '#/components/schemas/ConversationSummary' count: type: integer description: Number of results returned example: 2 limit: type: integer description: Maximum results per page example: 50 offset: type: integer description: Pagination offset example: 0 ConversationSummary: type: object required: - conversationId - reservationId - guestName properties: conversationId: type: string description: Unique conversation identifier example: "conv_12345" reservationId: type: integer description: Associated reservation ID example: 67890 guestId: type: integer description: Guest identifier example: 11111 guestName: type: string description: Guest full name example: "John Doe" listingName: type: string description: Property name example: "Beautiful Beachfront Villa" lastMessageAt: type: string format: date-time description: Timestamp of most recent message example: "2025-01-10T14:30:00Z" lastMessage: type: string description: Preview of last message (truncated to 100 chars) example: "Thank you for the check-in instructions!" unreadCount: type: integer description: Number of unread messages from guest example: 1 messageCount: type: integer description: Total number of messages in conversation example: 5 ConversationHistoryResponse: type: object required: - status - result properties: status: type: string enum: [success] description: Response status result: $ref: '#/components/schemas/ConversationHistory' ConversationHistory: type: object required: - conversationId - reservationId - messages properties: conversationId: type: string description: Unique conversation identifier example: "conv_12345" reservationId: type: integer description: Associated reservation ID example: 67890 guestId: type: integer description: Guest identifier example: 11111 guestName: type: string description: Guest full name example: "John Doe" messages: type: array description: Array of messages in chronological order items: $ref: '#/components/schemas/Message' messageCount: type: integer description: Total number of messages example: 3 limit: type: integer description: Maximum messages per page example: 50 offset: type: integer description: Pagination offset example: 0 Message: type: object required: - messageId - sender - recipient - content - sentAt - status properties: messageId: type: string description: Unique message identifier example: "msg_98761" sender: type: string enum: [host, guest, system] description: Message sender type example: "host" senderName: type: string description: Sender display name example: "Property Manager" recipient: type: string enum: [host, guest] description: Message recipient type example: "guest" recipientName: type: string description: Recipient display name example: "John Doe" content: type: string description: Message content example: "Welcome! We're excited to host you." channel: type: string enum: [email, sms, whatsapp, airbnb, vrbo, bookingCom, system] description: Delivery channel example: "email" sentAt: type: string format: date-time description: Timestamp when sent example: "2025-01-05T09:00:00Z" deliveredAt: type: string format: date-time nullable: true description: Timestamp when delivered example: "2025-01-05T09:00:15Z" readAt: type: string format: date-time nullable: true description: Timestamp when read example: "2025-01-05T10:30:00Z" status: type: string enum: [queued, sent, delivered, failed, read] description: Current message status example: "read" attachments: type: array description: File attachments (if any) items: $ref: '#/components/schemas/Attachment' Attachment: type: object properties: attachmentId: type: string description: Unique attachment identifier example: "att_54321" fileName: type: string description: Original file name example: "house_manual.pdf" fileType: type: string description: MIME type example: "application/pdf" fileSize: type: integer description: File size in bytes example: 245760 url: type: string format: uri description: Download URL example: "https://cdn.hostaway.com/attachments/att_54321" ErrorResponse: type: object required: - status - message properties: status: type: string enum: [error] description: Error status indicator message: type: string description: Human-readable error message example: "Invalid access token" code: type: string description: Machine-readable error code example: "UNAUTHORIZED" retryAfter: type: integer description: Seconds to wait before retrying (rate limit errors only) example: 10 details: type: object description: Additional error context additionalProperties: true tags: - name: Guest Communication description: Guest messaging operations for sending messages and retrieving conversation history