ARIA Developer Documentation

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, so adding a write method fails the build rather than shipping quietly.
• 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 available signal 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 another property's 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.

Request volume and limits Specification

ARIA does not poll. Calls are triggered by a guest asking something that needs live data.

• Typical volume for an active property is under 200 calls per day, spread across four capabilities, concentrated between 09:00 and 22:00.
• Availability responses are cached for under a minute, so a guest asking twice in one exchange produces one call.
• Reservation lookups are cached for the life of the conversation.
• Access tokens are generated once and reused for their full lifetime. We never generate a token per request.
• We read rate limit headers where a vendor publishes them rather than hard-coding thresholds, and we back off on 429 rather than retrying immediately.

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.

ARIA Bridge Live

This is the one machine-to-machine endpoint ARIA exposes today. It is internal to a single property's deployment: the guest-facing assistant calls its own property's instance to read live availability without ever holding PMS credentials. It is documented here because it is the boundary at which the owner's consent is enforced, and because a partner evaluating ARIA should be able to see exactly what crosses it.

Endpoint

GEThttps://<property>.erp.ariaknows.com/api/aria/availability

Authentication

A shared bearer token, configured per deployment. It is not a user session and it carries no user identity.

Authorization: Bearer <ARIA_BRIDGE_TOKEN>

Fail-closed by construction. When no token is configured the endpoint answers 503 and reads nothing. It cannot be reached before it has been deliberately set up.

Query parameters

Response

{
  "ok": true,
  "property": "Casa Exemplu",
  "stay": { "from": "2026-09-10", "to": "2026-09-12", "nights": 2 },
  "options": [
    {
      "roomType": "Camera dubla standard",
      "fitsParty": true,
      "pricePerNight": { "amount": 320, "currency": "RON" }
    }
  ]
}

An empty options array is a meaningful answer and means no room is free for every night of the stay. It is not an error, and it is not the same as ok: false, which means we could not read and therefore will not say.

Errors Live

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.

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

Integration questions, sandbox requests and connector proposals: hello@ariaknows.com.

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.