WhatsApp WhatsApp Business Account Activities 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 Activities
  description: APIs for retrieving WhatsApp Business Account activity logs and audit trails
paths:
  /{Version}/{WABA-ID}/activities:
    get:
      summary: Get WhatsApp Business Account Activities
      description: 'Retrieve activity logs and audit trails for a WhatsApp Business Account.

        This endpoint returns a chronological list of activities performed on the account,

        including administrative actions, configuration changes, and operational events.


        **Use Cases:**

        - Monitor account configuration changes and administrative actions

        - Generate compliance and audit reports for regulatory requirements

        - Track user activities and permission modifications

        - Investigate security incidents and unauthorized access attempts

        - Monitor API usage patterns and operational events


        **Rate Limiting:**

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


        **Caching:**

        Activity data can be cached for short periods, but recent activities may change

        frequently. Implement appropriate cache invalidation strategies.'
      operationId: getWhatsAppBusinessAccountActivities
      tags:
      - WhatsApp Business Account Activities
      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: WABA-ID
        in: path
        required: true
        description: 'Your WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager

          or through the business account management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      - 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, activity_type, timestamp, actor_type).

          Available fields: id, activity_type, timestamp, actor_type, actor_id, actor_name, description, details, ip_address, user_agent

          '
        schema:
          type: string
        example: id,activity_type,timestamp,actor_name,description
      - name: limit
        in: query
        required: false
        description: 'Maximum number of activity records to return per page. Default is 25, maximum is 100.

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

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

          '
        schema:
          type: string
        example: MTAxNTExOTQ1MjAwNzI5NDE=
      - name: since
        in: query
        required: false
        description: 'Unix timestamp or ISO 8601 date string. Only return activities that occurred after this time.

          '
        schema:
          type: string
        example: '2023-10-01T00:00:00Z'
      - name: until
        in: query
        required: false
        description: 'Unix timestamp or ISO 8601 date string. Only return activities that occurred before this time.

          '
        schema:
          type: string
        example: '2023-10-31T23:59:59Z'
      - name: activity_type
        in: query
        required: false
        description: 'Filter activities by type. Can be a single type or comma-separated list of types.

          '
        schema:
          type: string
        example: PHONE_NUMBER_VERIFIED,USER_ADDED
      responses:
        '200':
          description: Successfully retrieved WhatsApp Business Account activities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityList'
              examples:
                recent_activities:
                  summary: Recent account activities
                  value:
                    data:
                    - id: '1234567890123456'
                      activity_type: PHONE_NUMBER_VERIFIED
                      timestamp: '2023-10-15T14:30:00Z'
                      actor_type: USER
                      actor_id: '9876543210987654'
                      actor_name: John Smith
                      description: Phone number +1234567890 was successfully verified
                      details:
                        phone_number: '+1234567890'
                        verification_method: SMS
                      ip_address: 192.168.1.100
                    - id: '1234567890123457'
                      activity_type: USER_ADDED
                      timestamp: '2023-10-15T13:15:00Z'
                      actor_type: ADMIN
                      actor_id: '1111222233334444'
                      actor_name: Admin User
                      description: New user Jane Doe was added to the account
                      details:
                        user_id: '5555666677778888'
                        user_name: Jane Doe
                        role: DEVELOPER
                    paging:
                      cursors:
                        after: NDMyNzQyODI3OTQw
                        before: MTAxNTExOTQ1MjAwNzI5NDE=
                      next: https://graph.facebook.com/v23.0/1234567890123456/activities?limit=25&after=NDMyNzQyODI3OTQw
                filtered_activities:
                  summary: Filtered activities by type
                  value:
                    data:
                    - id: '1234567890123458'
                      activity_type: TEMPLATE_CREATED
                      timestamp: '2023-10-14T16:45:00Z'
                      actor_type: USER
                      actor_id: '9876543210987654'
                      actor_name: Marketing Team
                      description: New message template 'welcome_message' was created
                      details:
                        template_name: welcome_message
                        template_language: en_US
                        template_category: MARKETING
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: limit must be between 1 and 100'
                  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 access WhatsApp Business Account activities
                  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 date range is too large. Maximum range is 90 days
                  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:
    Paging:
      type: object
      properties:
        cursors:
          $ref: '#/components/schemas/PaginationCursors'
    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
    WhatsAppBusinessAccountActivity:
      type: object
      description: WhatsApp Business Account activity record
      required:
      - id
      - activity_type
      - timestamp
      - actor_type
      properties:
        id:
          type: string
          description: Unique identifier for the activity record
          example: '1234567890123456'
        activity_type:
          $ref: '#/components/schemas/ActivityType'
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the activity occurred
          example: '2023-10-15T14:30:00Z'
        actor_type:
          $ref: '#/components/schemas/ActorType'
        actor_id:
          type: string
          description: ID of the user or system that performed the activity
          example: '9876543210987654'
        actor_name:
          type: string
          description: Name of the user or system that performed the activity
          example: John Smith
        description:
          type: string
          description: Human-readable description of the activity
          example: Phone number configuration updated
        details:
          type: object
          description: Additional structured details about the activity
          additionalProperties: true
          example:
            phone_number: '+1234567890'
            previous_status: UNVERIFIED
            new_status: VERIFIED
        ip_address:
          type: string
          description: IP address from which the activity was performed (when available)
          example: 192.168.1.100
        user_agent:
          type: string
          description: User agent string from the client that performed the activity
          example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
    ActivityType:
      type: string
      description: Type of activity performed on the WhatsApp Business Account
      enum:
      - ACCOUNT_CREATED
      - ACCOUNT_UPDATED
      - ACCOUNT_DELETED
      - PHONE_NUMBER_ADDED
      - PHONE_NUMBER_REMOVED
      - PHONE_NUMBER_VERIFIED
      - USER_ADDED
      - USER_REMOVED
      - USER_ROLE_CHANGED
      - PERMISSION_GRANTED
      - PERMISSION_REVOKED
      - TEMPLATE_CREATED
      - TEMPLATE_UPDATED
      - TEMPLATE_DELETED
      - WEBHOOK_CONFIGURED
      - API_ACCESS_GRANTED
      - API_ACCESS_REVOKED
      - BILLING_UPDATED
      - COMPLIANCE_ACTION
      - SECURITY_EVENT
      example: PHONE_NUMBER_VERIFIED
    PaginationCursors:
      type: object
      properties:
        after:
          type: string
          example: eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD
        before:
          type: string
          example: eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD
    ActorType:
      type: string
      description: Type of entity that performed the activity
      enum:
      - USER
      - SYSTEM
      - API
      - ADMIN
      - AUTOMATED_PROCESS
      example: USER
    ActivityList:
      type: object
      description: Paginated list of WhatsApp Business Account activities
      required:
      - data
      properties:
        data:
          type: array
          description: Array of activity records
          items:
            $ref: '#/components/schemas/WhatsAppBusinessAccountActivity'
        paging:
          $ref: '#/components/schemas/Paging'
  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

        '