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

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

## 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 six operations cover call session commands and media download. Command acceptance is not final call state, and downloaded media remains a separate handoff.
- Operation coverage: `6`

## Operations

### `POST /whatsapp/calls/accept` — `whatsapp_call-accept`

- Summary: Accept a call
- Description:
  > Accepts an inbound WhatsApp call.
  >
  > Once the WebRTC connection is made, this endpoint is used to accept the call.
  > Media will begin flowing immediately since the connection was established prior to call connect.
- Parameters: none
- Request body: required
  - `application/json`: `#/components/schemas/WhatsappCallingPreAcceptRequest`
    - `$ref`: `#/components/schemas/WhatsappCallingPreAcceptRequest`
- Responses:
  - `200`: The call accept request is successfully processed.
    - `application/json`: `#/components/schemas/WhatsappCallingResponse`
      - `$ref`: `#/components/schemas/WhatsappCallingResponse`
  - `400`: Bad request. Invalid request parameters.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `POST /whatsapp/calls/connect` — `whatsapp_call-connect`

- Summary: Connect a call
- Description:
  > Initiates a WhatsApp call connection.
  >
  > Establishes the initial connection for a WhatsApp call by providing SDP offer information.
  > This endpoint is used for business-initiated calling scenarios.
- Parameters: none
- Request body: required
  - `application/json`: `#/components/schemas/WhatsappCallingConnectRequest`
    - `$ref`: `#/components/schemas/WhatsappCallingConnectRequest`
- Responses:
  - `200`: The call connection request is successfully accepted.
    - `application/json`: `#/components/schemas/WhatsappCallingResponse`
      - `$ref`: `#/components/schemas/WhatsappCallingResponse`
  - `400`: Bad request. Invalid request parameters.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `GET /whatsapp/calls/media/{mediaAssetId}` — `whatsapp_call-download-media`

- Summary: Download call media
- Description:
  > Downloads an available recording or transcription generated for an API-sourced WhatsApp call.
  >
  > Media can be downloaded only by the owning tenant for 30 days from its creation time. Requests without a Range header or with a blank Range header return the complete file as a download attachment with HTTP 200. A non-empty Range header is rejected with HTTP 400 because byte-range downloads are not supported.
- Parameters:
  - `mediaAssetId` (path, required): `string`
    > YCloud call media asset ID received in a recording or transcription webhook.
    - Constraints: example="66b1f0c2e4b05c2d8f1a3b47"
- Request body: none
- Responses:
  - `200`: The complete recording or transcription file.
    - `application/json`: `string (binary)`
    - `audio/ogg`: `string (binary)`
  - `400`: The request includes a non-empty Range header. Byte-range downloads are not supported.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`
  - `404`: The media asset does not exist, is not available, is expired, or does not belong to the authenticated tenant.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `POST /whatsapp/calls/preAccept` — `whatsapp_call-pre-accept`

- Summary: Pre-accept a call
- Description:
  > Pre-accepts an inbound WhatsApp call.
  >
  > Pre-accepting calls allows the calling media connection to be established before
  > attempting to send call media through the connection. This facilitates faster
  > connection times and avoids audio clipping issues.
- Parameters: none
- Request body: required
  - `application/json`: `#/components/schemas/WhatsappCallingPreAcceptRequest`
    - `$ref`: `#/components/schemas/WhatsappCallingPreAcceptRequest`
- Responses:
  - `200`: The call pre-accept request is successfully processed.
    - `application/json`: `#/components/schemas/WhatsappCallingResponse`
      - `$ref`: `#/components/schemas/WhatsappCallingResponse`
  - `400`: Bad request. Invalid request parameters.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `POST /whatsapp/calls/reject` — `whatsapp_call-reject`

- Summary: Reject a call
- Description:
  > Rejects an inbound WhatsApp call.
  >
  > This endpoint is used to reject an incoming call from a WhatsApp user.
  > The call will be terminated on the WhatsApp user side with appropriate notification.
- Parameters: none
- Request body: required
  - `application/json`: `#/components/schemas/WhatsappCallingTerminateRequest`
    - `$ref`: `#/components/schemas/WhatsappCallingTerminateRequest`
- Responses:
  - `200`: The call rejection request is successfully processed.
    - `application/json`: `#/components/schemas/WhatsappCallingResponse`
      - `$ref`: `#/components/schemas/WhatsappCallingResponse`
  - `400`: Bad request. Invalid request parameters.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `POST /whatsapp/calls/terminate` — `whatsapp_call-terminate`

- Summary: Terminate a call
- Description:
  > Terminates an active WhatsApp call.
  >
  > Both the business or the WhatsApp user can terminate the call at any time.
  > This endpoint is used by the business to end the call.
- Parameters: none
- Request body: required
  - `application/json`: `#/components/schemas/WhatsappCallingTerminateRequest`
    - `$ref`: `#/components/schemas/WhatsappCallingTerminateRequest`
