Hotel PMS AI Voice Agent: Where Mews Writes Go Wrong

Last verified November 5, 2026, against these Mews Connector API pages: reservations, customers, configuration, time units, requests, environments, webhooks and the webhooks FAQ. Behaviour is scoped to the Connector API and the reservation versions each page shows. Mews can change its docs; re-check before you ship.

Your team built the phone agent inside your own hotel software. It books, changes and cancels stays for many properties. The caller hears a friendly confirmation. Then the reservation lands in the property management system with the wrong night, a duplicate guest or a surprise cancellation fee.

This post takes one system, Mews, and walks the voice-to-PMS boundary for a hotel PMS AI voice agent. It focuses on hotel PMS integration at the Mews Connector API, including Mews reservation update behaviour and Mews webhooks. Every Mews behaviour below comes from a documentation page I opened for this post. Where the docs are silent, I say so. It is not a Mews integration guide, and it does not imply Mews endorses anything here. For the general pattern, see our AI voice agent integrations pillar. For the hotel-specific symptom list, see hotel AI reservation errors.

What a hotel PMS AI voice agent actually writes

A booking call to a hotel PMS AI voice agent looks like one conversation. In the PMS it is four writes. Each can fail on its own, and a spoken error in any of them is stored silently.

1. Dates. Check-in and check-out become timestamps.

2. Guest. A name, phone and email become a customer profile, new or matched.

3. Rate and category. The caller's wish becomes a rate plan and a room category.

4. State. The reservation lands in a lifecycle state.

Mews documents seven reservation states in its reservations page (reservation version 2023-06-06). They are Inquired, Requested, Optional, Confirmed, Started, Processed and Canceled. "Confirmed" means "Confirmed by both parties, before check-in." "Optional" means the enterprise is holding the resource for the guest. A voice agent that writes Confirmed when the caller only asked for a quote has created inventory pressure from a maybe.

The diagram above is the model for the rest of the post. A hotel PMS AI voice agent can break any one of the four. Take each write in turn. Our general posts cover integration testing and post-call write-back testing. This post stays on the hotel specifics.

Dates: "this Friday" has to survive a UTC conversion

Hotel reservation date errors are the first thing to test. A voice agent time zone mistake is the usual cause.

Callers say "this Friday", "tomorrow night" or "through Sunday". The agent must turn that into timestamps. Two facts from the Mews docs shape the job.

First, the Connector API takes UTC. The reservations page shows `StartUtc` and `EndUtc` as ISO 8601 UTC strings, for example `2017-08-12T15:00:00Z` in the updateInterval request. Second, the property has its own clock. The configuration page lists `TimeZoneIdentifier` for the enterprise as an "IANA timezone identifier of the enterprise", with `Europe/Budapest` as its example.

So the agent needs the property's zone, not the server's zone and not the caller's. Then it must convert local check-in and check-out times to UTC.

Worked example (illustrative, not Mews data). A property in `America/New_York` has a 15:00 check-in and 11:00 check-out. It is Wednesday, November 11, 2026, 8:30 pm Eastern. The caller says "tomorrow night, two nights."

The offset is 5 hours because daylight saving time ended in the US on November 1, 2026. A fixed "UTC minus 4" constant would be wrong by an hour all winter. The buggy column is a one-night shift that sounds fine when read back ("Friday, two nights"). Only a check against the caller's intent catches it.

A second trap is the date-only shortcut. Sending `2026-11-13T00:00:00Z` as a start is 7:00 pm Eastern on November 12. That instant is not a hotel night boundary under any normal policy. The Mews pages I opened do not say how an off-boundary instant maps to a night. Do not guess. Run the case in the Mews demo environment and record what comes back.

Time units and offsets

The Mews time units page says bookable services are booked "in terms of integer multiples of standard `time units`." It also defines `StartOffset` and `EndOffset`. It says "A positive value for `EndOffset` is normal for a nightly stay", which means the service ends the following morning. The configuration sample shows a service with `StartTime` of `PT14H` and `EndTime` of `PT12H`, but that page does not describe those fields, so treat them as an example only.

