ARIA Developer Documentation

ariaknows.com is the product site. This is the engineering companion to it.

ARIA is an AI front desk. It answers a business's own customers on WhatsApp and by telephone, in Romanian and English, from that business's own knowledge base and its own connected systems. This site documents how ARIA connects to a property management system, what it reads, what it will never read, and what it will never say.

Direction of integration Live

ARIA is a client, not a platform. In a PMS integration, ARIA calls the PMS. The PMS calls nothing. There is no API for a PMS vendor to implement, no SDK to embed, no webhook to build and no engineering effort required on the vendor's side.

This is deliberate. A hotel already owns credentials to its own PMS. It can grant them to a supplier it chooses, and withdraw them, without its PMS vendor becoming a party to the arrangement. The vendor keeps its contractual position and takes on no liability for what a third party does with a customer's own data.

Guest, on WhatsApp or the telephone
      |
      v
ARIA assistant            does not hold PMS credentials, and cannot
      |
      |  internal request, bearer token, read paths only
      v
The property's own ARIA instance      PMS credentials live here, and only here
      |
      |  HTTPS, allowlisted read methods
      v
The property management system

One property, one instance, one credential. There is no shared process holding several properties' PMS keys. A fault in one property's integration is invisible to every other property.

The integration contract Specification

The document a PMS vendor actually needs from an assistant vendor is not a list of endpoints it could call. It is a statement of what the assistant will do inside a customer's account. Six questions, answered in writing, and each one is a section below.

Capability set Specification

ARIA consumes capabilities, not vendor endpoints. Each PMS connector maps these to whatever that vendor calls them. A connector that can satisfy only some of them is still useful, and the assistant simply declines to answer in the areas it cannot serve.

A guest is matched to a reservation only by the telephone number they are messaging from, compared against the number stored on the reservation. If that does not resolve to exactly one active reservation, ARIA answers nothing personal and hands the conversation to staff. Zero matches and two matches are treated identically. There is no fuzzy fallback, because the failure mode of a fuzzy match is telling one guest about another guest's booking.

Read-only enforcement Live

Read-only is a property of the code, not a promise in a contract.

• Each connector declares an explicit allowlist of read methods. The request function checks the method against that set before anything is sent, and raises otherwise.
• No write method is referenced anywhere in a connector, not in a constant, not in a comment-driven branch, not behind a feature flag. There is nothing to enable.
• A unit test asserts the invariant: that the allowlist contains no write method, that the request function raises on one, that the module exposes no write function, and that no connection-test path bypasses the check. It lives with the connector, in the assistant service.
• A connector is dormant when its credentials are unset. It returns nothing rather than erroring, so an unconfigured integration cannot be reached by accident.

The practical consequence for a vendor: even a credential that is technically capable of writing, because the vendor issues one token for read and write with no scopes, cannot be used to write by this software. We still ask vendors for a least-privilege credential where one exists, as defence in depth.

Credentials and custody Live

The property owner enters the credential once, in the integrations page of their own instance. From that point:

• It is stored in that property's own database, in that property's own container, and nowhere else.
• It is never sent to the assistant process that talks to guests. That process asks the property's instance a question and receives an answer.
• It is never transmitted in a URL or a query string, only in an authorisation header, and it is never written to a log. Error paths do not echo the request or its headers.
• We do not ask for it by email and we do not need to see it.

Owner consent and revocation Live

Connecting an integration does not switch anything on for guests. Each integration carries per-consumer flags, and their defaults are deliberately asymmetric:

The owner turns the guest-facing flag on, and off, from a control in their own interface. The check is enforced at the data boundary rather than in the interface, so revoking it stops the very next message. Nothing needs to be redeployed and nobody needs to be called.

Property identity check Live

The only signal available is the property name the PMS itself returns for that credential. ARIA stores it at connect time and compares it with the identity of the business the instance belongs to. On a mismatch it refuses to serve guests, while leaving the staff assistant working, because a person reading an unexpected property name on their own screen can see what it means and a guest on WhatsApp cannot.

Two names for one property is normal, so an owner may confirm the pairing once and is believed afterwards. This is why property.identity matters in a connector even though no guest ever asks for it.

