skills/ycloud-whatsapp-flows/references/openapi.md

<!-- Generated by scripts/build_openapi_skill_references.py; do not edit. -->
# OpenAPI contract: WhatsApp flows

## Provenance

- Source: `ycloud-api-v2.yaml` (pinned release snapshot).
- Source SHA-256: `8592bd4cc37186655a480dd86ce6bac6731543727327a2871d9103a0b8ed9e81`
- OpenAPI version: `3.0.0`
- API info.version: `v2`
- This derived reference does not replace the upstream API Owner's canonical source.
- Generated deterministically from normalized JSON; do not edit this file by hand.

## Scope and handoff

- These nine operations cover Flow creation, retrieval, preview, metadata/assets, publish, deprecate, and delete. Lifecycle evidence must precede a Messages handoff.
- Operation coverage: `9`

## Operations

### `POST /whatsapp/flows` — `whatsapp_flow-create`

- Summary: Create a flow
- Description:
  > Creates a new WhatsApp Flow. New Flows are by default created in DRAFT state. You can create a new published Flow in single request by specifying flowJson and publish parameters.
- Parameters: none
- Request body: required
  - `application/json`: `object`
    - Required properties: `wabaId`, `name`, `categories`
    - Properties:
      - `categories`: `array` (required)
        - Description:
          > Flow categories.
        - Items: `#/components/schemas/WhatsappFlowCategory`
      - `cloneFlowId`: `string`
        - Description:
          > ID of source Flow to clone. You must have permission to access the specified Flow.
        - Constraints: example="flow-id-to-clone"
      - `endpointUri`: `string`
        - Description:
          > The endpoint URI for the Flow.
        - Constraints: example="https://example.com/flow-endpoint"
      - `flowJson`: `string`
        - Description:
          > JSON string of the Flow structure.
        - Constraints: example="{\"version\":\"5.0\",\"screens\":[{\"id\":\"WELCOME_SCREEN\",\"layout\":{\"type\":\"SingleColumnLayout\",\"children\":[{\"type\":\"TextHeading\",\"text\":\"Hello World\"},{\"type\":\"Footer\",\"label\":\"Complete\",\"on-click-action\":{\"name\":\"complete\",\"payload\":{}}}]},\"title\":\"Welcome\",\"terminal\":true,\"success\":true,\"data\":{}}]}"
      - `name`: `string` (required)
        - Description:
          > Flow name.
        - Constraints: example="My first flow"
      - `publish`: `boolean`
        - Description:
          > If true, the Flow will be created in PUBLISHED state.
        - Constraints: default=false
      - `wabaId`: `string` (required)
        - Description:
          > WhatsApp Business Account ID.
        - Constraints: example="whatsapp-business-account-id"
- Responses:
  - `200`: Successfully created a flow.
    - `application/json`: `object`
      - Properties:
        - `id`: `string`
          - Description:
            > The ID of the created Flow.
          - Constraints: example="flow-1"
        - `success`: `boolean`
          - Description:
            > Whether the operation was successful.
          - Constraints: example=true
  - `400`: Bad request. The Flow may be invalid.
    - `application/json`: `object`
      - Properties:
        - `success`: `boolean`
          - Description:
            > Whether the operation was successful.
          - Constraints: example=false
        - `validationErrors`: `array`
          - Description:
            > List of validation errors.
          - Items: `#/components/schemas/WhatsappFlowValidationError`

### `DELETE /whatsapp/flows/{flowId}` — `whatsapp_flow-delete`

- Summary: Delete a flow
- Description:
  > Deletes a WhatsApp Flow. Only Flows in DRAFT status can be deleted.
- Parameters:
  - `flowId` (path, required): `string`
    > Flow ID.
    - Constraints: example="flow-1"
- Request body: none
- Responses:
  - `200`: Successfully deleted the flow.
    - `application/json`: `object`
      - Properties:
        - `success`: `boolean`
          - Description:
            > Whether the operation was successful.
          - Constraints: example=true

### `POST /whatsapp/flows/{flowId}/deprecate` — `whatsapp_flow-deprecate`

- Summary: Deprecate a flow
- Description:
  > Marks a published Flow as deprecated. Once a Flow is published, it cannot be modified or deleted, but can be marked as deprecated.
- Parameters:
  - `flowId` (path, required): `string`
    > Flow ID.
    - Constraints: example="flow-1"
- Request body: none
- Responses:
  - `200`: Successfully deprecated the flow.
    - `application/json`: `object`
      - Properties:
        - `success`: `boolean`
          - Description:
            > Whether the operation was successful.
          - Constraints: example=true

### `GET /whatsapp/flows` — `whatsapp_flow-list`

- Summary: List flows
- Description:
  > Returns a list of WhatsApp Flows under a WhatsApp Business Account (WABA).
- Parameters:
  - `wabaId` (query, required): `string`
    > WhatsApp Business Account ID.
    - Constraints: example="whatsapp-business-account-id"