Check-in and check-out times vary by property. The practical rule: read the service's configuration for each property. Do not hard-code 15:00 and 11:00 across your customers.

Two field names for the same time

The reservation object for version 2023-06-06 splits scheduled and actual times into `ScheduledStartUtc` and `ActualStartUtc`, and marks `StartUtc` as deprecated. Yet the add, update and updateInterval requests I read still use `StartUtc` and `EndUtc`. The docs are not uniform across operations and versions. Pin the version you call, and test the round trip: write a date, read it back, compare.

Updates: what overwrites what

Date shifts are the most common mid-call change. "Actually, make it Saturday." The Mews update docs are specific, and the defaults are the risk.

From the `reservations/update` description (Connector API, as of November 2026):

• Fields sent as `null` are ignored and do not clear the field in Mews.
• "If the `Value` within the object is sent as `null`, the field will be cleared in Mews."
• `StartUtc` and `EndUtc` are `null` "if the start time should not be updated."
• For `PersonCounts`: "If supplied, the person counts will be replaced."
• `Reprice`: if not specified, "the reservation price is updated."
• `ApplyCancellationFee`: "If not specified, the cancellation fees are applied."
• `Reason` is "Required when updating the price of the reservation."

Read that list as a set of footguns for a voice agent.

Here is a simplified Python request body for a date shift, built only from the key lines I saw in the docs' example. It is a sketch, not a full client.

# Simplified. Field names from the Mews reservations/update example.
payload = {
    "ClientToken": CLIENT_TOKEN,
    "AccessToken": ACCESS_TOKEN,
    "Client": "my-voice-agent 1.0",
    "ReservationUpdates": [{
        "ReservationId": reservation_id,
        "StartUtc": {"Value": "2026-11-13T20:00:00Z"},
        "EndUtc":   {"Value": "2026-11-15T16:00:00Z"},
    }],
    "Reprice": False,               # decide explicitly
    "ApplyCancellationFee": False,  # decide explicitly
    "Reason": "Guest changed dates by phone",
}
# POST [PlatformAddress]/api/connector/v1/reservations/update

Three things matter in that sketch. The request is a POST with JSON, and the address is case-sensitive, per the Mews requests page. The date fields use a `Value` wrapper. And the two flags are set on purpose. The docs describe what happens when you omit them, but they do not say which edits actually trigger a fee. That is a business rule you must confirm per property, so never leave it to a default.

There is also a second operation. `reservations/updateInterval` "Updates reservation interval (start, end or both)" and has a `ChargeCancellationFee` flag for "potentially canceled nights." The two operations overlap. Pick one per intent and test both paths if your agent can reach either.

For undoing a bad write, see voice agent rollback actions. A date change that repriced the stay and charged a fee is a hard one to reverse. Gate it behind confirmation. See voice agent permissions for how to scope what the agent may touch.

Guest matching: how the voice agent creates duplicates

Callers spell names aloud. "Kowalczyk" becomes "Kovalchuk". An email read over the phone has a dropped dot. The PMS then has to decide: new guest or existing guest?

The Mews `customers/add` docs describe the duplicate rule by email. If a customer with the specified email already exists, the `OverwriteExisting` flag decides. With `true`, the existing profile is overwritten and returned. With `false`, an error is returned. The docs say the flag "applies only to basic personal information" such as title, first name and last name.

Now read that with a speech error in mind. The agent mishears "kowalczyk" as "Kovalchuk" but captures the email right. With `OverwriteExisting` true, the repeat guest's profile name is replaced with the misheard spelling. With the email misheard instead, no match fires, and a second profile appears. Neither shows up in the call transcript as an error. Our post on alphanumeric capture covers read-back technique for emails and codes.

For lookups, `customers/getAll` filters by `Emails`, `FirstNames` and `LastNames`. `customers/search` is narrower than it sounds. It "Searches for customers that are active at the moment in the enterprise", which means people currently in the property. It takes a `Name` but no email or phone parameter in the docs I read. A caller asking about a future stay is not "active at the moment", so that is the wrong tool for finding them. Use `getAll` with filters for that. I did not read the Merge accounts operation; the older `customers/merge` is marked deprecated.

