WhatsApp WhatsApp Business Account Users 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: WhatsApp Business Account Users
  description: APIs for managing user assignments and permissions for WhatsApp Business Accounts
paths:
  /{Version}/{WhatsApp-Business-Account-ID}/assigned_users:
    get:
      summary: List Assigned Users
      description: 'Retrieve a list of users assigned to the WhatsApp Business Account with their permissions

        and user details. This endpoint supports pagination and filtering capabilities.


        **Use Cases:**

        - Audit user access to WhatsApp Business Account

        - Retrieve user permission assignments for compliance

        - List all users with access for management purposes

        - Monitor user access patterns and assignments


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.


        **Caching:**

        User assignment data can be cached for short periods, but permission changes may occur

        frequently. Implement appropriate cache invalidation strategies.'
      operationId: getAssignedUsers
      tags:
      - WhatsApp Business Account Users
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: WhatsApp-Business-Account-ID
        in: path
        required: true
        description: 'Your WhatsApp Business Account ID. This ID is provided when you create the account

          and can be found in your Business Manager or through account management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      - name: business
        in: query
        required: true
        description: 'Business ID that owns or has access to the WhatsApp Business Account.

          This parameter is required to specify the business context for user assignments.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '9876543210987654'
      - name: fields
        in: query
        required: false
        description: 'Comma-separated list of fields to include in the response. If not specified,

          default fields will be returned (id, name). Available fields: id, name, business, user_type

          '
        schema:
          type: string
        example: id,name,business,user_type
      - name: limit
        in: query
        required: false
        description: 'Maximum number of assigned users to return per page. Default is 25, maximum is 100.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 100
        example: 25
      - name: after
        in: query
        required: false
        description: 'Cursor for pagination. Use this to get the next page of results.

          '
        schema:
          type: string
        example: QVFIUjJ5M2wwdmtONVFHbDZAMVQ4OGJBQUFBQQ
      - name: before
        in: query
        required: false
        description: 'Cursor for pagination. Use this to get the previous page of results.

          '
        schema:
          type: string
        example: QVFIUmx1WTBpMGpJWXprYzVYaVhabW9PVVhF
      responses:
        '200':
          description: Successfully retrieved assigned users list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignedUsersResponse'
              examples:
                multiple_users:
                  summary: Multiple assigned users with different types
                  value:
                    data:
                    - id: '1234567890123456'
                      name: John Smith
                      business:
                        id: '9876543210987654'
                        name: Example Business Inc
                      user_type: BUSINESS_USER
                    - id: '2345678901234567'
                      name: System User Bot
                      business:
                        id: '9876543210987654'
                        name: Example Business Inc
                      user_type: SYSTEM_USER
                    paging:
                      cursors:
                        after: QVFIUjJ5M2wwdmtONVFHbDZAMVQ4OGJBQUFBQQ
                        before: QVFIUmx1WTBpMGpJWXprYzVYaVhabW9PVVhF
                      next: https://graph.facebook.com/v23.0/1234567890123456/assigned_users?access_token=YOUR_SYSTEM_USER_ACCESS_TOKEN&limit=25&after=QVFIUjJ5M2wwdmtONVFHbDZAMVQ4OGJBQUFBQQ
                    summary:
                      total_count: 15
                single_user:
                  summary: Single assigned user
                  value:
                    data:
                    - id: '1234567890123456'
                      name: Jane Doe
                      user_type: BUSINESS_USER
                    summary:
                      total_count: 1
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: The parameter business is required to specify a business
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Need permission on WhatsAppBusinessAccount or this Business
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - WhatsApp Business Account ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: The requested fields are not available for this account
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
    post:
      summary: Add User to WhatsApp Business Account
      description: 'Add a user to the WhatsApp Business Account with specified permission tasks.

        This operation grants the user access to perform specific actions on the account

        based on the provided permission tasks.


        **Use Cases:**

        - Grant user access to WhatsApp Business Account management

        - Assign specific permission tasks for granular access control

        - Add new team members to WhatsApp Business Account operations

        - Configure user permissions for different business roles


        **Permission Tasks:**

        Different permission tasks grant access to different WhatsApp Business Account features:

        - MANAGE: General account management permissions

        - DEVELOP: Development and API access permissions

        - MANAGE_TEMPLATES: Message template management

        - MANAGE_PHONE: Phone number management

        - MESSAGING: Send and receive messages

        - FULL_CONTROL: Complete access to all account features


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.'
      operationId: addAssignedUser
      tags:
      - WhatsApp Business Account Users
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: WhatsApp-Business-Account-ID
        in: path
        required: true
        description: 'Your WhatsApp Business Account ID. This ID is provided when you create the account

          and can be found in your Business Manager or through account management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - user
              - tasks
              properties:
                user:
                  type: string
                  description: 'User ID of the person to add to the WhatsApp Business Account.

                    This must be a valid Facebook user ID.

                    '
                  pattern: ^[0-9]+$
                  example: '2345678901234567'
                tasks:
                  type: array
                  description: 'Array of permission tasks to grant to the user. These tasks determine

                    what actions the user can perform on the WhatsApp Business Account.

                    '
                  items:
                    $ref: '#/components/schemas/WhatsAppBusinessAccountPermissionTask'
                  minItems: 1
                  maxItems: 16
                  example:
                  - MANAGE
                  - DEVELOP
                  - MANAGE_TEMPLATES
            examples:
              basic_permissions:
                summary: Add user with basic management permissions
                value:
                  user: '2345678901234567'
                  tasks:
                  - MANAGE
                  - VIEW_INSIGHTS
              developer_permissions:
                summary: Add user with development permissions
                value:
                  user: '3456789012345678'
                  tasks:
                  - DEVELOP
                  - MANAGE_TEMPLATES
                  - VIEW_TEMPLATES
              full_access:
                summary: Add user with full control
                value:
                  user: '4567890123456789'
                  tasks:
                  - FULL_CONTROL
      responses:
        '200':
          description: Successfully added user to WhatsApp Business Account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: user must be a valid user ID'
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to add users to this WhatsApp Business Account
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - WhatsApp Business Account ID or User ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: User is already assigned to this WhatsApp Business Account
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
    delete:
      summary: Remove User from WhatsApp Business Account
      description: 'Remove a user''s access from the WhatsApp Business Account. This operation revokes

        all permissions and access rights for the specified user on the account.


        **Use Cases:**

        - Revoke user access when they leave the organization

        - Remove temporary access grants

        - Clean up user permissions for security compliance

        - Manage user lifecycle and access control


        **Important Notes:**

        - This operation removes ALL permissions for the user on this WhatsApp Business Account

        - The user will lose access to all account features and data

        - This action cannot be undone - the user must be re-added if access is needed again

        - Webhooks may be triggered to notify of user access changes


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.'
      operationId: removeAssignedUser
      tags:
      - WhatsApp Business Account Users
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: WhatsApp-Business-Account-ID
        in: path
        required: true
        description: 'Your WhatsApp Business Account ID. This ID is provided when you create the account

          and can be found in your Business Manager or through account management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - user
              properties:
                user:
                  type: string
                  description: 'User ID of the person to remove from the WhatsApp Business Account.

                    This must be a valid Facebook user ID that is currently assigned to the account.

                    '
                  pattern: ^[0-9]+$
                  example: '2345678901234567'
            examples:
              remove_user:
                summary: Remove user access
                value:
                  user: '2345678901234567'
      responses:
        '200':
          description: Successfully removed user from WhatsApp Business Account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: user must be a valid user ID'
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to remove users from this WhatsApp Business Account
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - WhatsApp Business Account ID or User ID does not exist or is not assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: User is not assigned to this WhatsApp Business Account
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Cannot remove user due to business asset group permissions
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
components:
  schemas:
    AssignedUsersResponse:
      type: object
      description: Response containing list of assigned users with pagination
      required:
      - data
      properties:
        data:
          type: array
          description: Array of assigned users
          items:
            $ref: '#/components/schemas/AssignedUser'
        paging:
          $ref: '#/components/schemas/CursorPaging'
        summary:
          $ref: '#/components/schemas/AssignedUsersSummary'
    CursorPaging:
      type: object
      description: Cursor-based pagination information
      properties:
        cursors:
          type: object
          properties:
            before:
              type: string
              description: Cursor pointing to the start of the page of data
              example: QVFIUjNpUWpVWmRBd0dn
            after:
              type: string
              description: Cursor pointing to the end of the page of data
              example: QVFIUjNpUWpVWmRBd0Rn
        previous:
          type: string
          description: URL for the previous page of results
          example: https://graph.facebook.com/v23.0/1234567890/connected_client_businesses?before=QVFIUjNpUWpVWmRBd0Dn
        next:
          type: string
          description: URL for the next page of results
          example: https://graph.facebook.com/v23.0/1234567890/connected_client_businesses?after=QVFIUjNpUWpVWmRBd0Rn
    GraphAPIError:
      type: object
      description: Standard Graph API error response
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Invalid parameter
            type:
              type: string
              description: Error category type
              example: OAuthException
            code:
              type: integer
              description: Numeric error code
              example: 100
            error_subcode:
              type: integer
              description: More specific error subcode when available
              example: 33
            fbtrace_id:
              type: string
              description: Unique identifier for debugging and support requests with Meta
              example: AXsgnV2Cm3ZMGF3dF_cfYIn
            is_transient:
              type: boolean
              description: Indicates whether this error is temporary and the request should be retried
              example: false
            error_user_title:
              type: string
              description: User-friendly error title for display purposes
              example: Permission Denied
            error_user_msg:
              type: string
              description: User-friendly error message for display purposes
              example: Your app doesn't have permission to access this resource
    SuccessResponse:
      type: object
      description: Generic success response
      required:
      - success
      properties:
        success:
          type: boolean
          description: Operation success status
          example: true
    WhatsAppBusinessAccountPermissionTask:
      type: string
      description: Granular permission tasks for WhatsApp Business Account access
      enum:
      - MANAGE
      - DEVELOP
      - MANAGE_TEMPLATES
      - MANAGE_PHONE
      - VIEW_COST
      - MANAGE_EXTENSIONS
      - VIEW_PHONE_ASSETS
      - MANAGE_PHONE_ASSETS
      - VIEW_TEMPLATES
      - VIEW_INSIGHTS
      - RECEIVE_INCOMING_MESSAGES
      - MANAGE_BILLING
      - MANAGE_USERS
      - MESSAGING
      - FULL_CONTROL
      example: MANAGE
    BusinessNode:
      type: object
      description: Business entity associated with the user
      properties:
        id:
          type: string
          description: Unique identifier for the business
          example: '9876543210987654'
        name:
          type: string
          description: Name of the business
          example: Example Business Inc
    AssignedUsersSummary:
      type: object
      description: Summary information about assigned users
      properties:
        total_count:
          type: integer
          description: Total number of assigned users
          example: 25
    AssignedUser:
      type: object
      description: User assigned to WhatsApp Business Account with permissions
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Unique identifier for the assigned user
          example: '1234567890123456'
        name:
          type: string
          description: Display name of the assigned user
          example: John Smith
        business:
          $ref: '#/components/schemas/BusinessNode'
        user_type:
          $ref: '#/components/schemas/AssignedUserType'
    AssignedUserType:
      type: string
      description: Type of user assignment
      enum:
      - BUSINESS_USER
      - SYSTEM_USER
      - PERSONAL_USER
      example: BUSINESS_USER
  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
  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

        '