- Responses:
  - `200`: The call termination request is successfully processed.
    - `application/json`: `#/components/schemas/WhatsappCallingResponse`
      - `$ref`: `#/components/schemas/WhatsappCallingResponse`
  - `400`: Bad request. Invalid request parameters.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

## Referenced schema and parameter shapes

### `Error`

- Reference: `#/components/schemas/Error`
- Shape: `object`
  - Required properties: `status`, `code`
  - Properties:
    - `code`: `string` (required)
      - Description:
        > One of a server-defined error codes. Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported.
      - Constraints: example="NOT_FOUND"
    - `docUrl`: `string`
      - Description:
        > A URL to more information about the error.
      - Constraints: example=""
    - `message`: `string`
      - Description:
        > A human-readable representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users.
      - Constraints: example="The requested resource does not exist."
    - `requestId`: `string`
      - Description:
        > Each API request has an associated request ID. It conveys the response header `YCloud-Request-ID` used for the convenience of the consumer.
      - Constraints: example="req_1KjtKI80IKoaJNa6n6p"
    - `status`: `integer (int32)` (required)
      - Description:
        > HTTP status code, [RFC 7231, Section 6](https://datatracker.ietf.org/doc/html/rfc7231#section-6). It conveys the HTTP status code used for the convenience of the consumer.
      - Constraints: pattern="[45]\\d{2}"; example=404
    - `target`: `string`
      - Description:
        > The target of the error.
      - Constraints: example=""
    - `whatsappApiError`: `#/components/schemas/WhatsappApiError`
      - Description:
        > The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
        >
        > Note: This field is returned if we tried to request the WhatsApp Business API and got an error response.

### `ErrorResponse`

- Reference: `#/components/schemas/ErrorResponse`
- Shape: `object`
  - Required properties: `error`
  - Properties:
    - `error`: `#/components/schemas/Error` (required)

### `WhatsappApiError`

- Reference: `#/components/schemas/WhatsappApiError`
- Shape: `object`
  - Description:
    > The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
  - Required properties: `message`, `code`
  - Properties:
    - `code`: `string` (required)
      - Description:
        > An error code.
      - Constraints: example=200002
    - `error_data`: `object`
      - Description:
        > Additional data about the error. A string or map.
        > - For template APIs, this field is a string describing the reason for the error.
        > - For message APIs, this field is a map with property `details` describing the reason for the error.
    - `error_subcode`: `string`
      - Description:
        > Additional code about the error.
      - Constraints: example=2388109
    - `error_user_msg`: `string`
      - Description:
        > The message to display to the user. The language of the message is based on the locale of the API request.
      - Constraints: example="This message template cannot be created."
    - `error_user_title`: `string`
      - Description:
        > The title of the dialog, if shown. The language of the message is based on the locale of the API request.
      - Constraints: example="Message Cannot Be Submitted"
    - `fbtrace_id`: `string`
      - Description:
        > Internal support identifier. When reporting a bug related to a Graph API call, include the fbtrace_id to help us find log data for debugging.
      - Constraints: example="AVGjJ7ia2zJkrHG"
    - `is_transient`: `boolean`
      - Description:
        > Whether the error is transient.
      - Constraints: example=false
    - `message`: `string` (required)
      - Description:
        > A human-readable description of the error.
      - Constraints: example="HSM Template creation failed"
    - `type`: `string`
      - Description:
        > Error type.
      - Constraints: example="OAuthException"

### `WhatsappCallingConnectRequest`

- Reference: `#/components/schemas/WhatsappCallingConnectRequest`
- Shape: `object`
  - Description:
    > Provide exactly one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored.
  - Required properties: `from`, `sdpType`, `sdp`
  - Properties:
    - `from`: `string` (required)
      - Description:
        > The caller's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
      - Constraints: example="+6283138205150"
    - `recipient`: `string`
      - Description:
        > The callee's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided.
      - Constraints: example="US.1234"
    - `sdp`: `string` (required)
      - Description:
        > The Session Description Protocol (SDP) offer information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866).
        > Contains media session parameters for establishing the WebRTC connection.
      - Constraints: example="v=0\r\no=- 4054442297240208280 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0\r\na=extmap-allow-mixed\r\na=msid-semantic: WMS 6c364341-f90d-48e6-b497-76e047e3c31a\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 13 110 126\r\nc=IN IP4 0.0.0.0\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=ice-ufrag:Dpsa\r\na=ice-pwd:oVuOd7HKhA8aWTvspLYACWJe\r\na=ice-options:trickle\r\na=fingerprint:sha-256 0A:A9:64:82:AD:D5:31:08:38:71:1C:C0:08:AA:CE:93:22:F4:17:2C:B6:F1:8F:F1:20:71:38:16:37:18:3F:FA\r\na=setup:actpass\r\na=mid:0\r\na=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level\r\na=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time\r\na=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid\r\na=sendrecv\r\na=msid:6c364341-f90d-48e6-b497-76e047e3c31a fa42cdbe-8696-4ee8-bce0-0919d86a223f\r\na=rtcp-mux\r\na=rtcp-rsize\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 minptime=10;useinbandfec=1\r\na=rtpmap:63 red/48000/2\r\na=fmtp:63 111/111\r\na=rtpmap:9 G722/8000\r\na=rtpmap:0 PCMU/8000\r\na=rtpmap:8 PCMA/8000\r\na=rtpmap:13 CN/8000\r\na=rtpmap:110 telephone-event/48000\r\na=rtpmap:126 telephone-event/8000\r\na=ssrc:3208712354 cname:bg/Ix8uTnsTsiMoe\r\na=ssrc:3208712354 msid:6c364341-f90d-48e6-b497-76e047e3c31a fa42cdbe-8696-4ee8-bce0-0919d86a223f\r\n"
    - `sdpType`: `string` (required)
      - Description:
        > The SDP type, must be "offer" for connection requests.
      - Constraints: enum=["offer"]; example="offer"
    - `to`: `string`
      - Description:
        > The callee's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided.
      - Constraints: example="+6281361905133"

