skills/ycloud-unsubscribers/references/openapi.md

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

## 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 five operations cover customer/channel unsubscribe state. Eligibility evidence is an input to project send policy, not a provider delivery result.
- Operation coverage: `5`

## Operations

### `POST /unsubscribers` — `unsubscriber-create`

- Summary: Create an unsubscriber
- Description:
  > Creates an unsubscriber.
  > An unsubscriber is a configuration item representing that customers opt out of receiving messages from your business.
  > **A customer and a channel form a unique identifier for an unsubscriber.**
- Parameters: none
- Request body: required
  - `application/json`: `#/components/schemas/UnsubscriberCreateRequest`
    - `$ref`: `#/components/schemas/UnsubscriberCreateRequest`
- Responses:
  - `200`: Successfully created an unsubscriber.
    - `application/json`: `#/components/schemas/Unsubscriber`
      - `$ref`: `#/components/schemas/Unsubscriber`

### `DELETE /unsubscribers/{customer}/{channel}` — `unsubscriber-delete-by-customer-and-channel`

- Summary: Delete an unsubscriber
- Description:
  > Deletes the unsubscriber for the specified customer and channel.
- Parameters:
  - `customer` (path, required): `string`
    > The customer who has opted out.
    - Constraints: example="+16315551111"
  - `channel` (path, required): `#/components/schemas/UnsubscriberChannel`
    - `$ref`: `#/components/schemas/UnsubscriberChannel`
- Request body: none
- Responses:
  - `200`: Successfully deleted the unsubscriber.
    - `application/json`: `#/components/schemas/Unsubscriber`
      - `$ref`: `#/components/schemas/Unsubscriber`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `GET /unsubscribers` — `unsubscriber-list`

- Summary: List unsubscribers
- Description:
  > Returns a paginated list of unsubscribers.
