Look up conversations

Returns the conversation summary for each phone number you send, up to 100, in the same order. A number with no conversation gets conversation: null. Use it to show WhatsApp status next to a list of contacts; read messages with List messages. It only reads, so it needs conversations:read.

POSThttps://api.alia.cx/api/v1/agencies/{agencyId}/conversations/lookup

Path parameters

agencyIdstringRequired
Agency ID from GET /me, such as agy_9f2c4e1a7b3d4c5e8f60a1b2c3d4e5f6.

Request body

application/json

phoneNumbersarray of stringsRequired
Phone numbers to look up, from 1 to 100.
min items 1max items 100

Responses

200OKConversations for the phone numbers you sent.

resultsarray of objectsRequired
One result per phone number, in the order you sent them.
Show 2 child fieldsHide child fields
- phoneNumberstringRequired
  The phone number exactly as you sent it.
- conversationobject or nullRequired
  The conversation with this contact. Null when there is none.
  Show 17 child fieldsHide child fields
  phoneNumberstringRequired
  Contact phone number in E.164 format.
  contactNamestring or nullRequired
  Contact name, when known.
  lastMessageAtstring or nullRequired
  Time of the last message, in either direction.
  lastMessagePreviewstring or nullRequired
  Start of the last message text.
  lastMessageDirectionstring or nullRequired
  Direction of the last message: inbound (from the contact) or outbound.
  totalMessagesintegerRequired
  Number of messages in the conversation.
  failedMessagesintegerRequired
  Outbound messages that failed, went undelivered or carry an error code.
  activeFlowsintegerRequired
  Alia flows now running for this contact.
  completedFlowsintegerRequired
  Alia flows this contact has finished.
  latestFlowStatusstring or nullRequired
  Status of the most recently updated flow, such as active, waiting, completed, cancelled, failed or timeout.
  lastInboundAtstring or nullRequired
  Time of the last message from the contact.
  windowExpiresAtstring or nullRequired
  When the WhatsApp 24-hour window closes: 24 hours after the last message from the contact. Null when the contact has never written. After this time a send is queued, not sent.
  aiEnabledbooleanRequired
  True when the AI may reply to this contact.
  queuedMessagesintegerRequired
  Messages waiting for the contact to reopen the WhatsApp window.
  isUnlinkedbooleanRequired
  True when no agency owns this conversation.
  visibilityobjectRequired
  Why this agency can see the conversation.
  Show 3 child fieldsHide child fields
  reasonstringRequired
  Why the agency sees this conversation. focus: the agency owns it. unlinked: no agency owns it. tagged: the agency sees it through an agency tag. unknown: none of these.
  One offocusunlinkedtaggedunknown
  isSharedbooleanRequired
  True when other agencies may also see this conversation.
  isVisibleThroughAgencyTagbooleanRequired
  True when the agency sees it through an agency tag.
  cursorstring or nullRequired
  Opaque position of this row in the list. Pass it as cursor to read the rows after it. Null in lookup results.

Errors

400Bad requestPartnerBadRequestThe request is not valid.
401UnauthorizedPartnerUnauthorizedThe bearer token is missing or not valid.
403ForbiddenPartnerForbiddenThe key may not do this.
500Server errorPartnerInternalErrorAlia failed to handle the request.

Every error body is JSON with the same two fields: _tag names the error and message explains it. How errors work

Request

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

Response

200

{  "results": [    {      "phoneNumber": "+32470123456",      "conversation": {        "phoneNumber": "+32470123456",        "contactName": "Marie Peeters",        "lastMessageAt": "2026-09-30T08:41:12.000Z",        "lastMessagePreview": "Is the flat on Rue Haute still available?",        "lastMessageDirection": "inbound",        "totalMessages": 12,        "failedMessages": 0,        "activeFlows": 1,        "completedFlows": 2,        "latestFlowStatus": "completed",        "lastInboundAt": "2026-09-30T08:41:12.000Z",        "windowExpiresAt": "2026-10-01T08:41:12.000Z",        "aiEnabled": true,        "queuedMessages": 0,        "isUnlinked": false,        "visibility": {          "reason": "focus",          "isShared": false,          "isVisibleThroughAgencyTag": false        },        "cursor": null      }    },    {      "phoneNumber": "+32471987654",      "conversation": null    }  ]}

List conversationsGET

Lists the agency's WhatsApp conversations, newest last message first. Pass nextCursor as cursor to read the next page; stop when nextCursor is null.

Get a conversationGET

Returns one conversation, its AI and window state, any queued text and its newest messages. Use it to check whether a send would go out now or be queued.