- Request body: none
- Responses:
  - `200`: Successfully retrieved the list of flows.
    - `application/json`: `object`
      - Properties:
        - `items`: `array`
          - Description:
            > List of flows.
          - Items: `#/components/schemas/WhatsappListFlowItem`

### `GET /whatsapp/flows/{flowId}/preview` — `whatsapp_flow-preview`

- Summary: generate a web preview URL with this flow.
- Description:
  > In order to visualize the Flows created, you can generate a web preview URL with this request. **The preview URL is public and can be shared with different stakeholders to visualize the Flow.**.
- Parameters:
  - `flowId` (path, required): `string`
    > Flow ID.
    - Constraints: example="flow-1"
  - `invalidate` (query, optional): `boolean`
    > the link will expire in 30 days in default, or if you set with invalidate=true which will generate a new link.
    - Constraints: example=false
- Request body: none
- Responses:
  - `200`: Successfully generate the flow preview url.
    - `application/json`: `#/components/schemas/WhatsappFlowPreviewUrl`
      - `$ref`: `#/components/schemas/WhatsappFlowPreviewUrl`

### `POST /whatsapp/flows/{flowId}/publish` — `whatsapp_flow-publish`

- Summary: Publish a flow
- Description:
  > Updates the status of the Flow to "PUBLISHED". You can either edit this flow in the future and turn it back to the "DRAFT" state, or create a new flow by specifying the existing Flow ID as the cloneFlowId parameter.
- Parameters:
  - `flowId` (path, required): `string`
    > Flow ID.
    - Constraints: example="flow-1"
- Request body: none
- Responses:
  - `200`: Successfully published the flow.
    - `application/json`: `object`
      - Properties:
        - `success`: `boolean`
          - Description:
            > Whether the operation was successful.
          - Constraints: example=true

### `GET /whatsapp/flows/{flowId}` — `whatsapp_flow-retrieve`

- Summary: Retrieve a flow
- Description:
  > Retrieves a WhatsApp Flow's details.
- Parameters:
  - `flowId` (path, required): `string`
    > Flow ID.
    - Constraints: example="flow-1"
- Request body: none
- Responses:
  - `200`: Successfully retrieved the flow.
    - `application/json`: `#/components/schemas/WhatsappFlow`
      - `$ref`: `#/components/schemas/WhatsappFlow`

### `PATCH /whatsapp/flows/{flowId}/metadata` — `whatsapp_flow-update-metadata`

- Summary: Update flow metadata
- Description:
  > Updates a WhatsApp Flow's metadata (name or categories).
- Parameters:
  - `flowId` (path, required): `string`
    > Flow ID.
    - Constraints: example="flow-1"
- Request body: required
  - `application/json`: `object`
    - Properties:
      - `categories`: `array`
        - Description:
          > Flow categories.
        - Items: `#/components/schemas/WhatsappFlowCategory`
      - `endpointUri`: `string`
        - Description:
          > The endpoint URI for the Flow.
        - Constraints: example="https://example.com/flow-endpoint"
      - `name`: `string`
        - Description:
          > Flow name.
        - Constraints: example="New flow name"
- Responses:
  - `200`: Successfully updated the flow metadata.
    - `application/json`: `object`
      - Properties:
        - `success`: `boolean`
          - Description:
            > Whether the operation was successful.
          - Constraints: example=true

### `PATCH /whatsapp/flows/{flowId}/assets` — `whatsapp_flow-update-structure`

- Summary: Update flow structure
- Description:
  > Updates a WhatsApp Flow's structure. Note that the file must be attached as form-data.
- Parameters:
  - `flowId` (path, required): `string`
    > Flow ID.
    - Constraints: example="flow-1"
- Request body: required
  - `multipart/form-data`: `object`
    - Required properties: `flowJson`
    - Properties:
      - `flowJson`: `string (binary)` (required)
        - Description:
          > JSON file containing the Flow structure.
- Responses:
  - `200`: Successfully updated the flow structure.
    - `application/json`: `object`
      - Properties:
        - `success`: `boolean`
          - Description:
            > Whether the operation was successful.
          - Constraints: example=true
  - `400`: Bad request. The Flow structure may be invalid.
    - `application/json`: `object`
      - Properties:
        - `success`: `boolean`
          - Description:
            > Whether the operation was successful.
          - Constraints: example=false
        - `validationErrors`: `array`
          - Description:
            > List of validation errors.
          - Items: `#/components/schemas/WhatsappFlowValidationError`

## Referenced schema and parameter shapes

### `WhatsappFlow`

