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

# List Channels

> Lists your connected WhatsApp and Messenger accounts. Each account also shows its WhatsApp phone numbers or Facebook pages in the endpoints field.



## OpenAPI

````yaml /api-collection/chatflows-api-v1.json get /api/v1/channels
openapi: 3.1.0
info:
  title: ChatFlows REST API
  version: 1.0.0
  description: >-
    ChatFlows REST API (v1).


    **Base URL:** `https://app.chatflows.io/api/v1` — also shown, with a copy
    button, on your **Developer API Keys** page.


    **Auth:** every authenticated request sends `Authorization: Bearer <token>`,
    where the token is created under **Setup → Developer API Keys** in your
    dashboard.


    **What a token can see:** a token belongs to ONE workspace — your store's.
    Every endpoint returns only that workspace's data, and `/api/v1/account`
    describes your own workspace. A token created before tokens were tied to a
    workspace is refused with `401 token_not_scoped`; create a new one to
    replace it.


    **Scopes:** each endpoint's description lists the token ability it requires.
    Create your token with the matching scopes.


    **Pagination:** list endpoints return `{ data, links: { next, prev }, meta
    }`. Large/append-only collections (contacts, group members, webhooks) use
    opaque cursor pagination — follow `links.next` until it is `null`.
    `per_page` is clamped to 5–100.


    **Async sends:** message and OTP sends return `202` and are processed on the
    queue.


    **Error envelope:**

    ```json

    { "message": "...", "error_code": "...", "status": 4xx }

    ```


    **Modules:** Auth/Account · Channels · Contacts · Statuses · Sources ·
    Groups · Labels · Templates · Messages · Conversations · OTP.
servers:
  - url: https://app.chatflows.io
    description: ChatFlows
security:
  - bearerAuth: []
tags:
  - name: Root
    description: Unauthenticated service metadata.
  - name: Auth & Account
    description: Verify your token, and read workspace identity, plan and usage.
  - name: Channels
    description: Connected WhatsApp accounts and their phone numbers.
  - name: Customers
    description: Create, read, update, merge and bulk-manage customers.
  - name: Customer Statuses
    description: The pipeline statuses a contact can be assigned.
  - name: Customer Sources
    description: Where a contact originated (e.g. website, referral).
  - name: Customer Groups
    description: Named groups used to segment contacts and target campaigns.
  - name: Customer Labels
    description: Free-form labels for tagging contacts.
  - name: Templates
    description: WhatsApp message templates and their Meta approval status.
  - name: Messages
    description: Send template and free-form messages, and read delivery status.
  - name: Conversations
    description: Customer conversation threads and their message history.
  - name: OTP
    description: Send, verify and resend one-time passcodes over WhatsApp.
  - name: Error Examples
    description: Reference shapes for the errors any endpoint may return.
