WhatsApp Schedule Management 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: Schedule Management
  description: APIs for managing WhatsApp Business Account schedules and scheduling configurations
paths:
  /{Version}/{WABA-ID}/schedules:
    get:
      summary: Get WhatsApp Business Account Schedules
      description: 'Retrieve all schedules associated with a WhatsApp Business Account, including their

        configuration, status, and execution details.


        **Use Cases:**

        - List all schedules in a WhatsApp Business Account

        - Monitor schedule status and performance

        - Check schedule configuration and timing details

        - Retrieve schedule execution history and metrics


        **Filtering:**

        You can filter results using the `filtering` parameter with JSON-encoded filter conditions.

        Supported filters include status, schedule_type, and is_active.


        **Sorting:**

        Results can be sorted by created_time or updated_time in ascending or descending order.


        **Rate Limiting:**

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


        **Caching:**

        Schedule data can be cached for short periods, but status information may change

        frequently. Implement appropriate cache invalidation strategies.'
      operationId: getWhatsAppBusinessAccountSchedules
      tags:
      - Schedule Management
      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: 'WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager

          or through the business 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. Available fields include: id, name, status,

          schedule_type, description, start_time, end_time, timezone, days_of_week,

          created_time, updated_time, is_active, recurrence_pattern

          '
        schema:
          type: string
        example: id,name,status,schedule_type,start_time,end_time
      - name: filtering
        in: query
        required: false
        description: 'JSON-encoded array of filter conditions. Each filter should specify field, operator, and value.

          Supported fields: status, schedule_type, is_active

          '
        schema:
          type: string
        example: '[{"field":"status","operator":"EQUAL","value":"ACTIVE"}]'
      - name: sort
        in: query
        required: false
        description: 'Sort field and direction. Format: field_name.asc or field_name.desc

          Supported fields: created_time, updated_time

          '
        schema:
          type: string
          enum:
          - created_time.asc
          - created_time.desc
          - updated_time.asc
          - updated_time.desc
        example: created_time.desc
      - name: limit
        in: query
        required: false
        description: Maximum number of schedules to return per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        example: 25
      - name: after
        in: query
        required: false
        description: Cursor for pagination - retrieve records after this cursor
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Cursor for pagination - retrieve records before this cursor
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved WhatsApp Business Account schedules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppBusinessAccountSchedulesConnection'
              examples:
                multiple_schedules:
                  summary: Multiple schedules with various types
                  value:
                    data:
                    - id: '1234567890123456'
                      name: Business Hours Schedule
                      status: ACTIVE
                      schedule_type: BUSINESS_HOURS
                      description: Standard business operating hours
                      start_time: 09:00
                      end_time: '17:00'
                      timezone: America/New_York
                      days_of_week:
                      - MONDAY
                      - TUESDAY
                      - WEDNESDAY
                      - THURSDAY
                      - FRIDAY
                      created_time: '2024-01-15T10:30:00Z'
                      updated_time: '2024-01-20T14:45:00Z'
                      is_active: true
                      recurrence_pattern:
                        frequency: WEEKLY
                        interval: 1
                    - id: '2345678901234567'
                      name: Weekend Maintenance
                      status: INACTIVE
                      schedule_type: MAINTENANCE_WINDOW
                      description: System maintenance window
                      start_time: 02:00
                      end_time: 04:00
                      timezone: UTC
                      days_of_week:
                      - SATURDAY
                      - SUNDAY
                      created_time: '2024-01-10T08:00:00Z'
                      updated_time: '2024-01-15T12:00:00Z'
                      is_active: false
                    paging:
                      cursors:
                        after: MTAxNTExOTQ1MjAwNzI5NDE=
                single_schedule:
                  summary: Single schedule response
                  value:
                    data:
                    - id: '1234567890123456'
                      name: Business Hours Schedule
                      status: ACTIVE
                      schedule_type: BUSINESS_HOURS
                      start_time: 09:00
                      end_time: '17:00'
                      is_active: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: filtering must be valid JSON'
                  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 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 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: Create WhatsApp Business Account Schedule
      description: 'Create a new schedule configuration within a WhatsApp Business Account. This endpoint

        allows businesses to set up automated scheduling for various operations such as business hours,

        automated responses, and maintenance windows.


        **Use Cases:**

        - Create business hours schedules for automated responses

        - Set up maintenance windows for system operations

        - Configure automated message campaigns with timing

        - Establish recurring schedule patterns for business operations


        **Prerequisites:**

        - WhatsApp Business Account must have scheduling feature enabled

        - Appropriate permissions for schedule management

        - Valid timezone and time format specifications

        - Business must meet WhatsApp Business API requirements


        **Process Flow:**

        1. Submit schedule configuration with timing and recurrence details

        2. System validates schedule parameters and conflicts

        3. Schedule is created and activated based on is_active flag

        4. Monitor schedule status through GET endpoint


        **Rate Limiting:**

        Schedule creation is subject to rate limits to prevent abuse.

        Standard Graph API rate limits also apply.


        **Validation:**

        - Start time must be before end time

        - Timezone must be valid IANA timezone identifier

        - Days of week must be valid if specified

        - Recurrence pattern must be consistent with schedule type'
      operationId: createWhatsAppBusinessAccountSchedule
      tags:
      - Schedule Management
      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: 'WhatsApp Business Account ID where the schedule will be created.

          This ID can be found in your WhatsApp Manager or through business management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleCreateRequest'
            examples:
              business_hours_schedule:
                summary: Business hours schedule creation
                value:
                  name: Business Hours Schedule
                  schedule_type: BUSINESS_HOURS
                  description: Standard business operating hours
                  start_time: 09:00
                  end_time: '17:00'
                  timezone: America/New_York
                  days_of_week:
                  - MONDAY
                  - TUESDAY
                  - WEDNESDAY
                  - THURSDAY
                  - FRIDAY
                  is_active: true
                  recurrence_pattern:
                    frequency: WEEKLY
                    interval: 1
              maintenance_window:
                summary: Maintenance window schedule
                value:
                  name: Weekend Maintenance
                  schedule_type: MAINTENANCE_WINDOW
                  description: System maintenance during off-hours
                  start_time: 02:00
                  end_time: 04:00
                  timezone: UTC
                  days_of_week:
                  - SATURDAY
                  - SUNDAY
                  is_active: false
              automated_response:
                summary: Automated response schedule
                value:
                  name: After Hours Auto-Reply
                  schedule_type: AUTOMATED_RESPONSE
                  description: Automated responses outside business hours
                  start_time: '18:00'
                  end_time: 08:00
                  timezone: America/Los_Angeles
                  days_of_week:
                  - MONDAY
                  - TUESDAY
                  - WEDNESDAY
                  - THURSDAY
                  - FRIDAY
                  - SATURDAY
                  - SUNDAY
                  is_active: true
      responses:
        '200':
          description: Successfully created schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleCreateResponse'
              examples:
                successful_creation:
                  summary: Schedule successfully created
                  value:
                    id: '1234567890123456'
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: start_time must be before end_time'
                  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 schedule limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Schedule limit exceeded for this WhatsApp Business Account
                  type: OAuthException
                  code: 200
                  error_subcode: 1349175
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Limit Exceeded
                  error_user_msg: You have reached the maximum number of schedules for this account
        '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
        '409':
          description: Conflict - Schedule name already exists or time conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Schedule name already exists in this WhatsApp Business Account
                  type: GraphMethodException
                  code: 100
                  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: 'Schedule validation failed: invalid timezone identifier'
                  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: Schedule creation rate limit exceeded
                  type: OAuthException
                  code: 4
                  error_subcode: 2446080
                  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:
    RecurrencePattern:
      type: object
      description: Pattern for recurring schedules
      properties:
        frequency:
          type: string
          enum:
          - DAILY
          - WEEKLY
          - MONTHLY
          - YEARLY
          example: WEEKLY
        interval:
          type: integer
          minimum: 1
          description: Interval between recurrences
          example: 1
        end_date:
          type: string
          format: date
          description: End date for the recurrence pattern
          example: '2024-12-31'
    WhatsAppScheduleType:
      type: string
      description: Type of schedule configuration
      enum:
      - BUSINESS_HOURS
      - AUTOMATED_RESPONSE
      - MESSAGE_CAMPAIGN
      - MAINTENANCE_WINDOW
      - CUSTOM
      example: BUSINESS_HOURS
    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
    ScheduleCreateResponse:
      type: object
      description: Response after successfully creating a schedule
      required:
      - id
      properties:
        id:
          type: string
          description: Unique identifier for the created schedule
          example: '1234567890123456'
    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
    WhatsAppScheduleStatus:
      type: string
      description: Current status of the schedule
      enum:
      - ACTIVE
      - INACTIVE
      - PAUSED
      - EXPIRED
      - DRAFT
      example: ACTIVE
    WhatsAppBusinessAccountSchedule:
      type: object
      description: WhatsApp Business Account schedule configuration and details
      required:
      - id
      - name
      - status
      - schedule_type
      properties:
        id:
          type: string
          description: Unique identifier for the schedule
          example: '1234567890123456'
        name:
          type: string
          description: Human-readable name for the schedule
          minLength: 1
          maxLength: 100
          example: Daily Business Hours Schedule
        status:
          $ref: '#/components/schemas/WhatsAppScheduleStatus'
        schedule_type:
          $ref: '#/components/schemas/WhatsAppScheduleType'
        description:
          type: string
          description: Optional description of the schedule purpose
          maxLength: 500
          example: Automated responses during business hours
        start_time:
          type: string
          format: time
          description: Schedule start time in HH:MM format
          example: 09:00
        end_time:
          type: string
          format: time
          description: Schedule end time in HH:MM format
          example: '17:00'
        timezone:
          type: string
          description: Timezone identifier for the schedule
          example: America/New_York
        days_of_week:
          type: array
          items:
            $ref: '#/components/schemas/DayOfWeek'
          description: Days of the week when the schedule is active
          example:
          - MONDAY
          - TUESDAY
          - WEDNESDAY
          - THURSDAY
          - FRIDAY
        created_time:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the schedule was created
          example: '2024-01-15T10:30:00Z'
        updated_time:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the schedule was last updated
          example: '2024-01-20T14:45:00Z'
        is_active:
          type: boolean
          description: Whether the schedule is currently active
          example: true
        recurrence_pattern:
          $ref: '#/components/schemas/RecurrencePattern'
    ScheduleCreateRequest:
      type: object
      description: Request payload for creating a new schedule
      required:
      - name
      - schedule_type
      - start_time
      - end_time
      properties:
        name:
          type: string
          description: Human-readable name for the schedule
          minLength: 1
          maxLength: 100
          example: Business Hours Schedule
        schedule_type:
          $ref: '#/components/schemas/WhatsAppScheduleType'
        description:
          type: string
          description: Optional description of the schedule purpose
          maxLength: 500
          example: Automated responses during business hours
        start_time:
          type: string
          format: time
          description: Schedule start time in HH:MM format
          example: 09:00
        end_time:
          type: string
          format: time
          description: Schedule end time in HH:MM format
          example: '17:00'
        timezone:
          type: string
          description: Timezone identifier for the schedule
          default: UTC
          example: America/New_York
        days_of_week:
          type: array
          items:
            $ref: '#/components/schemas/DayOfWeek'
          description: Days of the week when the schedule is active
          example:
          - MONDAY
          - TUESDAY
          - WEDNESDAY
          - THURSDAY
          - FRIDAY
        is_active:
          type: boolean
          description: Whether the schedule should be active upon creation
          default: true
        recurrence_pattern:
          $ref: '#/components/schemas/RecurrencePattern'
    DayOfWeek:
      type: string
      description: Day of the week
      enum:
      - MONDAY
      - TUESDAY
      - WEDNESDAY
      - THURSDAY
      - FRIDAY
      - SATURDAY
      - SUNDAY
      example: MONDAY
    WhatsAppBusinessAccountSchedulesConnection:
      type: object
      description: Paginated collection of WhatsApp Business Account schedules
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WhatsAppBusinessAccountSchedule'
          description: Array of schedule records
        paging:
          $ref: '#/components/schemas/CursorPaging'
  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

        '