- Reference: `#/components/schemas/WhatsappFlow`
- Shape: `object`
  - Description:
    > Represents a WhatsApp Flow.
  - Properties:
    - `categories`: `array`
      - Description:
        > Flow categories.
      - Items: `#/components/schemas/WhatsappFlowCategory`
    - `dataApiVersion`: `string`
      - Description:
        > Version of the Data API.
      - Constraints: example="3.0"
    - `endpointUri`: `string`
      - Description:
        > The endpoint URI for the Flow.
      - Constraints: example="https://example.com/flow-endpoint"
    - `id`: `string`
      - Description:
        > Flow ID.
      - Constraints: example="flow-1"
    - `jsonVersion`: `string`
      - Description:
        > Version of the Flow JSON structure.
      - Constraints: example="3.0"
    - `name`: `string`
      - Description:
        > Flow name.
      - Constraints: example="My first flow"
    - `status`: `#/components/schemas/WhatsappFlowStatus`
    - `validationErrors`: `array`
      - Description:
        > List of validation errors.
      - Items: `#/components/schemas/WhatsappFlowValidationError`
    - `whatsappBusinessAccount`: `object`
      - Description:
        > WhatsApp Business Account information.

### `WhatsappFlowCategory`

- Reference: `#/components/schemas/WhatsappFlowCategory`
- Shape: `string`
  - Description:
    > Category of the WhatsApp Flow.
    > - `SIGN_UP`: For sign-up processes.
    > - `SIGN_IN`: For sign-in processes.
    > - `APPOINTMENT_BOOKING`: For booking appointments.
    > - `LEAD_GENERATION`: For lead generation.
    > - `CONTACT_US`: For contact forms.
    > - `CUSTOMER_SUPPORT`: For customer support.
    > - `SURVEY`: For surveys.
    > - `OTHER`: For other purposes.
  - Constraints: enum=["SIGN_UP", "SIGN_IN", "APPOINTMENT_BOOKING", "LEAD_GENERATION", "CONTACT_US", "CUSTOMER_SUPPORT", "SURVEY", "OTHER"]

### `WhatsappFlowPreviewUrl`

- Reference: `#/components/schemas/WhatsappFlowPreviewUrl`
- Shape: inline schema
  - Properties:
    - `expiresAt`: `string (date-time)`
      - Constraints: example="2022-03-01T12:00:00.000Z"
    - `previewUrl`: `string`
      - Description:
        > The flow preview url
      - Constraints: example="https://business.facebook.com/wa/manage/flows/123456/preview/?token=xxxx"

### `WhatsappFlowStatus`

- Reference: `#/components/schemas/WhatsappFlowStatus`
- Shape: `string`
  - Description:
    > Status of the WhatsApp Flow.
    > - `DRAFT`: The Flow is in draft state and can be modified.
    > - `PUBLISHED`: The Flow is published and cannot be modified.
    > - `DEPRECATED`: The Flow is deprecated and cannot be used.
  - Constraints: enum=["DRAFT", "PUBLISHED", "DEPRECATED"]

### `WhatsappFlowValidationError`

- Reference: `#/components/schemas/WhatsappFlowValidationError`
- Shape: `object`
  - Description:
    > Represents a validation error in a WhatsApp Flow.
  - Properties:
    - `columnEnd`: `integer`
      - Description:
        > End column of the error.
      - Constraints: example=34
    - `columnStart`: `integer`
      - Description:
        > Start column of the error.
      - Constraints: example=21
    - `error`: `string`
      - Description:
        > Error code.
      - Constraints: example="INVALID_PROPERTY_VALUE"
    - `errorType`: `string`
      - Description:
        > Error type.
      - Constraints: example="FLOW_JSON_ERROR"
    - `lineEnd`: `integer`
      - Description:
        > End line of the error.
      - Constraints: example=10
    - `lineStart`: `integer`
      - Description:
        > Start line of the error.
      - Constraints: example=10
    - `message`: `string`
      - Description:
        > Error message.
      - Constraints: example="Invalid value found for property 'type'."
    - `pointers`: `array`
      - Description:
        > List of pointers to the error location.
      - Items: `object`

### `WhatsappListFlowItem`

- Reference: `#/components/schemas/WhatsappListFlowItem`
- Shape: `object`
  - Description:
    > Represents a list item of WhatsApp Flows.
  - Properties:
    - `categories`: `array`
      - Description:
        > Flow categories.
      - Items: `#/components/schemas/WhatsappFlowCategory`
    - `id`: `string`
      - Description:
        > Flow ID.
      - Constraints: example="flow-1"
    - `name`: `string`
      - Description:
        > Flow name.
      - Constraints: example="My first flow"
    - `status`: `#/components/schemas/WhatsappFlowStatus`
    - `validationErrors`: `array`
      - Description:
        > List of validation errors.
      - Items: `#/components/schemas/WhatsappFlowValidationError`

## Codegen interpretation and unknowns

- `operationId` identifies the OpenAPI operation; it is not an SDK method name.
- `allOf` is wire-level schema composition. Response adapters must merge inherited and local properties; generated model inheritance/flattening is only a codegen shape, not additional API behavior.
- `x-group-parameters`, `x-enum-varnames`, and `x-enum-descriptions` are generator hints, not business rules.
- Description-only constraints (including conditional fields, precedence, and endpoint-specific behavior) remain verbatim above.
- This OpenAPI snapshot does not confirm cross-cutting error, retry/`Retry-After`, rate-limit, idempotency, delivery, or webhook-signature behavior. Consult the reviewed `runtime.md`; if neither source confirms a fact, do not fill it in.