WhatsApp Solution Migration 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: Solution Migration
  description: APIs for managing Multi-Partner Solution migration processes
paths:
  /{Version}/{WABA-ID}/set_solution_migration_intent:
    post:
      summary: Set Solution Migration Intent
      description: 'Set migration intent for a Multi-Partner Solution associated with a WhatsApp Business Account.

        This endpoint allows solution partners to initiate, schedule, confirm, or cancel migration

        processes for their solutions.


        **Use Cases:**

        - Initiate migration process for solution transitions

        - Schedule migration for a specific time

        - Confirm pending migration requests

        - Cancel previously set migration intents


        **Rate Limiting:**

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


        **Migration Process:**

        1. Set migration intent with INITIATE_MIGRATION

        2. System validates migration eligibility

        3. Migration intent enters PENDING status

        4. Partner can schedule or confirm migration

        5. Migration executes at scheduled time or immediately upon confirmation'
      operationId: setSolutionMigrationIntent
      tags:
      - Solution Migration
      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 identifies the WABA for which the solution

          migration intent is being set.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetSolutionMigrationIntentRequest'
            examples:
              initiate_migration:
                summary: Initiate solution migration
                value:
                  solution_id: '1234567890123456'
                  migration_intent: INITIATE_MIGRATION
                  target_solution_id: '2345678901234567'
                  migration_reason: Migrating to new solution provider for enhanced features
              schedule_migration:
                summary: Schedule solution migration
                value:
                  solution_id: '1234567890123456'
                  migration_intent: SCHEDULE_MIGRATION
                  target_solution_id: '2345678901234567'
                  scheduled_migration_time: '2024-12-01T10:00:00Z'
                  migration_reason: Scheduled migration during maintenance window
              cancel_migration:
                summary: Cancel solution migration
                value:
                  solution_id: '1234567890123456'
                  migration_intent: CANCEL_MIGRATION
                  migration_reason: Migration cancelled due to business requirements change
      responses:
        '200':
          description: Successfully set solution migration intent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetSolutionMigrationIntentResponse'
              examples:
                migration_initiated:
                  summary: Migration intent successfully initiated
                  value:
                    success: true
                    migration_intent_id: migration_intent_123456789
                    status: PENDING
                    estimated_completion_time: '2024-12-01T12:00:00Z'
                migration_scheduled:
                  summary: Migration intent successfully scheduled
                  value:
                    success: true
                    migration_intent_id: migration_intent_987654321
                    status: SCHEDULED
                    estimated_completion_time: '2024-12-01T10:00:00Z'
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: solution_id must be a valid numeric string'
                  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 set migration intent for this solution
                  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 - WABA ID or Solution ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account or Solution 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: Migration intent cannot be set for solution in current state
                  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:
    SetSolutionMigrationIntentResponse:
      type: object
      description: Response for setting solution migration intent
      required:
      - success
      - migration_intent_id
      properties:
        success:
          type: boolean
          description: Indicates if the migration intent was set successfully
          example: true
        migration_intent_id:
          type: string
          description: Unique identifier for the migration intent request
          example: migration_intent_123456789
        status:
          type: string
          description: Current status of the migration intent
          enum:
          - PENDING
          - APPROVED
          - REJECTED
          - SCHEDULED
          example: PENDING
        estimated_completion_time:
          type: string
          format: date-time
          description: Estimated completion time for the migration (ISO 8601 format)
          example: '2024-12-01T12:00:00Z'
    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
    SetSolutionMigrationIntentRequest:
      type: object
      description: Request payload for setting solution migration intent
      required:
      - solution_id
      - migration_intent
      properties:
        solution_id:
          type: string
          description: Unique identifier for the Multi-Partner Solution
          pattern: ^[0-9]+$
          example: '1234567890123456'
        migration_intent:
          $ref: '#/components/schemas/SolutionMigrationIntent'
        target_solution_id:
          type: string
          description: Target solution ID for migration (required for certain migration intents)
          pattern: ^[0-9]+$
          example: '2345678901234567'
        migration_reason:
          type: string
          description: Reason for the migration intent
          maxLength: 500
          example: Migrating to new solution provider for enhanced features
        scheduled_migration_time:
          type: string
          format: date-time
          description: Scheduled time for migration execution (ISO 8601 format)
          example: '2024-12-01T10:00:00Z'
    SolutionMigrationIntent:
      type: string
      description: Intent for solution migration
      enum:
      - INITIATE_MIGRATION
      - CANCEL_MIGRATION
      - CONFIRM_MIGRATION
      - SCHEDULE_MIGRATION
      example: INITIATE_MIGRATION
  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

        '