> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lehar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List WhatsApp sessions

> Lists WhatsApp conversations across all campaigns as agent-scoped sessions, optionally filtered by `agent_id`; each row carries the masked phone, qualification verdict, and message count. Owner-scoped for a normal logged-in user (only conversations from campaigns they created; campaign-less threads are admin-only), while API-key and admin callers see the whole workspace. Scope `campaigns:read`.



## OpenAPI

````yaml /api-reference/openapi.json get /whatsapp/sessions
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /whatsapp/sessions:
    get:
      tags:
        - Campaigns
      summary: List WhatsApp sessions
      description: >-
        Lists WhatsApp conversations across all campaigns as agent-scoped
        sessions, optionally filtered by `agent_id`; each row carries the masked
        phone, qualification verdict, and message count. Owner-scoped for a
        normal logged-in user (only conversations from campaigns they created;
        campaign-less threads are admin-only), while API-key and admin callers
        see the whole workspace. Scope `campaigns:read`.
      operationId: list_whatsapp_sessions_ca_api_v0_whatsapp_sessions_get
      parameters:
        - name: agent_id
          in: query
          required: false
          description: Filter conversations to those driven by this agent.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum rows to return (clamped to 100).
          schema:
            type: integer
            default: 20
            minimum: 0
            maximum: 100
        - name: offset
          in: query
          required: false
          description: Number of rows to skip.
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        '200':
          description: A page of WhatsApp conversations (sessions).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        campaign_id:
                          type: string
                          nullable: true
                        recipient_id:
                          type: string
                          nullable: true
                        agent_id:
                          type: string
                          nullable: true
                        provider:
                          type: string
                        phone_number_masked:
                          type: string
                          description: End-user phone, masked (e.g. 9***5678).
                        status:
                          type: string
                        qualification_status:
                          type: string
                          nullable: true
                        goal_state:
                          type: string
                          nullable: true
                          description: Conversation running-memory goal state.
                        message_count:
                          type: integer
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
                      total:
                        type: integer
              example:
                data:
                  - id: wac_01HZY4A0P3RK5S8W9U1Q6C7D8E
                    campaign_id: camp_01HZX2B7N1PJ3Q6T8V0M4A5B6C
                    recipient_id: rcpt_01HZX3C8M2QK4R7U9W1N5B6C7D
                    agent_id: agt_01HZW1A6L0NH2P5S7U9K3Z4Y5X
                    provider: trustsignal
                    phone_number_masked: 9***5678
                    status: open
                    qualification_status: qualified
                    goal_state: completed
                    message_count: 6
                    created_at: '2026-09-01T10:15:00Z'
                    updated_at: '2026-09-01T11:00:00Z'
                pagination:
                  limit: 20
                  offset: 0
                  total: 1
        '400':
          description: Invalid pagination parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              example:
                error:
                  code: invalid_request
                  message: limit and offset must be non-negative integers
        '401':
          description: Authentication is required or the credentials are invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              example:
                error:
                  code: unauthorized
                  message: Authentication required
        '403':
          description: The caller lacks the required scope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              example:
                error:
                  code: forbidden
                  message: Scope 'campaigns:read' is required
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              example:
                error:
                  code: internal_error
                  message: An unexpected error occurred
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````