WhatsApp Groups API

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses…
  version: v23.0
  description: 'API for retrieving connected client businesses associated with a Meta application.


    This endpoint allows applications to retrieve information about businesses that have

    established client connections through the application. This is essential for managing

    business relationships and understanding client business configurations.'
  contact:
    name: Meta Business Platform Team
    url: https://developers.facebook.com/support
  license:
    name: Meta Platform Terms
    url: https://developers.facebook.com/terms
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com
  description: Production Graph API server
- url: https://graph.facebook.com
- url: https://graph.facebook.com
  description: WhatsApp Business Cloud API
- url: https://graph.facebook.com
  description: Meta Graph API production server
tags:
- name: Groups
paths:
  /{Version}/{Phone-Number-ID}/groups:
    post:
      summary: Create Group
      description: Create a new group and get an invite link
      operationId: createGroup
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - name: Version
        in: path
        required: true
        schema:
          type: string
      - name: Phone-Number-ID
        in: path
        required: true
        description: Business phone number ID
        schema:
          type: string
        example: '12784358810'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - messaging_product
              - subject
              properties:
                messaging_product:
                  type: string
                  enum:
                  - whatsapp
                  description: Messaging product
                subject:
                  type: string
                  maxLength: 128
                  description: Group subject. Maximum 128 characters. Whitespace is trimmed.
                  example: New Purchase Inquiry
                description:
                  type: string
                  maxLength: 2048
                  description: Group description. Maximum 2048 characters.
                  example: Jim, an existing client, would like to learn about new car purchase options for current year models.
                join_approval_mode:
                  type: string
                  enum:
                  - approval_required
                  - auto_approve
                  default: auto_approve
                  description: 'Indicates if WhatsApp users who click the invitation link can join the group with or without being approved first.

                    - approval_required: WhatsApp users must be approved via join request before they can access the group

                    - auto_approve: WhatsApp users can join the group without approval

                    '
      responses:
        '200':
          description: Group creation request submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  messaging_product:
                    type: string
                    example: whatsapp
                  request_id:
                    type: string
                    description: Group creation request ID
                    example: '106540352242922'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - bearerAuth: []
      tags:
      - Groups
    get:
      summary: Get Active Groups
      description: Retrieve a list of active groups for a given business phone number
      operationId: getActiveGroups
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - name: Version
        in: path
        required: true
        schema:
          type: string
      - name: Phone-Number-ID
        in: path
        required: true
        description: Business phone number ID
        schema:
          type: string
      - name: limit
        in: query
        description: Number of groups to fetch in the request
        schema:
          type: integer
          minimum: 1
          maximum: 1024
          default: 25
      - name: after
        in: query
        description: Cursor that points to the end of a page of data
        schema:
          type: string
      - name: before
        in: query
        description: Cursor that points to the beginning of a page of data
        schema:
          type: string
      responses:
        '200':
          description: List of active groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      groups:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Group ID
                            subject:
                              type: string
                              description: Group subject
                            created_at:
                              type: string
                              description: Group creation timestamp
                  paging:
                    $ref: '#/components/schemas/PagingInfo'
      security:
      - bearerAuth: []
      tags:
      - Groups
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: 'Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

        '
      required: true
      schema:
        type: string
        pattern: ^Bearer\s+[A-Za-z0-9\-_.]+.*$
        example: Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...
    UserAgent:
      name: User-Agent
      in: header
      description: The user agent string identifying the client software making the request.
      required: false
      schema:
        type: string
        default: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
        pattern: ^[a-zA-Z0-9\-_]+\/[0-9]+\.[0-9]+\.[0-9]+(;[a-zA-Z0-9\-=\.]+)?(\s+[a-zA-Z0-9\-_]+\/[0-9\-\.]+)?$
        example: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
    ContentType:
      name: Content-Type
      in: header
      description: Media type of the request body
      required: true
      schema:
        type: string
        enum:
        - application/json
        - application/x-www-form-urlencoded
        - multipart/form-data
        default: application/json
        example: application/json
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
      - error
    PagingInfo:
      type: object
      properties:
        cursors:
          type: object
          properties:
            before:
              type: string
              description: Before cursor
            after:
              type: string
              description: After cursor
        previous:
          type: string
          description: Previous page URL
        next:
          type: string
          description: Next page URL
    ErrorObject:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the error
        type:
          type: string
          description: Error type classification
        code:
          type: integer
          description: Numeric error code
      required:
      - message
      - type
      - code
  responses:
    BadRequest:
      description: Bad Request - Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InvalidTemplateParameters:
              summary: Invalid template name or parameters
              value:
                error:
                  message: Invalid template name or parameters
                  type: OAuthException
                  code: 100
            MalformedRequest:
              summary: Malformed request body
              value:
                error:
                  message: Invalid JSON in request body
                  type: OAuthException
                  code: 100
            MissingFeatureSetting:
              summary: One feature setting must be specified
              value:
                error:
                  message: One feature setting must be specified
                  type: OAuthException
                  code: 100
    InternalServerError:
      description: Internal Server Error - An unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UnexpectedError:
              summary: Unexpected server error
              value:
                error:
                  message: An unexpected error occurred
                  type: OAuthException
                  code: 1
    Unauthorized:
      description: Unauthorized - Invalid or missing access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InvalidAccessToken:
              summary: Invalid OAuth access token
              value:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
            MissingAccessToken:
              summary: Missing access token
              value:
                error:
                  message: An access token is required to request this resource
                  type: OAuthException
                  code: 104
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'System user access token with whatsapp_business_management permission. Format: Bearer YOUR_SYSTEM_USER_ACCESS_TOKEN

        '