- Parameters:
  - `page` (query, optional): `integer (int32)`
    > Page number of the results to be returned, 1-based.
    - Constraints: minimum=1; maximum=100; default=1
  - `limit` (query, optional): `integer (int32)`
    > A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
    - Constraints: minimum=1; maximum=100; default=10
  - `includeTotal` (query, optional): `boolean`
    > Return results inside an object that contains the total result count or not.
    - Constraints: default=false
  - `pageAfter` (query, optional): `string`
    > A cursor to fetch the next page in cursor pagination.
    > For example, if you make a list request, receive 100 objects and `cursor.after=id:foo`, your subsequent call can include `pageAfter=id:foo` in order to fetch the next page of the list.
    - Constraints: example="id:foo"
  - `filter.customer` (query, optional): `string`
    - Description:
      > The customer who has opted out.
    - Constraints: example="+16315551111"
  - `filter.channel` (query, optional): `#/components/schemas/UnsubscriberChannel`
    - `$ref`: `#/components/schemas/UnsubscriberChannel`
  - `filter.regionCode` (query, optional): `string`
    - Description:
      > Region code, formatted in [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
- Request body: none
- Responses:
  - `200`: Successfully retrieved a paginated list of objects.
    - `application/json`: `#/components/schemas/UnsubscriberPage`
      - `$ref`: `#/components/schemas/UnsubscriberPage`

### `GET /unsubscribers/{customer}` — `unsubscriber-list-all-by-customer`

- Summary: List all unsubscribers by customer
- Description:
  > Returns all unsubscribers for the specified customer.
- Parameters:
  - `customer` (path, required): `string`
    > The customer who has opted out.
    - Constraints: example="+16315551111"
- Request body: none
- Responses:
  - `200`: Successfully retrieved the unsubscribers.
    - `application/json`: `array`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `GET /unsubscribers/{customer}/{channel}` — `unsubscriber-retrieve-by-customer-and-channel`

- Summary: Retrieve an unsubscriber
- Description:
  > Retrieves the unsubscriber for the specified customer and channel.
- Parameters:
  - `customer` (path, required): `string`
    > The customer who has opted out.
    - Constraints: example="+16315551111"
  - `channel` (path, required): `#/components/schemas/UnsubscriberChannel`
    - `$ref`: `#/components/schemas/UnsubscriberChannel`
- Request body: none
- Responses:
  - `200`: Successfully retrieved the unsubscribers.
    - `application/json`: `#/components/schemas/Unsubscriber`
      - `$ref`: `#/components/schemas/Unsubscriber`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

## Referenced schema and parameter shapes

### `channel-in_path_for_unsubscriber`

- Reference: `#/components/parameters/channel-in_path_for_unsubscriber`
- Parameter name: `channel`
- Location: `path`
- Required: `true`
- Schema: `#/components/schemas/UnsubscriberChannel`
  - `$ref`: `#/components/schemas/UnsubscriberChannel`

### `customer-in_path_for_unsubscriber`

- Reference: `#/components/parameters/customer-in_path_for_unsubscriber`
- Parameter name: `customer`
- Location: `path`
- Required: `true`
- Description:
  > The customer who has opted out.
- Schema: `string`
  - Constraints: example="+16315551111"

### `includeTotal`

- Reference: `#/components/parameters/includeTotal`
- Parameter name: `includeTotal`
- Location: `query`
- Required: `false`
- Description:
  > Return results inside an object that contains the total result count or not.
- Schema: `boolean`
  - Constraints: default=false

### `limit`

- Reference: `#/components/parameters/limit`
- Parameter name: `limit`
- Location: `query`
- Required: `false`
- Description:
  > A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
- Schema: `integer (int32)`
  - Constraints: minimum=1; maximum=100; default=10

### `page`

- Reference: `#/components/parameters/page`
- Parameter name: `page`
- Location: `query`
- Required: `false`
- Description:
  > Page number of the results to be returned, 1-based.
- Schema: `integer (int32)`
  - Constraints: minimum=1; maximum=100; default=1

### `pageAfter`

- Reference: `#/components/parameters/pageAfter`
- Parameter name: `pageAfter`
- Location: `query`
- Required: `false`
- Description:
  > A cursor to fetch the next page in cursor pagination.
  > For example, if you make a list request, receive 100 objects and `cursor.after=id:foo`, your subsequent call can include `pageAfter=id:foo` in order to fetch the next page of the list.
- Schema: `string`
  - Constraints: example="id:foo"

### `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)

### `Page`

- Reference: `#/components/schemas/Page`
- Shape: `object`
  - Description:
    > Represents a given page of items.
  - Required properties: `offset`, `limit`, `length`
  - Properties:
    - `items`: `array`
      - Items: `object`
    - `length`: `integer (int32)` (required)
      - Description:
        > The actual number of items in the page.
      - Constraints: minimum=0
    - `limit`: `integer (int32)` (required)
      - Description:
        > A limit on the number of items to be returned, between 1 and 100, defaults to 10.
      - Constraints: minimum=1
    - `offset`: `integer (int32)` (required)
      - Description:
        > The position of the item this page starts from, zero-based. e.g., the 11th item is at offset 10.
      - Constraints: minimum=0
    - `total`: `integer (int32)`
      - Description:
        > The total number of items. This field is returned only when the request parameter `includeTotal` is set to `true`.
      - Constraints: minimum=0

### `PageCursor`

- Reference: `#/components/schemas/PageCursor`
- Shape: `object`
  - Description:
    > A cursor object is returned only if the endpoint you requested supports cursor pagination.
  - Properties:
    - `after`: `string`
      - Description:
        > A cursor to fetch the next page in cursor pagination.
        > For example, if you make a list request, receive 100 objects and `cursor.after=id:foo`, your subsequent call can include `pageAfter=id:foo` in order to fetch the next page of the list.
        > This field is returned only if there are more items in the list.
      - Constraints: example="id:foo"

### `Unsubscriber`

- Reference: `#/components/schemas/Unsubscriber`
- Shape: `object`
  - Description:
    > An unsubscriber is a configuration item representing that customers opt out of receiving messages from your business.
    > **A customer and a channel form a unique identifier for an unsubscriber.**
  - Properties:
    - `channel`: `#/components/schemas/UnsubscriberChannel`
    - `createTime`: `string (date-time)`
      - Description:
        > The time at which this object was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
      - Constraints: example="2022-06-01T12:00:00.000Z"
    - `customer`: `string`
      - Description:
        > The customer who has opted out.
        > For `type=PHONE_NUMBER`, it should be a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
      - Constraints: example="+16315551111"
    - `regionCode`: `string`
      - Description:
        > The customer's region code, formatted in [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
      - Constraints: example="US"
    - `source`: `string`
      - Description:
        > The source from which a customer resumed their subscription
        > - `Whatsapp`: The customer resumed their subscription on the whatsapp client
        > - `API`: You remove the customer from the unsubscribe list through the OpenAPI of YCloud
        > - `Manual`: You remove the customer from the unsubscribe list on the Contact page of YCloud.
      - Constraints: enum=["Whatsapp", "API", "Manual"]; example="Whatsapp"
    - `type`: `#/components/schemas/UnsubscriberType`

### `UnsubscriberChannel`

- Reference: `#/components/schemas/UnsubscriberChannel`
- Shape: `string`
  - Description:
    > Channel of unsubscriber.
    > - `whatsapp`: Indicates that the customer opts out of receiving WhatsApp messages from your business.
  - Constraints: enum=["whatsapp"]

### `UnsubscriberCreateRequest`

- Reference: `#/components/schemas/UnsubscriberCreateRequest`
- Shape: `object`
  - Required properties: `type`, `customer`, `channel`
  - Properties:
    - `channel`: `#/components/schemas/UnsubscriberChannel` (required)
    - `customer`: `string` (required)
      - Description:
        > The customer who has opted out.
        > For `type=PHONE_NUMBER`, it should be a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
      - Constraints: example="+16315551111"
    - `regionCode`: `string`
      - Description:
        > The customer's region code, formatted in [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
      - Constraints: example="US"
    - `type`: `#/components/schemas/UnsubscriberType` (required)

### `UnsubscriberPage`

- Reference: `#/components/schemas/UnsubscriberPage`
- Shape: `object`
  - Description:
    > Represents a given page of unsubscriber objects.
  - `allOf` composition (preserved; not inferred SDK inheritance):
    - `#/components/schemas/Page`
      - `$ref`: `#/components/schemas/Page`
  - Properties:
    - `cursor`: `#/components/schemas/PageCursor`
    - `items`: `array`
      - Description:
        > An array containing unsubscriber objects.
      - Items: `#/components/schemas/Unsubscriber`
  - Effective wire object after merging `allOf` (use this shape in response adapters):
    - Required properties: `offset`, `limit`, `length`
    - Properties:
      - `items`: `array`
        - Items: `#/components/schemas/Unsubscriber`
      - `length`: `integer (int32)` (required)
      - `limit`: `integer (int32)` (required)
      - `offset`: `integer (int32)` (required)
      - `total`: `integer (int32)`
      - `cursor`: `#/components/schemas/PageCursor`

### `UnsubscriberType`

- Reference: `#/components/schemas/UnsubscriberType`
- Shape: `string`
  - Description:
    > Type of unsubscriber.
    > - `PHONE_NUMBER`: Indicates that the `customer` is a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
  - Constraints: enum=["PHONE_NUMBER"]

### `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"

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