Design rule: match on a verified email or confirmation number, never on a spoken name alone. If only a name is available, ask for a second identifier, and treat a mismatch as "create nothing, hand off."

Rate and room category: the quote versus the write

This is where a vague wish becomes a booked rate.

The add operation takes a `RateId` and a `RequestedCategoryId`. The reservation object describes the category as "Identifier of the requested Resource category." Check the exact property name on read in the demo environment, because it may differ from the request name.

The add page says `CheckRateApplicability` and `CheckOverbooking` both default to `true`, and `SendConfirmationEmail` defaults to `true`. The overbooking check prevents a booking when there are not enough resources available. The page I read does not give a specific error code for that case. So your agent must treat any non-success as "booking not made" and never say "you're booked" before it reads the success response.

Two voice-specific risks follow. First, the caller says "the cheaper room", and the agent maps it to a category by guesswork. Second, the confirmation email goes out by default, so a wrong write also emails the guest a wrong confirmation. Our hotel AI reservation errors post lists rate-code and room-type mixups in more detail, and AI voice agent for hotels accuracy covers the booking-accuracy view.

Rate limits and webhooks

Rate limits

The Mews environments page gives the same figure for demo and production: "200 requests per AccessToken within 30 seconds." The requests page says limits use "a sliding window, not fixed time buckets," that you should expect `429 Too Many Requests`, and that Mews includes a `Retry-After` header you should use first, with exponential backoff as the fallback. The environments page also warns that limits can change without notice.

A voice agent is bursty. A property's morning peak can put several calls through the same AccessToken, each making a customer lookup, a price call and a write. See voice agent API rate limits for the capacity math. Here the point is simple. A 429 during a call means dead air or a wrong "I couldn't find you." Test it on purpose.

Webhooks

Mews webhooks are how your hotel PMS AI voice agent, or your analytics, learns that a front desk edit happened. The general webhooks page names `ServiceOrderUpdated` for "A Reservation or other Service Order was updated." Payloads carry IDs only: an `Id` and a discriminator. You call "Get all reservations" with that ID to see what changed. Three consequences for a voice team:

• You cannot tell from the event who changed what. Expect your own writes to raise update events too, since the page treats added events as a subset of updated ones. Filter them, or you may loop.
• The FAQ says the receiver should reply within 5 seconds, or the message is retried "after a few minutes." The page does not state ordering or general duplicate guarantees, so make handlers idempotent.
• `Added` events are a subset of updated events, so creating a record can fire both.

This matters for the agent's read side too. If a guest calls back after the front desk moved their room, the agent must read fresh state, not a cached copy from the last call.

How to test a hotel PMS AI voice agent

Run it against the Mews demo environment, which the docs say is for development and testing with no real data. The demo is not a mirror of every production property setup, so repeat the key cases on a staging property you control.

1. Pin your versions. Record the Connector API version and reservation version each call uses. Re-run after any doc change.

2. Build a date matrix. Cross phrasing ("this Friday", "tomorrow night", "next weekend", "through Sunday") with call times near midnight, month ends and a DST change. Assert the exact UTC instants against a reference calculator.

3. Read back from the PMS. After every write, fetch the reservation and compare nights, guest and category to the caller's stated intent, not to what the agent said.

4. Test update intent by intent. Date shift, guest-count change, room upgrade, cancel. For each, assert that `Reprice` and `ApplyCancellationFee` were set explicitly and that no fee posted unexpectedly.

5. Seed duplicates. Pre-load a guest, then call with a misheard surname and with a misheard email. Assert no overwrite and no second profile.

6. Force failures. Inject a 429 with `Retry-After`, an overbooked category and a 5-second webhook stall. Assert the agent never confirms an unwritten booking.

7. Replay with callers who vary. Accent, pace, interruptions, noise and language change what the agent hears. Re-run the matrix across them.

8. Monitor live calls. Sample production calls and compare the spoken confirmation to the stored reservation.