Described honestly, because a control claim should survive being read closely: this is a name-overlap heuristic, not an assertion of identity. It compares distinctive words after dropping generic ones such as hotel, casa, residence, pensiune and srl. If either name reduces to nothing distinctive, it allows rather than blocks, because refusing to serve a property on the strength of our own inability to compare two names would be the worse failure. It catches the case it was built for, a credential belonging to a visibly different property, and it is one layer among several rather than a guarantee.

Request volume and limits Specification

ARIA does not poll. Calls are triggered by a guest asking something that needs live data, so volume tracks conversations, not clock time.

• One availability question is not one upstream call. Answering it needs the room types, what is actually free across the stay, and the nightly rates, which the current connector fetches as three parallel calls. Budget accordingly: a guest question costs about three requests, not one.
• Our design budget is under 200 requests per property per day, concentrated between 09:00 and 22:00. State it as a budget rather than a measurement: only one property runs a live PMS integration today, so we have no fleet average worth quoting and will not invent one.
• There is no response cache today. Two identical questions in one conversation produce two lookups. Caching is on the list below, and we will tell you when it ships rather than describe it before.
• A circuit breaker is live: after repeated failures the connector stops calling for a cooling period and the assistant defers to a human, so a struggling PMS is not hammered. A manual connection test from the owner's screen deliberately bypasses it so they can always retry.
• Timeout is 4 seconds per request, configurable per deployment. Past it we answer nothing rather than answer late.
• Where a vendor issues expiring tokens we will generate once and reuse for the token's full lifetime, never one per request. The connector that exists today authenticates with a static key, so this is a commitment for a token-based vendor, not a description of something running.

Failure behaviour Live

Every path fails closed, to a human.

An outage means the assistant is silent. It never means the assistant is wrong.

Data we never request Specification

A connector must not implement these even where the vendor exposes them.

• Guest contact lists. Bulk exports of guest email addresses or telephone numbers. ARIA speaks only to the person who wrote first, on the number they wrote from.
• Financial state. Balances, amounts owed, payment status, folio totals. These are deferred to a human by doctrine, so there is no reason to read them.
• Other properties. Anything scoped beyond the single property that granted the credential.
• Aggregate or commercial data belonging to the vendor rather than to the property.

The boundary between the assistant and the PMS Live

The guest-facing assistant does not hold PMS credentials and cannot obtain them. It asks the property's own instance a question and receives an answer. Everything below is enforced at that boundary rather than in an interface, which is what makes the owner's switch immediate.

What the assistant never does Live

Connecting a PMS gives the assistant a source of facts that changes hourly. It does not relax any rule about what may be said. These gates are deterministic and sit in front of the language model, not after it.

• Never says how many rooms are left. That is the property's commercial information, and scarcity messaging is the property's decision to make, not ours.
• Never gives a total for a stay. Extras, local taxes and policies sit outside the rate card, so any total we produced would be wrong in a way the guest would discover at the desk.
• Never says a room is held. Nothing is reserved by a conversation.
• Never takes a booking or a payment.
• Never discusses money owed, a balance or a payment status, even when the PMS would return it.
• Never answers about a third party. A message naming another guest, another room or another reservation is declined, not looked up.
• Never invents. When the source cannot be read, the answer is that a colleague will come back.

"No" is deliberately split three ways, because they must not be said in the same words: sold out, free but nothing seats the party, and free but not priced. The last two promise a colleague.

Dates are parsed deterministically rather than by the model, because the model's failure mode is quoting a confident price for the wrong week.

Data protection posture Live

Short, and deliberately not padded. Anything we cannot state plainly is marked as absent rather than dressed up.

Not available yet Planned

Listed so that nobody builds against something that does not exist. None of the following is implemented, and none of it should be relied on in a commercial discussion.

Contact

Product, pricing and what ARIA does for a business: ariaknows.com.

Integration questions and connector proposals: hello@ariaknows.com. Security reports go to the same address with SECURITY in the subject, and we answer within one working day.

We do not operate a public sandbox. What we ask a vendor for is one test property on their side, which is where a connector gets built before it goes near a real guest.

We ask every vendor the same five things before writing a connector: a test property with credentials, who issues the credential (the property or the vendor), whether the token generation limit is per client or per source IP, whether one token may serve several properties, and whether any event push exists.