# List chats (v2)

Paginated chat list for the authenticated agent, selected by scope. The agent and client are resolved from your API key / session. Returns a lean ChatParticipantResponse page and replaces the deprecated Get chat participants.

Endpoint: GET /pl4chat-service/api/v2/chats
Version: 3.0.0
Security: apikeyAuth

## Query parameters:

  - `scope` (string, required)
    Which list to return: my (assigned to you), team (your team's), unassigned, closed, my-missed, missed-agent, missed-after-hours, open (all open client chats), or all (open and closed).
    Enum: "my", "team", "my-missed", "unassigned", "closed", "missed-agent", "missed-after-hours", "open", "all"

  - `page` (integer)
    Page number (zero-based).

  - `size` (integer)
    Number of items per page.
    Example: 10

  - `search` (string)
    Optional case-insensitive substring filter on phone number and full name.
    Example: "27123456789"

## Response 200 fields (application/json):

  - `content` (array)

  - `content.id` (string)
    Example: "aef65b5a-23a4-462a-a275-9aa2f3e0e56e"

  - `content.fullName` (string)
    Example: "John Doe"

  - `content.firstName` (string)
    Example: "John"

  - `content.lastName` (string)
    Example: "Doe"

  - `content.phoneNumber` (string)
    Example: "27821234567"

  - `content.userId` (string)
    Customer's durable business-scoped user id (BSUID, alpha usernames). Stable across phone-number changes; present even when the phone is withheld.
    Example: "ZA.1021033720668862"

  - `content.username` (string)
    Customer's optional WhatsApp username (display only).
    Example: "johndoe"

  - `content.email` (string)
    Example: "john.doe@example.com"

  - `content.channel` (string)
    Enum: "WHATSAPP", "WEB", "FACEBOOK"

  - `content.conversationStatus` (string)
    Example: "ACTIVE"

  - `content.conversationClosed` (boolean)

  - `content.unread` (boolean)
    Example: true

  - `content.missedConversation` (boolean)

  - `content.chatBotConversation` (boolean)

  - `content.whatsAppClientNumber` (string)
    Example: "+27123456789"

  - `content.team` (string)
    Example: "Support"

  - `content.teamId` (string)
    Example: "288436ad-4522-4f27-95e9-c406a917894d"

  - `content.lastMessageTime` (string)
    Example: "2026-01-15T10:31:00Z"

  - `content.createdTime` (string)
    Example: "2026-01-15T10:00:00Z"

  - `content.customerLastMessageTime` (string)
    Example: "2026-01-15T10:30:00Z"

  - `content.assignedTo` (object)
    Lean reference to the agent who sent or owns a message.

  - `content.assignedTo.id` (string)
    Example: "b2c3d4e5-f6a7-8901-b2c3-d4e5f6a78901"

  - `content.assignedTo.firstName` (string)
    Example: "Alice"

  - `content.assignedTo.lastName` (string)
    Example: "Smith"

  - `content.assignedTo.email` (string)
    Example: "alice.smith@example.com"

  - `content.assignedTo.avatar` (string)
    URL of the agent's avatar image.
    Example: "https://example.com/avatars/alice.png"

  - `content.lastAssignedAgent` (object)
    Lean reference to the agent who sent or owns a message.

  - `totalElements` (integer)
    Example: 85

  - `totalPages` (integer)
    Example: 9

  - `size` (integer)
    Example: 10

  - `number` (integer)

  - `first` (boolean)
    Example: true

  - `last` (boolean)

  - `empty` (boolean)

## Response 400 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Invalid Parameters"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"

## Response 401 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Unauthorized user"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"

## Response 403 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Forbidden"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"