> ## Documentation Index > Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt > Use this file to discover all available pages before exploring further. # List conversations > Retrieve a paginated list of WhatsApp conversations for a phone number. Conversations are ordered by last activity (most recent first). Supports filtering by status, activity time range, and phone number. ## Kapso Extensions The response includes Kapso-specific conversation metadata: - Message counts (total and unread) - Associated contact information - Conversation status and timestamps ## OpenAPI ````yaml /api/meta/whatsapp/openapi-whatsapp.yaml get /{phone_number_id}/conversations openapi: 3.1.0 info: title: Kapso Meta Proxy API version: 1.0.0 description: > Kapso's Meta Proxy API provides a unified interface to WhatsApp Business Platform with enhanced features and Kapso-specific extensions. This API acts as a proxy layer between your application and WhatsApp, adding: - Simplified authentication with project-level API keys - Enhanced message metadata and tracking - Conversation management capabilities - Voice call integration - Extended contact and template management ## Base URL All API requests are made to: `https://api.kapso.ai/meta/whatsapp/v24.0` ## Authentication The API supports authentication via **X-API-Key header** (recommended): ``` X-API-Key: your_project_api_key ``` Alternative: Bearer token authentication is also supported for backward compatibility: ``` Authorization: Bearer your_access_token ``` Note: X-API-Key is the recommended authentication method for the Meta Proxy API. contact: name: Kapso Support url: https://kapso.ai email: dev@kap.so servers: - url: https://api.kapso.ai/meta/whatsapp/v24.0 description: Production server security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Messages description: Send and retrieve WhatsApp messages - name: Conversations description: Manage WhatsApp conversations - name: Contacts description: Manage WhatsApp contacts - name: Templates description: Manage message templates - name: Media description: Upload and retrieve media files - name: Calls description: Manage voice calls - name: Settings description: Account settings and configuration - name: Business Profile description: Business profile management - name: Phone Numbers description: Phone number management - name: Flows description: WhatsApp Flow management (Beta) - name: Block Users description: Block and unblock WhatsApp users - name: Usernames description: Reserve and manage WhatsApp business usernames paths: /{phone_number_id}/conversations: parameters: - name: phone_number_id in: path required: true description: WhatsApp Business Phone Number ID schema: type: string example: '110987654321' get: tags: - Conversations summary: List conversations description: | Retrieve a paginated list of WhatsApp conversations for a phone number. Conversations are ordered by last activity (most recent first). Supports filtering by status, activity time range, and phone number. ## Kapso Extensions The response includes Kapso-specific conversation metadata: - Message counts (total and unread) - Associated contact information - Conversation status and timestamps operationId: listConversations parameters: - name: status in: query description: Filter by conversation status schema: type: string enum: - active - ended example: active - name: assigned_user_id in: query description: Filter by active assignee user ID (must be a project member) schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 - name: unassigned in: query description: >- Filter conversations with no active assignment. Cannot be combined with `assigned_user_id`. schema: type: boolean example: true - name: last_active_since in: query description: Filter conversations active on or after this time (ISO 8601) schema: type: string format: date-time example: '2024-01-15T00:00:00.000Z' - name: last_active_until in: query description: Filter conversations active on or before this time (ISO 8601) schema: type: string format: date-time example: '2024-01-15T23:59:59.000Z' - name: phone_number in: query description: Filter by contact phone number schema: type: string example: '+15551234567' - name: limit in: query description: Maximum number of results per page (default 20, max 100) schema: type: integer minimum: 1 maximum: 100 default: 20 example: 20 - name: before in: query description: Cursor for previous page (Base64 encoded) schema: type: string - name: after in: query description: Cursor for next page (Base64 encoded) schema: type: string - name: fields in: query description: >- Filter response fields. Use `kapso()` to include Kapso-specific extensions. schema: type: string example: kapso() responses: '200': description: Successfully retrieved conversations content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/WhatsappConversation' paging: $ref: '#/components/schemas/Paging' examples: success: summary: List of conversations value: data: - id: 123e4567-e89b-12d3-a456-426614174000 phone_number: '15551234567' status: active last_active_at: '2024-01-15T14:30:00.000Z' created_at: '2024-01-15T10:00:00.000Z' updated_at: '2024-01-15T14:30:00.000Z' whatsapp_config_id: 456e7890-a12b-34c5-d678-901234567890 metadata: tags: - vip - priority phone_number_id: '110987654321' kapso: contact_name: John Doe messages_count: 15 last_message_id: >- wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== last_message_type: text last_message_timestamp: '2024-01-15T14:30:00.000Z' last_message_text: Hello! I need help with my order last_inbound_at: '2024-01-15T14:30:00.000Z' last_outbound_at: '2024-01-15T14:25:00.000Z' - id: 223e4567-e89b-12d3-a456-426614174001 phone_number: '15559876543' status: ended last_active_at: '2024-01-14T12:00:00.000Z' created_at: '2024-01-14T08:00:00.000Z' updated_at: '2024-01-14T12:00:00.000Z' whatsapp_config_id: 456e7890-a12b-34c5-d678-901234567890 metadata: null phone_number_id: '110987654321' kapso: contact_name: Jane Smith messages_count: 8 last_message_id: >- wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAB== last_message_type: text last_message_timestamp: '2024-01-14T12:00:00.000Z' last_message_text: Thank you for your help! last_inbound_at: '2024-01-14T12:00:00.000Z' last_outbound_at: '2024-01-14T11:58:00.000Z' paging: cursors: after: >- eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNFQxMjowMDowMC4wMDAwMDBaIiwiMjIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAxIl0sImNvbHVtbnMiOlsibGFzdF9hY3RpdmVfYXQiLCJpZCJdfQ== '400': description: Bad request (invalid parameters) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized (invalid or missing API key) content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Phone number not found content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Validation error (conflicting filters or invalid assignee) content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: WhatsappConversation: type: object required: - id - status - last_active_at - created_at - updated_at - whatsapp_config_id - phone_number_id properties: id: type: string description: Conversation ID (UUID) example: 123e4567-e89b-12d3-a456-426614174000 phone_number: type: string nullable: true description: >- Contact's phone number (normalized). Can be null for BSUID-only identity. example: '15551234567' business_scoped_user_id: type: string nullable: true description: WhatsApp business-scoped user ID example: US.13491208655302741918 parent_business_scoped_user_id: type: string nullable: true description: Parent business-scoped user ID when provided by Meta example: US.ENT.506847293015824 username: type: string nullable: true description: WhatsApp username when available example: '@testusername' status: type: string enum: - active - ended description: Conversation status example: active last_active_at: type: string format: date-time description: Last activity timestamp example: '2024-01-15T14:30:00.000Z' created_at: type: string format: date-time description: Creation timestamp example: '2024-01-15T10:00:00.000Z' updated_at: type: string format: date-time description: Last update timestamp example: '2024-01-15T14:30:00.000Z' whatsapp_config_id: type: string description: WhatsApp configuration ID (UUID) example: 456e7890-a12b-34c5-d678-901234567890 metadata: type: object description: Custom metadata additionalProperties: true nullable: true phone_number_id: type: string description: WhatsApp Business Phone Number ID example: '110987654321' kapso: type: object description: Kapso-specific conversation metadata properties: contact_name: type: string nullable: true description: Contact display name example: John Doe messages_count: type: integer description: Total message count in conversation example: 15 last_message_id: type: string nullable: true description: WhatsApp message ID of last message example: wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== last_message_type: type: string nullable: true description: Type of last message example: text last_message_timestamp: type: string format: date-time nullable: true description: Timestamp of last message (ISO 8601) example: '2024-01-15T14:30:00.000Z' last_message_text: type: string nullable: true description: Text content of last message (if text message) example: Hello! I need help with my order last_inbound_at: type: string format: date-time nullable: true description: Timestamp of last inbound message (ISO 8601) example: '2024-01-15T14:30:00.000Z' last_outbound_at: type: string format: date-time nullable: true description: Timestamp of last outbound message (ISO 8601) example: '2024-01-15T14:25:00.000Z' Paging: type: object properties: cursors: $ref: '#/components/schemas/PaginationCursor' Error: type: object required: - error properties: error: type: object required: - message - type - code properties: message: type: string description: Human-readable error message example: Invalid phone number format type: type: string description: Error category example: OAuthException code: type: integer description: Error code example: 400 error_subcode: type: integer description: More specific error code example: 1001 fbtrace_id: type: string description: Facebook trace ID for debugging example: AXk7s_8dR4eVHp9Kq2MmNlO PaginationCursor: type: object properties: before: type: string description: Cursor for previous page (Base64 encoded) example: >- eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0= after: type: string description: Cursor for next page (Base64 encoded) example: >- eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNFQwOToyMTozMi43ODkwMTJaIiwiMTIzMjAiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0= securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: > Project API key for authentication. This is the recommended authentication method. Get your API key from the Kapso dashboard under Integrations > API keys. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | Bearer token authentication (alternative method). Note: X-API-Key authentication is recommended for the Meta Proxy API. ````