### `WhatsappCallingPreAcceptRequest`

- Reference: `#/components/schemas/WhatsappCallingPreAcceptRequest`
- Shape: `object`
  - Required properties: `phoneId`, `wacid`, `sdpType`, `sdp`
  - Properties:
    - `phoneId`: `string` (required)
      - Description:
        > The WhatsApp Business phone number ID.
      - Constraints: example="461269257068832"
    - `sdp`: `string` (required)
      - Description:
        > The Session Description Protocol (SDP) information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866).
        > Contains media session parameters for the WebRTC connection.
      - Constraints: example="v=0\r\no=- 2239925877841361960 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\na=msid-semantic: WMS 0ed5100f-da68-4193-8865-146c1ac7a087\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111 126\r\nc=IN IP4 0.0.0.0\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=ice-ufrag:NCH6\r\na=ice-pwd:ogUYxqJDPNn0C5RFif6UlLz6\r\na=ice-options:trickle\r\na=fingerprint:sha-256 5B:95:C4:E4:8B:2B:06:B6:DB:FB:2C:08:2F:FD:3B:C7:9C:8D:84:4C:97:8D:84:AC:B2:93:32:B8:20:5C:3C:85\r\na=setup:active\r\na=mid:audio\r\na=sendrecv\r\na=msid:0ed5100f-da68-4193-8865-146c1ac7a087 bc955459-4bae-4504-99c8-348944c12b6f\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 minptime=10;useinbandfec=1\r\na=rtpmap:126 telephone-event/8000\r\na=ssrc:436995058 cname:BIzAP4IgR06SrZ1S\r\n"
    - `sdpType`: `string` (required)
      - Description:
        > The SDP type for pre-accept operations. Must be "answer".
      - Constraints: enum=["answer"]; example="answer"
    - `wacid`: `string` (required)
      - Description:
        > The WhatsApp call ID. Required for inbound call operations.
        > This ID is received from the Call Connect webhook when a WhatsApp user initiates the call.
      - Constraints: example="wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIDhEMjc4NEY2QUU4NTA2MTgxNTBGNzQ3N0M4QTBDMTU5HBgNNjI4MzEzODIwNTE1MBUCABUeAA=="

### `WhatsappCallingResponse`

- Reference: `#/components/schemas/WhatsappCallingResponse`
- Shape: `object`
  - Required properties: `success`
  - Properties:
    - `success`: `boolean` (required)
      - Description:
        > Indicates whether the calling operation was successful.
      - Constraints: example=true
    - `wacid`: `string`
      - Description:
        > The WhatsApp call ID associated with this calling operation.
      - Constraints: example="wacid.HBgNNjI4MTM2MTkwNTEzMxUCABEYIDNENjg2OEMzNTFFRDkwRkUxRUE1RTgxNjY1NjJCQUJBHBgNNjI4MzEzODIwNTE1MBUCABUeAA=="

### `WhatsappCallingTerminateRequest`

- Reference: `#/components/schemas/WhatsappCallingTerminateRequest`
- Shape: `object`
  - Required properties: `phoneId`, `wacid`
  - Properties:
    - `phoneId`: `string` (required)
      - Description:
        > The WhatsApp Business phone number ID.
      - Constraints: example="461269257068832"
    - `wacid`: `string` (required)
      - Description:
        > The WhatsApp call ID. Required for terminate operations.
        > This ID is received from the Call Connect webhook when a WhatsApp user initiates the call.
      - Constraints: example="wacid.HBgNNjI4MTM2MTkwNTEzMxUCABEYIDNENjg2OEMzNTFFRDkwRkUxRUE1RTgxNjY1NjJCQUJBHBgNNjI4MzEzODIwNTE1MBUCABUeAA=="

## 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.