Concepts

Integrations and agencies

An integration is your CRM's account in Alia. An agency is a real estate agency that uses Alia. When an agency starts using your CRM with Alia, Alia links the agency to your integration.

Your keys can reach every agency linked to your integration. New agencies appear in GET /me as soon as they are linked. If a link ends, requests for that agency fail with 403.

Each agency has an ID, such as agy_9f2c4e1a7b3d4c5e8f60a1b2c3d4e5f6, which names it in every request. It never changes, so you can store it. Your integration also has an ID, a UUID. You don't send it, because your key already identifies the integration, but quote it when you contact Alia support.

API keys

Each key belongs to one integration. Keys have two scopes:

New keys get both scopes. Keys don't expire. When you revoke a key in the Console, requests that use it fail with 401 at once.

Create one key for each system that calls Alia. You can then revoke one key without breaking the others.

Conversations

A conversation is the WhatsApp thread between one agency and one contact. The API finds a conversation by the contact's phone number.

Send phone numbers in E.164 format, such as +32470123456. Alia also accepts Belgian local numbers (0470 12 34 56) and the 00 prefix, but E.164 avoids mistakes. In a URL path, write the + as %2B.

A conversation shows who the contact is, the last message, message counts, whether Alia's AI is on, and when the WhatsApp window closes. Get a conversation adds the AI settings, any queued message, and whether the agency can message the contact after the window closes.

Look up several contacts at once

To show WhatsApp status next to a list of contacts, send up to 100 phone numbers in one Look up conversations call, instead of one call per contact. The numbers go in the JSON body, so keep the +.

curl -X POST "https://api.alia.cx/api/v1/agencies/$AGENCY_ID/conversations/lookup" \
  -H "Authorization: Bearer $ALIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumbers": ["+32470123456", "+32471987654"] }'

{
  "results": [
    {
      "phoneNumber": "+32470123456",
      "conversation": {
        "phoneNumber": "+32470123456",
        "contactName": "Marie Peeters",
        "lastMessageAt": "2026-09-30T08:41:12.000Z",
        "windowExpiresAt": "2026-10-01T08:41:12.000Z"
      }
    },
    { "phoneNumber": "+32471987654", "conversation": null }
  ]
}

You get one result per number, in the order you sent them. Each phoneNumber is the number exactly as you sent it, so you can match results to your contacts. conversation is null when the agency has no conversation with that number. We trimmed this response: each conversation has the same fields as in List conversations.

Messages

Each message has a direction: inbound from the contact, or outbound from the agency. Outbound messages include those sent by the AI, by automated flows, by agency staff, and through the API.

status is the WhatsApp delivery status, such as sent, delivered, read, or failed. deliveredAt and readAt record when those steps happened.

Contacts can send photos and documents. media lists them as WhatsApp provided them, and mediaStored lists the copies Alia keeps when the agency stores media. The API can't send files.

The WhatsApp window

WhatsApp lets a business send free text only within 24 hours of the contact's last message. After that, the business must first send a template that WhatsApp has approved.

windowExpiresAt tells you when the current window closes. If that time has passed, or the value is null, the window is closed. Sending messages explains what Alia does with a message sent to a closed window.

The AI and your messages

Alia's AI replies to contacts for the agency, often inside a flow such as a visit booking. When you send a message through the API, Alia treats it as a person taking over. It turns the AI off for that contact and ends any flow in progress, so the AI and your CRM don't both reply.

The AI turns itself back on when the contact next writes more than 24 hours after your message. Agency staff can also turn it back on in Alia. aiEnabled on a conversation shows whether the AI is on now.