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, 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.
export ALIA_API_KEY='alia_live.…'2. Find your integration and agencies
curl https://api.alia.cx/api/v1/me \
-H "Authorization: Bearer $ALIA_API_KEY"{
"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:
AGENCY_ID=agy_9f2c4e1a7b3d4c5e8f60a1b2c3d4e5f6
export AGENCY_URL="https://api.alia.cx/api/v1/agencies/$AGENCY_ID"3. List conversations
curl "$AGENCY_URL/conversations?pageSize=20" \
-H "Authorization: Bearer $ALIA_API_KEY"{
"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 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:
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
This sends a real WhatsApp message. Send your first one to a phone you control.
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:
{
"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 explains both cases, retries, and what a send changes in Alia.