WIwithallo
Conversations

List conversations

Changed on

Returns a paginated list of conversations grouped by contact phone number, sorted by most recent activity. Listing by inbox_id or with pinned can return 400 FEATURE_NOT_SUPPORTED (with param naming which one), 400 CONTACT_FILTER_NOT_SUPPORTED when the inbox has saved contact filters on a workspace still on the old contact model, or 422 CONTACT_FILTER_TOO_LARGE (type validation_error) when its contact filters resolve to too many numbers or hold more than 50 IDs. Right after an inbox is created, INBOX_NOT_FOUND can be transient and carries retryable: true: retry once.

get/v2/api/conversations

Request

  • Base URL
    https://api.withallo.com
  • URL
    https://api.withallo.com/v2/api/conversations
  • Auth
    API key in header Authorization

Query parameters

allo_numberstring
Example:+14155550100

Filter by Allo number (E.164). Send exactly one of allo_number or inbox_id. List your numbers with GET /v2/api/numbers to find the right one.

inbox_idstring
Example:inb-abc123

List the conversations of one of your inboxes (inb-*), from all of its lines (each row has its own allo_number). The inbox's sources and saved filters apply, but not the app's Needs action and Mine tabs; pass unread yourself. Send exactly one of allo_number or inbox_id.

last_activity_sincestring date-time
Example:2026-04-20T10:00:00Z

Only return conversations with activity after this timestamp (ISO 8601). Ideal for incremental sync.

unreadboolean
pinnedboolean

Only pinned (true) or only unpinned (false) conversations. Any other value returns 400 INVALID_PARAMETER.

pageinteger

Page number (1-indexed)

sizeinteger

Results per page

extendstring
Example:transcript

Comma-separated optional fields. Supported: transcript

Response

List of conversations

Example response

{
  "data": [
    {
      "contact_number": "+14155551234",
      "contacts": [
        {
          "id": "cnt-abc123",
          "name": "Sarah Johnson",
          "company": {
            "id": "com-xyz789",
            "name": "Acme Corp"
          },
          "deals": [
            {
              "id": "dea-def456",
              "name": "Enterprise Plan"
            }
          ]
        }
      ],
      "last_item": {
        "id": "cll-abc123",
        "allo_number": "+14155550100",
        "contact_number": "+14155551234",
        "contacts": [
          {
            "id": "cnt-abc123",
            "name": "Sarah Johnson",
            "company": {
              "id": "com-xyz789",
              "name": "Acme Corp"
            },
            "deals": [
              {
                "id": "dea-def456",
                "name": "Enterprise Plan"
              }
            ]
          }
        ],
        "user": {
          "id": "usr-abc123",
          "name": "John",
          "email": "john@acme.com"
        },
        "extracted_data": {
          "contact": {
            "name": "Marie Dupont",
            "company": "Vibrant Events",
            "job_title": "Office manager",
            "website": "vibrantevents.com",
            "address": "12 rue de la Paix, Paris",
            "emails": [
              "marie@vibrantevents.com"
            ]
          }
        }
      },
      "allo_number": "+14155550100"
    }
  ]
}

Changes

  • 46c77103dd14Revision changes
    • warning

      added the new BLOCKED enum value to the //// response property for the response status

    • warning

      added the new CLOSED enum value to the //// response property for the response status

    • warning

      added the new FAILED enum value to the //// response property for the response status

    • warning

      added the new FAILED_EXTERNAL enum value to the //// response property for the response status

    • warning

      added the new RECEIVED enum value to the //// response property for the response status

    • warning

      added the new TRANSFERRED_AI enum value to the //// response property for the response status

    • warning

      added the new TRANSFERRED_EXTERNAL enum value to the //// response property for the response status

    • info

      added the new optional query request parameter inbox_id

    • info

      added the new optional query request parameter pinned

    • info

      the query request parameter allo_number became optional

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      removed the TRANSFERRED enum value from the //// response property for the response status

    • info

      added the required property /// to the response with the status