# Quickstart

Get an API key, find your agencies, and read your first conversation.

## 1. Get an API key

An owner or admin of your integration creates keys in the [Alia Console](https://console.alia.cx), under **API keys**. If you can't sign in to the Console, ask your Alia contact.

A key looks like `alia_live.<key id>.<secret>`. The Console shows it only once. Keep it in your server's secret store and send it only from your server.

```bash
export ALIA_API_KEY='alia_live.…'
```

## 2. Find your integration and agencies

```bash
curl https://api.alia.cx/api/v1/me \
  -H "Authorization: Bearer $ALIA_API_KEY"
```

```json
{
  "integration": {
    "id": "8f14e45f-ceea-4c6b-9a3e-2d5f1c0b7a91",
    "name": "Acme CRM"
  },
  "agencies": [
    { "id": "agy_9f2c4e1a7b3d4c5e8f60a1b2c3d4e5f6", "name": "Immo Dupont" },
    { "id": "agy_5d8e2f0a9c3b4e1d7a6f5c4b3a2e1d0c", "name": "Immo Lambert" }
  ],
  "scopes": ["conversations:read", "messages:write"]
}
```

Every other request names an agency by its `id`. For the rest of this guide, keep the base path for one agency in a variable:

```bash
AGENCY_ID=agy_9f2c4e1a7b3d4c5e8f60a1b2c3d4e5f6
export AGENCY_URL="https://api.alia.cx/api/v1/agencies/$AGENCY_ID"
```

## 3. List conversations

```bash
curl "$AGENCY_URL/conversations?pageSize=20" \
  -H "Authorization: Bearer $ALIA_API_KEY"
```

```json
{
  "conversations": [
    {
      "phoneNumber": "+32470123456",
      "contactName": "Marie Peeters",
      "lastMessageAt": "2026-09-30T08:41:12.000Z",
      "lastMessagePreview": "Is the flat on Rue Haute still available?",
      "lastMessageDirection": "inbound",
      "aiEnabled": true,
      "windowExpiresAt": "2026-10-01T08:41:12.000Z"
    }
  ],
  "nextCursor": "eyJsYXN0TWVzc2FnZUF0Ijoi…",
  "pageSize": 20
}
```

We trimmed this response. [List conversations](/docs/openapi/conversations.list) shows every field.

Each conversation is keyed by the contact's phone number, and the most recent activity comes first. When `nextCursor` is not `null`, pass it as `cursor` to get the next page.

## 4. Read messages

Put the phone number in the path in E.164 format, and write the `+` as `%2B`:

```bash
curl "$AGENCY_URL/conversations/%2B32470123456/messages" \
  -H "Authorization: Bearer $ALIA_API_KEY"
```

The newest message comes first, 50 to a page. Page through older messages with `nextCursor`, as in step 3.

## 5. Send a message

> **Warning:** This sends a real WhatsApp message. Send your first one to a phone you
> control.

```bash
curl -X POST "$AGENCY_URL/messages" \
  -H "Authorization: Bearer $ALIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+32470123456",
    "body": "Hello Marie, is Thursday at 10:00 still good for the visit?",
    "operationId": "crm-activity-8841"
  }'
```

If the contact has written to the agency in the last 24 hours, Alia sends the text at once:

```json
{
  "success": true,
  "queued": false,
  "messageId": "SMa1b2c3d4e5f60718293a4b5c6d7e8f90",
  "queueId": null,
  "status": "queued",
  "windowOpen": true,
  "windowExpiresAt": "2026-10-01T08:41:12.000Z"
}
```

If not, Alia holds the text and first asks the contact for consent. The response then has `queued: true`. [Sending messages](/docs/sending-messages) explains both cases, retries, and what a send changes in Alia.