AliaDocsSign in
Sign in

List conversations

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

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

Path parameters

  • agencyIdstringRequired

    Agency ID from GET /me, such as agy_9f2c4e1a7b3d4c5e8f60a1b2c3d4e5f6.

Query parameters

  • pageSizeinteger

    Conversations per page, from 1 to 100. Default 50.

    min 1max 100default 50

  • cursorstring

    nextCursor from the previous page. Leave it out to read the first page.

  • searchstring

    Filter by contact phone number or name, such as Marie or 0470. Three or more digits match part of a phone number; three or more letters match part of a name.

Responses

200OKA page of conversations.
  • conversationsarray of objectsRequired

    Conversations, newest last message first.

    Show 17 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 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.

  • nextCursorstring or nullRequired

    Pass as cursor to read the next page. Null when there are no more conversations.

  • pageSizeintegerRequired

    The page size used for this page.

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

Get your integration and agenciesGET

Returns the integration your API key belongs to, the agencies it may access and its scopes. Call it first: every other path needs the id of one of these agencies.

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.