Evalgent can generate scenarios from your agent's prompt and flows, and run them with caller profiles that vary accent, pace, interruption, response delay, background noise and language. It evaluates from the audio, not just the transcript, so a mumbled "Friday" that the agent heard as "Thursday" shows up in the evidence. The PMS read-back assertions in steps 3 to 5 are yours to write. Evalgent tests the agent's behaviour and does not connect to Mews.

For ongoing quality, Evalgent's production monitoring takes call recordings you push, transcribes them, maps them to scenarios and judges them, flagging tool-call failures and policy failures with fix recommendations. A date mix-up still needs your reconciliation against the PMS. For the full workflow view, see voice agent workflow testing.

What to measure

Use plain counts, not a single accuracy score.

Targets here are illustrative. Set yours with each property's finance and front desk teams. With zero-tolerance metrics, one failure in a matrix run is a defect, not noise.

How this differs from the other hotel and system posts

This post is about Mews's API behaviour at the voice boundary. Hotel AI reservation errors is the symptom catalogue. AI voice agent for hotels: a QA guide is the generic QA flow. Guest request routing covers housekeeping and front desk handoffs. For another property system, read the Cloudbeds AI voice agent post, which is written separately from the Cloudbeds docs. For calendar-style date bugs in a different system, see the Google Calendar AI voice agent post.

Frequently asked questions

How does a voice agent connect to a hotel PMS?

Through the PMS's API. In Mews, the Connector API takes HTTP POST requests with JSON and three required tokens: ClientToken, AccessToken and Client. Your agent calls operations such as customer lookup, reservation add and reservation update. Webhooks tell it when something changes. Confirm each operation against the vendor's current documentation.

What happens when a voice agent changes a hotel reservation date?

In the Mews update operation, omitted pricing and fee flags have defaults: the price is updated and cancellation fees are applied if not specified. So a spoken date change can reprice the stay or charge a fee. Set both flags explicitly, and confirm the consequence with the caller before writing.

How do time zones affect a hotel reservation API?

Mews takes reservation start and end in UTC, while each property has its own IANA time zone and its own check-in and check-out times. An agent that resolves "tomorrow" with the server's clock can book the wrong night near midnight. Resolve dates in the property's zone, then convert to UTC, and handle daylight saving changes.

How do I avoid duplicate guest profiles from voice bookings?

Match on a verified identifier, not a spoken name. Mews's customers/add detects an existing customer by email and either overwrites basic personal details or returns an error, depending on OverwriteExisting. Read back emails, ask for a second identifier, and test with misheard names and emails.

Does the Mews API have rate limits?

Yes. The Mews environments page lists 200 requests per AccessToken within 30 seconds, for demo and production, using a sliding window. It warns the limits can change without notice. Handle 429 responses with the Retry-After header, and fall back to exponential backoff if the header is missing.

How do Mews webhooks work for reservation changes?

Subscribe to events such as ServiceOrderUpdated. Each message carries IDs only, so you call Get all reservations to read the change. Reply within 5 seconds, or Mews retries after a few minutes. Ordering and general duplicate guarantees are not stated on the pages I read, so make handlers idempotent.

How do I test a hotel AI voice agent before launch?

Use the PMS demo environment and a date matrix that crosses phrases with midnight, month-end and daylight saving cases. After every write, read the reservation back and compare it to the caller's intent. Seed duplicate guests, inject rate-limit and overbooking failures, and repeat across accents and noise.

Can an AI voice agent cancel a hotel reservation safely?

Only with guardrails. The docs describe cancellation-fee flags on update and interval operations, so a cancel can cost the guest money. Require identity verification, spoken confirmation of the fee outcome, and an explicit fee decision in code. Keep a handoff path to staff. This is operational guidance, not legal advice.

The bottom line

A hotel PMS AI voice agent is only as accurate as its last write, and the write turns speech into UTC timestamps, guest matches, fee flags and rate choices that fail silently. Test the dates, the update defaults and the guest match against the PMS itself, because the call transcript will not show the damage.