Get a conversation

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.

GEThttps://api.alia.cx/api/v1/agencies/{agencyId}/conversations/{phone}

Path parameters

agencyIdstringRequired
Agency ID from GET /me, such as agy_9f2c4e1a7b3d4c5e8f60a1b2c3d4e5f6.
phonestringRequired
Contact phone number in E.164 format.

Query parameters

pageSizeinteger
Messages in the returned message page, from 1 to 100. Default 50.
min 1max 100default 50
cursorstring
nextCursor from a previous message page, to read older messages. Leave it out for the newest.

Responses

200OKA conversation and its newest messages.

conversationobjectRequired
A conversation with its current state.
Show 4 child fieldsHide child fields
- summaryobjectRequired
  One WhatsApp conversation with a contact.
  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.
- queuedMessagesarray of objectsRequired
  The text waiting for the window to reopen, if any. Holds at most one entry.
  Show 9 child fieldsHide child fields
  idstringRequired
  Queue entry id.
  bodystringRequired
  Text Alia will send once the contact reopens the window.
  attachmentUploadIdstring or nullRequired
  Upload id of an attached file, or null. API sends never attach files.
  attachmentFileNamestring or nullRequired
  Name of the attached file.
  attachmentMimeTypestring or nullRequired
  MIME type of the attached file.
  attachmentFileSizeinteger or nullRequired
  Size of the attached file in bytes.
  statusstringRequired
  Queue status. Always queued here.
  createdAtstringRequired
  When Alia queued the text.
  updatedAtstringRequired
  When the queued text last changed.
- aiSettingsobjectRequired
  AI state for this contact.
  Show 3 child fieldsHide child fields
  enabledbooleanRequired
  True when the AI may reply to this contact.
  disabledReasonstring or nullRequired
  Why the AI is off: manual_send (a person sent a message) or user_toggle (agency staff turned it off). After a manual_send, the AI turns back on when the contact writes more than 24 hours later.
  disabledAtstring or nullRequired
  When the AI was turned off.
- windowReopenReadinessobjectRequired
  Whether Alia can reach this contact after the 24-hour window closes, by queuing the text and sending a consent template first.
  Show 9 child fieldsHide child fields
  configuredbooleanRequired
  True when the agency has the consent flow turned on.
  templatesApprovedbooleanRequired
  True when every consent flow and template exists and is approved.
  eligibleForManualSendbooleanRequired
  True when a send outside the 24-hour window can be queued: templates are approved and at least one language exists.
  availableLanguagesarray of stringsRequired
  Languages you may pass as consentLanguage.
  defaultLanguagestring or nullRequired
  Language Alia uses by default.
  flowCodesarray of stringsRequired
  Consent flow codes for the agency.
  missingFlowCodesarray of stringsRequired
  Consent flow codes Alia could not find.
  missingTemplatesarray of stringsRequired
  Consent templates the agency lacks.
  unapprovedTemplatesarray of objectsRequired
  Consent templates waiting for WhatsApp approval.
  Show 2 child fieldsHide child fields
  templateCodestringRequired
  Template code.
  statusstring or nullRequired
  WhatsApp approval status.
messagePageobjectRequired
A page of messages, newest first.
Show 4 child fieldsHide child fields
- messagesarray of objectsRequired
  Messages, newest first.
  Show 16 child fieldsHide child fields
  idintegerRequired
  Alia message id.
  messageSidstringRequired
  Twilio message SID.
  bodystring or nullRequired
  Message text. Null for a message with only files.
  directionstringRequired
  inbound (from the contact) or outbound.
  createdAtstring or nullRequired
  When the message was sent or received.
  deliveredAtstring or nullRequired
  When WhatsApp reported delivery.
  readAtstring or nullRequired
  When WhatsApp reported the contact read it.
  statusstring or nullRequired
  Twilio message status, such as queued, sent, delivered, read, failed, undelivered or, for inbound messages, received.
  mediaarray of objects or nullRequired
  Files the contact sent. Sending files is not supported yet.
  Show 4 child fieldsHide child fields
  urlstringRequired
  Media link as WhatsApp delivered it.
  indexnumber
  Position of the file in the message.
  contentTypestring
  MIME type.
  content_typestring
  MIME type (older records).
  mediaStoredarray of objects or nullRequired
  Copies of inbound files, when the agency has media storage on.
  Show 6 child fieldsHide child fields
  sizenumberRequired
  File size in bytes.
  stored_urlstringRequired
  Link to the copy Alia keeps.
  content_typestringRequired
  MIME type.
  original_urlstringRequired
  The WhatsApp media link the copy came from.
  storage_pathstringRequired
  Path of the copy in Alia storage.
  downloaded_atstringRequired
  When Alia stored the copy.
  numMediainteger or nullRequired
  Number of files in the message.
  templateNamestring or nullRequired
  Template code, when Alia sent a template.
  buttonClickedstring or nullRequired
  Code of the button the contact tapped.
  profileNamestring or nullRequired
  WhatsApp profile name of the contact.
  interactiveContentobject
  Buttons or lists the template showed the contact.
  Show 3 child fieldsHide child fields
  quickRepliesarray of objects or null
  Reply buttons.
  Show 2 child fieldsHide child fields
  codestringRequired
  Code Alia receives when the contact taps it.
  textstringRequired
  Button label.
  listPickerobject or null
  A list of choices.
  Show 2 child fieldsHide child fields
  buttonTextstring or null
  Label of the button that opens the list.
  itemsarray of objectsRequired
  Choices in the list.
  Show 3 child fieldsHide child fields
  idstringRequired
  Item id Alia receives when the contact picks it.
  titlestringRequired
  Item label.
  descriptionstring or null
  Extra line under the label.
  ctaButtonsarray of objects or null
  Call-to-action buttons.
  Show 6 child fieldsHide child fields
  typestringRequired
  Button kind, such as URL or PHONE_NUMBER.
  titlestringRequired
  Button label.
  urlstring or null
  Link the button opens.
  phonestring or null
  Number the button calls.
  codestring or null
  Code the button copies.
  ttl_minutesnumber or null
  Minutes the code stays valid.
  replyToobject
  The message the contact replied to.
  Show 5 child fieldsHide child fields
  bodystring or nullRequired
  Text of the quoted message.
  directionstring or nullRequired
  inbound or outbound.
  createdAtstring or nullRequired
  When the quoted message was sent.
  templateNamestring or nullRequired
  Template code, when the quoted message was a template.
  hasMediaboolean or nullRequired
  True when the quoted message had files.
