List messages

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

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

Path parameters

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

Query parameters

pageSizeinteger
Messages per page, from 1 to 100. Default 50.
min 1max 100default 50
cursorstring
nextCursor from the previous page. Leave it out to read the newest messages.

Responses

200OKA page of messages, newest first.

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/messages \  -H "Authorization: Bearer $ALIA_API_KEY"

Response

200

{  "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}

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.

Send a messagePOST

Sends a plain-text WhatsApp message as the agency. If the 24-hour window is closed, Alia queues the text and asks the contact for consent first. A send takes over the conversation and turns the AI off for this contact.