Documentation Vacation rentals and PMS Hostaway

Rentals integration

Hostaway

Hostaway integration overview
  • CategoryRentals
  • AuthOAuth
  • Scopes1

Overview

Hostaway is a short-term-rental PMS whose unified inbox fronts Airbnb, Vrbo, Booking.com, Expedia, email, SMS and WhatsApp as one conversation per guest per reservation. Hostaway connects on /integrations in the dashboard. Click the Hostaway card and the 'Connect Hostaway' modal takes exactly two fields: Account ID (digits only) and API Key. MessageMind mints an OAuth2 client_credentials token against POST /accessTokens with scope general, waits out Hostaway's documented one-second settle before publishing the token, and uses it for both the property catalog and the guest messaging surface. The modal tells you the API Key is displayed only once; if you lose it, you must generate a new one in Hostaway Settings and Hostaway API. On a successful connect, the AI can read listings, availability and pricing, look up reservations, read conversation history and send messages across the channel each thread is on.

What MessageMind can do with it

  • Import your Hostaway listings as rows in the AI's property catalog, in paged reads capped per sync.
  • Check availability and quote pricing for a specific stay and listing.
  • Look up reservations, including stay dates, check-in and check-out times.
  • Read conversation history on a thread and send guest messages back through Hostaway on one of channel, email, SMS or WhatsApp, chosen explicitly because Hostaway does not auto-route.
  • Receive Hostaway webhooks on a per-integration URL authenticated with Basic-auth that MessageMind registered on the hook.
  • Backfill the last few conversations on connect so the AI has thread context from day one.
  • Pick up host replies typed inside the Hostaway dashboard via a short-interval echo poll, since Hostaway publishes no message-sent event.

Requirements

  • A Hostaway account with API access.
  • The Account ID (digits only) and an API Key generated in Hostaway Settings and Hostaway API. The API Key is shown only once at creation; if lost, a new one must be generated.
  • For webhook delivery, a publicly reachable base URL set by your deployment. Without it, webhooks are not registered and a warning is recorded.

How to connect

  1. In Hostaway, open Settings and then Hostaway API. Click Create and copy the Account ID shown in the popup; the API Key is shown only once at creation, so copy it straight away.
  2. In the MessageMind dashboard, open /integrations and click the Hostaway card. The 'Connect Hostaway' modal opens.
  3. Paste the Account ID (digits only) and the API Key into the two fields. The modal reminds you that your API Key is displayed only once; if you lose it, you must generate a new one.
  4. Click Integrate. A toast reads 'Connecting to Hostaway...' while MessageMind mints an OAuth2 client_credentials token against POST /accessTokens with scope general, waits for Hostaway's documented one-second settle, probes your listings and reports a precise reason for any failure.
  5. If every check passes, the toast flips to 'Hostaway connected', the minted token is cached, the API key is encrypted at rest, and a per-integration webhook URL is derived.
  6. A short backfill reads the last few conversations so the AI has thread history straight away, and once connected MessageMind imports your properties so your AI agent can answer guest questions about them.
  7. If an Account ID or API Key is rotated, repaste the fresh values in the same card to replace the stored credential and resume use.

Authentication and permissions

Mechanism
OAuth2 client_credentials against POST /accessTokens with scope general, minted from the pasted Account ID and API Key. A freshly minted token is dead for roughly one second, so MessageMind waits out the settle before publishing it.
Credentials
Exactly two fields: Account ID (wire key accountId, digits only) and API Key (wire key apiKey). Stored on your MessageMind tenant with the API key encrypted at rest; the minted access token is cached beside them.

Required scopes

  • general

Available data and actions

Reads

  • Your Hostaway listings, in paged reads capped per sync.
  • Reservations referenced in a guest thread, including embedded hints that are re-confirmed against the API before use.
  • Conversation history on a thread, for backfill and for live context on an incoming message.
  • Reviews, read on a periodic walk.

Writes

  • Guest messages sent back on a Hostaway conversation thread, with the transport (channel, email, SMS or WhatsApp) chosen explicitly per send because Hostaway does not auto-route.

AI agent use cases

  • Answer a guest message that arrived on Airbnb, Booking.com, Expedia, Vrbo, email, SMS or WhatsApp without caring which channel it came in on; Hostaway's unified inbox stitches them into one thread per guest per reservation.
  • Quote availability and pricing for a specific stay and listing.
  • Confirm a returning guest's reservation dates and check-in time.
  • Pick up a reply you typed inside Hostaway's dashboard so the AI's view of the thread stays current.

Configuration

  • Hostaway rate limits are respected process-wide: 200 requests per 10s per account and per IP, and 30 sends per minute per account. Bursts are paced, not dropped.
  • Webhook URL requirements enforced at connect: port 80 or 443, and not a private host.
  • Delivery authentication on the webhook is Basic-auth with credentials MessageMind registered on the hook.
  • A webhook delivery is answered within Hostaway's 20-second window and queued for ingest.
  • An echo poll picks up messages the host sent inside Hostaway, since Hostaway publishes no message-sent webhook.

Example workflows

Guest message to AI reply

  1. Hostaway delivers a webhook to the per-integration URL with the Basic-auth credentials MessageMind registered on the hook.
  2. The delivery is authenticated, deduped and persisted inside Hostaway's 20-second window.
  3. A drain pass ingests the delivery, enriches the thread (identity, stay snapshot), and the AI prepares a reply.
  4. The reply is sent back to Hostaway on the thread's channel, email, SMS or WhatsApp transport, chosen explicitly.

Limitations

  • A freshly minted OAuth2 token is dead for roughly one second; MessageMind handles this by waiting out the settle before publishing it.
  • Hostaway publishes no message-sent event, so host replies typed inside Hostaway arrive through the echo poll, not instantly.
  • If no public base URL is configured, webhooks are not registered and a warning is recorded.
  • Send route caps at 30 per minute per account; reads cap at 200 per 10s per account and per IP. Bursts are paced, not dropped.
  • The connect modal rejects anything other than exactly two keys (Account ID and API Key); the backend compares the count and rejects any other number.

Troubleshooting

The form says 'Account ID must contain only digits.'

The Account ID is digits only. Check Hostaway Settings and Hostaway API and open Create for your account number; paste just the digits shown in the popup.

Connect reports 'Invalid Account ID or API Key.'

Re-check your credentials in Hostaway Settings and Hostaway API. The API Key is shown only once at creation; if lost, generate a new one and repaste.

The toast reads 'Hostaway is temporarily unavailable. Your credentials were not rejected, please try again shortly.'

This is a transient 429, 502 or 503 from Hostaway. Do not re-issue the API Key; the credential was not rejected. Try again shortly.

No webhooks are being received.

Confirm the deployment has a public base URL. Verify the webhook URL is on port 80 or 443 and is not a private host. Check that Basic-auth is set to registered or strict on both sides.

A host reply typed inside Hostaway is not reflected right away.

Hostaway publishes no message-sent event. The echo poll picks these up on an interval; wait for the next tick or trigger a resync.

Disconnect and reconnect

  • On /integrations in the dashboard, open the Hostaway card and choose Disconnect. The integration document is kept but its credential is cleared so the AI stops using it.
  • To reconnect, paste a fresh Account ID and API Key in the same card. Hostaway recommends renewing keys roughly every 12 months.