paths:
  /api/v1/channels:
    get:
      tags:
        - Channels
      summary: List Channels
      operationId: channelsListChannels
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique ID.
                        platform:
                          type: string
                          description: '`whatsapp` or `messenger`.'
                        name:
                          type: string
                          description: The account name.
                        account_id:
                          type: string
                          description: The account's ID at Meta.
                        status:
                          type: string
                          description: >-
                            `pending`, `active`, `disconnecting`, `disconnected`
                            or `suspended`.
                        connection_method:
                          type: string
                          description: 'How it was connected: `embedded_signup` or `manual`.'
                        is_default:
                          type: boolean
                          description: '`true` if this is your default.'
                        connected_at:
                          type: string
                          description: When it was connected.
                        endpoints:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                description: Unique ID.
                              identifier:
                                type: string
                                description: The phone number's or page's ID at Meta.
                              display_name:
                                type: string
                                description: >-
                                  The phone number or page name, as shown to
                                  customers.
                              status:
                                type: string
                                description: >-
                                  `pending`, `active`, `disconnecting`,
                                  `disconnected` or `suspended`.
                              is_default:
                                type: boolean
                                description: '`true` if this is your default.'
                              phone_number_id:
                                type: string
                                description: WhatsApp only. Same as `identifier`.
                              display_number:
                                type: string
                                description: WhatsApp only. Same as `display_name`.
                              verified_name:
                                type: string
                                description: >-
                                  WhatsApp only. The business name Meta approved
                                  for this number.
                              quality_rating:
                                type: string
                                description: >-
                                  WhatsApp only. Meta's quality rating: `GREEN`,
                                  `YELLOW` or `RED`.
                              throughput_level:
                                type: string
                                description: >-
                                  WhatsApp only. How fast Meta lets this number
                                  send.
                          description: >-
                            The phone numbers (WhatsApp) or pages (Messenger) on
                            this account.
                        waba_id:
                          type: string
                          description: WhatsApp only. Same as `account_id`.
                        business_profile:
                          type: object
                          properties:
                            name:
                              type: string
                              description: Your business name at Meta.
                            country:
                              type: string
                              description: Business country code.
                            review_status:
                              type: string
                              description: Meta's account review status.
                            verification_status:
                              type: string
                              description: Meta's business verification status.
                          description: WhatsApp only. Your business details at Meta.
                        mm_lite_status:
                          description: >-
                            WhatsApp only. Status of Meta's Marketing Messages
                            Lite on this account.
                        phone_numbers:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                description: Unique ID.
                              phone_number_id:
                                type: string
                                description: WhatsApp only. Same as `identifier`.
                              display_number:
                                type: string
                                description: WhatsApp only. Same as `display_name`.
                              verified_name:
                                type: string
                                description: >-
                                  WhatsApp only. The business name Meta approved
                                  for this number.
                              quality_rating:
                                type: string
                                description: >-
                                  WhatsApp only. Meta's quality rating: `GREEN`,
                                  `YELLOW` or `RED`.
                              throughput_level:
                                type: string
                                description: >-
                                  WhatsApp only. How fast Meta lets this number
                                  send.
                              status:
                                type: string
                                description: >-
                                  `pending`, `active`, `disconnecting`,
                                  `disconnected` or `suspended`.
                              is_default:
                                type: boolean
                                description: '`true` if this is your default.'
                          description: >-
                            WhatsApp only. Same numbers as `endpoints`, in the
                            older format.
              examples:
                200 OK:
                  summary: 200 OK
                  value:
                    data:
                      - id: 1
                        platform: whatsapp
                        name: Main WhatsApp Account
                        account_id: '123456789012345'
                        status: active
                        connection_method: embedded_signup
                        is_default: true
                        connected_at: '2026-01-15T10:00:00+00:00'
                        endpoints:
                          - id: 2
                            identifier: '987654321098765'
                            display_name: +91 98765 43210
                            status: active
                            is_default: true
                            phone_number_id: '987654321098765'
                            display_number: +91 98765 43210
                            verified_name: My Store
                            quality_rating: GREEN
                            throughput_level: STANDARD
                        waba_id: '123456789012345'
                        business_profile:
                          name: My Store
                          country: IN
                          review_status: approved
                          verification_status: verified
                        mm_lite_status: null
                        phone_numbers:
                          - id: 2
                            phone_number_id: '987654321098765'
                            display_number: +91 98765 43210
                            verified_name: My Store
                            quality_rating: GREEN
                            throughput_level: STANDARD
                            status: active
                            is_default: true
                      - id: 5
                        platform: messenger
                        name: My Store Facebook Page
                        account_id: '104857392017465'
                        status: active
                        connection_method: embedded_signup
                        is_default: false
                        connected_at: '2026-02-01T10:00:00+00:00'
                        endpoints:
                          - id: 6
                            identifier: '104857392017465'
                            display_name: My Store Facebook Page
                            status: active
                            is_default: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/QuotaExhausted'
      security:
        - bearerAuth:
            - channels:read
components:
  responses:
    Unauthorized:
      description: >-
        Missing, invalid or expired API token — or an older token that is not
        tied to a workspace (`token_not_scoped`), in which case create a new one
        on the Developer API Keys page.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Missing API token.
            error_code: unauthenticated
            status: 401
    PaymentRequired:
      description: >-
        Your workspace has no active subscription, or its first payment is still
        pending.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Subscription required or expired.
            error_code: subscription_required
            status: 402
    Forbidden:
      description: >-
        The token lacks the required scope, or the account is suspended or on
        hold.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: 'This token is missing the required scope: contacts:write.'
            error_code: insufficient_scope
            status: 403
    QuotaExhausted:
      description: The monthly API request quota for the workspace is exhausted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: API request quota exhausted for this billing period.
            error_code: quota_exhausted
            status: 429
      headers:
        RateLimit-Limit:
          schema:
            type: integer
          description: Your API request quota for the current billing period.
        RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining in the current billing period.
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until the quota resets.
  schemas:
    Error:
      type: object
      description: Standard error envelope returned by every endpoint.
      properties:
        message:
          type: string
          description: Human-readable explanation.
        error_code:
          type: string
          description: Stable machine-readable code — branch on this, not the message.
        status:
          type: integer
          description: HTTP status code.
      required:
        - message
        - error_code
        - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your API key. Create one under **Setup → Developer API Keys** and select
        the permissions this endpoint needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.