- nextCursorstring or nullRequired
  Pass as cursor to read older messages. Null when there are no more.
- pageSizeintegerRequired
  The page size used for this page.
- hasMorebooleanRequired
  True when older messages exist.

Errors

400Bad requestPartnerBadRequestThe request is not valid.
401UnauthorizedPartnerUnauthorizedThe bearer token is missing or not valid.
403ForbiddenPartnerForbiddenThe key may not do this.
404Not foundPartnerNotFoundNot found.
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 https://api.alia.cx/api/v1/agencies/agy_9f2c4e1a7b3d4c5e8f60a1b2c3d4e5f6/conversations/%2B32470123456 \  -H "Authorization: Bearer $ALIA_API_KEY"

Response

200

{  "conversation": {    "summary": {      "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": "eyJsYXN0TWVzc2FnZUF0IjoiMjAyNi0wMy0xNCJ9"    },    "queuedMessages": [      {        "id": "3f6c1a52-8d4e-4b7a-9c21-5e0f8a7b6d13",        "body": "Hello Marie, the visit on Thursday at 10:00 is confirmed.",        "attachmentUploadId": "5f3a9c2e-1b7d-4e8a-9c6f-2d4b8a1e7c3f",        "attachmentFileName": "Immo Dupont",        "attachmentMimeType": "value",        "attachmentFileSize": 48213,        "status": "queued",        "createdAt": "2026-09-30T08:41:12.000Z",        "updatedAt": "2026-09-30T08:41:12.000Z"      }    ],    "aiSettings": {      "enabled": true,      "disabledReason": "manual_send",      "disabledAt": "2026-09-30T08:41:12.000Z"    },    "windowReopenReadiness": {      "configured": true,      "templatesApproved": true,      "eligibleForManualSend": true,      "availableLanguages": [        "fr",        "nl"      ],      "defaultLanguage": "fr",      "flowCodes": [        "visit"      ],      "missingFlowCodes": [        "visit"      ],      "missingTemplates": [        "first_contact"      ],      "unapprovedTemplates": [        {          "templateCode": "first_contact",          "status": "pending"        }      ]    }  },  "messagePage": {    "messages": [      {        "id": 987654,        "messageSid": "SM0123456789abcdef0123456789abcdef",        "body": "Hello!",        "direction": "inbound",        "createdAt": "2026-09-30T08:41:12.000Z",        "deliveredAt": "2026-09-30T08:41:12.000Z",        "readAt": "2026-09-30T08:41:12.000Z",        "status": "delivered",        "media": [          {            "url": "https://api.twilio.com/2010-04-01/Accounts/AC123/Messages/MM123/Media/ME123",            "index": 0,            "contentType": "image/jpeg",            "content_type": "image/jpeg"          }        ],        "mediaStored": [          {            "size": 48213,            "stored_url": "https://storage.example.com/media/abc.jpg",            "content_type": "image/jpeg",            "original_url": "https://example.com/media/photo.jpg",            "storage_path": "agency-123/abc.jpg",            "downloaded_at": "2026-09-30T08:41:12.000Z"          }        ],        "numMedia": 0,        "templateName": "first_contact",        "buttonClicked": "See available times",        "profileName": "Marie",        "interactiveContent": {          "quickReplies": [            {              "code": "visit",              "text": "Yes"            }          ],          "listPicker": {            "buttonText": "See available times",            "items": [              {                "id": "5f3a9c2e-1b7d-4e8a-9c6f-2d4b8a1e7c3f",                "title": "Immo Dupont",                "description": "Pick a time that suits you."              }            ]          },          "ctaButtons": [            {              "type": "URL",              "title": "Immo Dupont",              "url": "https://example.com/media/photo.jpg",              "phone": "+32470123456",              "code": "visit",              "ttl_minutes": 1.5            }          ]        },        "replyTo": {          "body": "Hello Marie, the visit on Thursday at 10:00 is confirmed.",          "direction": "outbound",          "createdAt": "2026-09-30T08:41:12.000Z",          "templateName": "first_contact",          "hasMedia": false        }      }    ],    "nextCursor": "eyJvZmZzZXQiOjI1fQ",    "pageSize": 50,    "hasMore": false  }}

Look up conversationsPOST

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.

List messagesGET

Lists the messages in one conversation, newest first. Pass nextCursor as cursor to read older messages; stop when hasMore is false.