YCloud Developer Kit

View saved version →

---
name: ycloud-api-authentication
description: Design, implement locally, or evaluate secure server-side YCloud API authentication with the contract’s X-API-Key scheme, placeholder configuration, environment isolation, secret-manager boundaries, and API-key rotation planning. Use for API-key storage, header, or API-key rotation questions; webhook endpoint secret rotation belongs to Webhooks.
---

# YCloud API Authentication

Design or implement authentication at a trusted server boundary. Use the global authentication scheme in `references/openapi.md` and the official error behavior in `references/runtime.md`. When translating authentication errors or designing rotation coordination, also read `references/shared/integration-boundaries.md` and label project policy separately from YCloud behavior. Never call YCloud, read a credential, or expose a real secret.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Infer the Architect dimensions when they are supplied: `scope`, `deliverable`,
and `mutation`. Without an Architect handoff, default to focused scope and
read-only guidance unless the user explicitly asks to implement local project
changes. Local-write authorization permits server config adapters, validation,
redaction, and no-network tests inside the scoped project. It does not permit
reading, setting, validating, or rotating a real key, changing deployment or
production configuration, or making an external request.

## Scope and handoff

Handle only server-side API-key configuration and API-key rotation planning. A generic "rotate secret" request must be clarified: webhook endpoint secret rotation belongs to Webhooks, not Authentication. Route these requests away:

- Message send/retrieve (including sending an existing template) → `ycloud-whatsapp-messages`.
- Media upload → `ycloud-whatsapp-media`.
- Template lifecycle or analytics → `ycloud-whatsapp-templates`.
- Webhook endpoint management → `ycloud-webhook-endpoints`.
- Broad or multi-domain integration planning → `ycloud-integration-architect`.
- Plugin readiness → the readiness-only smoke Skill; repository-maintenance and issue-tracker workflows are outside this Plugin.

## Workflow

For explicitly requested sandbox/mock/no-real-side-effect tests, also read
`references/shared/sandbox-contract.md`. The fixed synthetic key belongs only to
the local Facade and is not a YCloud test credential or an example of production
key format.

1. Inspect project structure read-only to identify the server runtime, configuration mechanism, deployment environments, and test harness. Do not open or parse secret values from `.env`, credential files, secret stores, logs, shell history, browser storage, or customer data. Ask only for a missing runtime/deployment fact that changes the guidance.
2. Read both narrow references and preserve their exact boundaries. The request header is `X-API-Key`; show only a placeholder such as `<YCLOUD_API_KEY>`, never a user-provided key. An invalid key is documented as HTTP `401` with `error.code=UNAUTHORIZED`; preserve that provider envelope and `YCloud-Request-ID`. If the project exposes RFC 9457, translate only at its own API boundary and retain redacted `provider_code`/`provider_request_id`; never claim YCloud returned Problem Details.
3. Keep the key on a trusted server boundary. Recommend an environment-specific secret injection path or Secret Manager reference, least-privilege access, redaction, and rotation ownership without claiming provider-specific behavior that the contract does not state.
4. Explain environment isolation (development, staging, production), startup/configuration validation that checks presence and shape without printing the value, and tests that use a synthetic placeholder. When local writes are authorized, implement these seams using the project's established configuration pattern and run no-network tests; never inspect the user's environment value.

## Safe examples

Illustrative raw HTTP only; do not execute it:

```http
X-API-Key: <YCLOUD_API_KEY>
```

Illustrative server configuration shape (choose the project’s established mechanism; the value is never supplied here):

```text
YCLOUD_API_KEY=<injected-secret-placeholder>
```

Never place the key in a browser/mobile bundle, client-side storage, a URL/query parameter, source control, a code sample with a real value, analytics, or ordinary request logs. Redact authorization headers in diagnostics.

## Outcome requirements

Adapt the shape to planning, implementation, or evaluation. Make these results
easy to verify:

### Contract

Name the confirmed global `api_key` `apiKey` security scheme with header name `X-API-Key` and cite the generated reference. Distinguish raw HTTP from any SDK/codegen shape.

### Configuration Plan

Describe the server-only injection point, environment separation, access/redaction controls, startup checks, and rotation handoff. Use names and placeholders, not secret values.

### Project Integration

Map the plan to confirmed project modules (HTTP client, config loader, deployment manifest, and tests). If the project cannot be inspected, ask the minimum questions or mark the assumption.

### Tests

Cover header construction with `<YCLOUD_API_KEY>`, missing/blank configuration, environment isolation, redaction, a synthetic `401/UNAUTHORIZED` envelope, and request-ID correlation. Tests must not contact YCloud or inspect a real secret.

### CANNOT

Explicitly refuse to read, echo, validate, rotate, retrieve, or store a real key; call the API; make unrequested local changes or any deployment/production change; put a key client-side, in a URL, logs, or a repository; infer an SDK auth method; or assert unspecified key expiry, rotation overlap, recovery, retry, or endpoint-specific rate behavior. Do not mark the documented `401/UNAUTHORIZED` behavior as unknown. For rotation, describe coordination and confirmation points only.

### Handoff

Send message/media/template/webhook work to its domain Skill. For an Architect
handoff, return `crosscutting:api-authentication` status, project seams, changed
or proposed artifacts, tests and results, unknowns, and the server-side header
boundary. Authentication does not perform the downstream workflow.

## Codegen boundary

Do not infer a Java, TypeScript, Python, Go, or PHP SDK method from `operationId` or model names. Provide a raw HTTP/header example unless the user supplies a confirmed SDK artifact/version and authoritative docs. Treat generated models and schema composition as codegen hints, not additional authentication behavior.

Referenced files: 5

View saved version →

---
name: ycloud-balance
description: Design, implement locally, or evaluate retrieval and interpretation of the YCloud account balance. Use for the single Balance read operation or a balance-to-readiness evidence handoff; exclude plugin readiness checks, billing history, top-ups, and real API operations.
---

# YCloud Balance

Design or implement contract-aware retrieval of the current account balance.
Use synthetic responses and a mock transport only; never call YCloud, read a
credential, expose customer financial data, or claim a live balance was checked.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor an Architect handoff for scope, deliverable, mutation, capability ID,
project seams, and evidence. Without one, default to focused read-only guidance
unless the user explicitly requests local implementation. Local-write
authorization permits a trusted-server adapter, typed response mapping,
mock-only handler/service bindings, fixtures, and no-network tests in the scoped
project. It never authorizes a live balance request or production readiness
decision.

## Scope and handoffs

After this Skill is selected, read the generated [OpenAPI
contract](references/openapi.md) and reviewed [runtime
behavior](references/runtime.md). If retry, error translation, rate limiting, or
production architecture is requested, also read
`references/shared/integration-boundaries.md`. If either generated reference is
missing, stale, or conflicts with the pinned source, report the drift and stop
instead of guessing.

This Skill owns exactly `GET /balance`, operationId `balance-retrieve`. It does
not own transactions, billing history, invoices, spending forecasts, top-ups,
currency conversion, or account mutation. API-key configuration belongs to
`ycloud-api-authentication`; broad planning belongs to
`ycloud-integration-architect`.

Balance may provide one synthetic or observed-at-runtime input to an
application's operational-readiness policy, but this Skill does not define a
minimum sufficient balance and cannot certify plugin, deployment, account, or
production readiness. Route an explicit Developer Kit installation/readiness
check to the readiness/smoke workflow. Keep any application threshold, alert,
reservation, or fail-open/fail-closed rule labeled as project policy.

## Contract-first workflow

1. Confirm the source hash, exact method/path, `operationId`, lack of parameters
   and request body, and response schema in the generated reference. Do not
   infer an SDK method from `balance-retrieve`.
2. Preserve the documented `200 Balance` shape: required numeric `amount` and
   required string `currency`, where currency is an ISO 4217 code. Do not assume
   `amount` is an integer, minor units, non-negative, available credit, or a
   promise that a future operation will succeed. Preserve decimal precision
   according to the target project's established money strategy; if none
   exists, surface that decision instead of silently rounding through binary
   floating-point arithmetic.
3. Keep provider-generated identifiers and future opaque strings
   case-sensitive and unparsed. Preserve unknown response properties and an
   explicit unknown branch for future enum-like values. Do not convert currency
   or combine balances unless a separate, authoritative project contract is in
   scope.
4. At the provider adapter, retain the standard error envelope and
   `YCloud-Request-ID` (or `error.requestId`) for redacted correlation. The
   operation itself declares only `200`; use reviewed cross-cutting runtime
   behavior for generic failures and do not invent balance-specific status
   codes or error meanings. Branch on HTTP status and `error.code`, never
   diagnostic `error.message`.
5. On `429`, honor `Retry-After` before another request and parse beta
   `RateLimit-*` headers defensively. Do not assign an invented balance quota.
   Because retrieval is read-only, a bounded transient retry may be proposed as
   project policy, but no retry count, backoff, cache lifetime, or staleness
   tolerance is a YCloud guarantee unless `runtime.md` says so.
6. Keep the API key on a trusted server and use placeholders only. A local
   handler or readiness consumer must call a fake adapter and visibly
   label its data synthetic; it must not offer a control that reaches YCloud.

## Illustrative raw HTTP

This shape is documentation only; do not execute it:

```http
GET <YCLOUD_API_BASE_URL>/balance
X-API-Key: <YCLOUD_API_KEY>
```

Synthetic response fixture:

```json
{"amount": 190.0765, "currency": "USD"}
```

Do not put a real key, account identifier, response, or customer financial data
in examples, fixtures, logs, or generated artifacts.

## Outcome requirements

Adapt the result to planning, implementation, or evaluation, while making these
items explicit:

1. **Matched contract** — source hash, `GET /balance`, `balance-retrieve`, no
   request body, `200 Balance`, and required `amount`/`currency` fields.
2. **Interpretation** — numeric/precision strategy, ISO 4217 treatment, unknown
   property handling, freshness label, and every project-owned threshold or
   policy clearly separated from YCloud facts.
3. **Integration placement** — trusted-server adapter, placeholder
   Authentication handoff, mock transport seam, and redacted request-ID
   observability.
4. **Response and rate handling** — standard error envelope, no invented
   balance-specific statuses, defensive rate headers, `Retry-After`, and any
   bounded GET retry labeled as project policy.
5. **Tests** — no-parameter/no-body request construction; decimal and currency
   preservation; missing/wrong-typed fields; unknown fields/currency-like
   values; synthetic error/request-ID fixtures; `429` scheduling; timeout and
   bounded-retry policy; readiness handoff without a readiness claim; and proof
   that no network call occurs.
6. **CANNOT** — live balance retrieval, credentials or real financial data,
   mutations/top-ups/history, currency conversion, affordability or readiness
   guarantees, inferred SDK methods, invented quotas/errors, or unlabelled
   caching and threshold policy.
7. **Handoff** — provide Balance evidence with provenance and freshness to the
   Architect or project-owned readiness consumer, which owns the final policy
   decision. Return capability-row status, artifacts, tests/results, and
   unknowns; state when no handoff is needed.

## Safety and source priority

Use the pinned OpenAPI source first, generated references second, and this
workflow third. Keep provider contract, reviewed runtime facts, and project
policy visibly separate. External reads and mutations remain prohibited even
when local implementation is authorized.

Referenced files: 4

View saved version →

---
name: ycloud-contacts
description: Design, implement locally, or evaluate YCloud Contacts lifecycle, attribute, and note operations with strict contact/note ID separation and defensive pagination. Use for Contacts API work; exclude Custom Events, Unsubscribers, message sending, and real API mutations.
---

# YCloud Contacts

Design or implement contract-aware contact, contact-attribute, and contact-note
workflows against mocks only. Never call YCloud, read credentials or customer
data, perform a real mutation, or treat a contact change as a downstream event,
subscription, or message action.

## Execution and authority boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor an Architect handoff for `scope`, `deliverable`, `mutation`, capability
IDs, project seams, and evidence. Without one, default to focused, read-only
guidance unless the user explicitly requests local implementation. Local-write
authorization permits request models/builders, adapters, handlers, service
bindings, mocks, fixtures, and no-network tests inside the scoped project. Every
create, update, or delete remains mock-only; local-write authorization does not
authorize a real contact or note mutation.

Keep claims in three authority layers:

1. **Provider contract** — [references/openapi.md](references/openapi.md) and
   [references/runtime.md](references/runtime.md). State these as YCloud behavior.
2. **Developer Kit policy** — `references/shared/integration-boundaries.md` when
   retry, idempotency, queueing, error translation, or webhook reliability is in
   scope. Label its recommendations as local policy.
3. **Project decisions** — only facts confirmed in the user's scoped project.

Do not promote an `operationId`, generated model name, `x-*` extension, example,
platform recommendation, or project convention into provider behavior. If the
generated references are absent, stale, internally inconsistent, or do not list
all ten operations below, stop and report the drift.

## Exact operation allowlist

Load both generated references after this Skill is selected. Match only these
operations and preserve every source-defined parameter, request/response schema,
status code, and description constraint.
For contact list work, also read
[`references/shared/pagination-contract.md`](references/shared/pagination-contract.md).

| Intent | Method and path | operationId |
| --- | --- | --- |
| List attributes | `GET /contact/contacts/attributes` | `contact-attributes-list` |
| Create contact | `POST /contact/contacts` | `contact-create` |
| Delete contact | `DELETE /contact/contacts/{id}` | `contact-delete` |
| List contacts | `GET /contact/contacts` | `contact-list` |
| Create note | `POST /contact/contacts/{contactIdentifier}/notes` | `contact-note-create` |
| Delete note | `DELETE /contact/notes/{noteId}` | `contact-note-delete` |
| Update note | `PATCH /contact/notes/{noteId}` | `contact-note-update` |
| List notes | `GET /contact/contacts/{contactIdentifier}/notes` | `contact-notes-list` |
| Retrieve contact | `GET /contact/contacts/{id}` | `contact-retrieve` |
| Update contact | `PATCH /contact/contacts/{id}` | `contact-update` |

No search operation is in this allowlist. Contact attributes are configurations,
not contact values. Contact retrieve/list responses do not contain notes; use
`contact-notes-list` when note contents or note IDs are needed.

## Identifier separation

Treat every identifier as opaque and case-sensitive except where the contract
defines syntax. Never substitute one identifier class for another.

- Contact `{id}` and note-owner `{contactIdentifier}` accept a contact ID, an
  E.164 phone number beginning with `+`, or a Meta username without `@`, up to
  255 characters. Ambiguous numeric input resolves as a username first and as a
  contact ID only when no matching username exists; do not pre-resolve it with
  local numeric heuristics.
- Note `{noteId}` is a separate 24-character hexadecimal ObjectId. It is valid
  only for `contact-note-update` and `contact-note-delete`. Obtain note IDs from
  note create/list responses, never from the owning contact ID.
- A `ContactNote.contactId` identifies the owner and is not the note's `id`.
  For note mutations embedded in `contact-update`, an item without `id` creates
  a note; an item with a note ID updates an owned note. Omitted notes remain
  unchanged, an empty array changes nothing, and deletion uses the dedicated
  note-delete operation.

## Contract-first workflow

1. Select one allowlisted operation and a confirmed server-side project seam.
   Preserve unknown response properties and unknown attribute/source values;
   do not fail exhaustive decoding when YCloud adds compatible fields or enums.
2. Preserve request constraints. Contact create requires `phoneNumber`; notes
   trim surrounding whitespace and require 1–500 characters after trimming;
   contact create/update accepts at most 50 notes; tags accept at most 50 values
   of at most 50 characters. `nickname` is a deprecated input alias for
   `remarkName`, while response `nickname` is read-only WhatsApp data.
3. Keep contact updates patch-like. A non-null `customAttributes` array replaces
   all previous custom attributes. A no-op persisted-field update emits no
   `contact.attributes_changed` event, although note mutations in the request
   still apply. Do not infer note success from the returned `Contact`, because
   that schema excludes notes.
4. Use only synthetic contacts, phone numbers, usernames, note IDs, and payloads
   in examples and tests. Keep `X-API-Key` injection server-side through the
   Authentication handoff without reading a real key. An `operationId` is not an
   SDK method name.
5. Treat a timeout or lost response for create, update, delete, or note mutation
   as ambiguous. Never replay it automatically. Note create has no client
   idempotency key and replay creates another note; repeated note delete returns
   `404`; repeated note update may emit another update event even when content is
   unchanged. Any reconciliation or deduplication design is project policy.

## Defensive pagination

Contact list supports two modes; choose one and do not silently switch modes.

- Page mode omits `pageAfter`; `page` is 1–100 with default 1, `limit` is 1–100
  with default 10, and `includeTotal` defaults false.
- Its successful wire response is the merged `ContactPage allOf Page` object:
  required `offset`, `limit`, and `length`; optional `total`; resource `items`;
  and optional `cursor`. `offset` is response metadata, not a request parameter.
  Preserve each Contact field, including `phoneNumber`, `countryCode`,
  `countryName`, `sourceType`, `lastSeen`, and `lastMessageToPhoneNumber`, plus
  unknown properties. Do not unwrap a nonexistent `data` property.
- Forward-cursor mode starts with the string `pageAfter=0`, then passes the exact
  returned `cursor.after` value unchanged. Never parse, increment, synthesize,
  or persist assumptions about cursor contents.
- Do not combine `pageAfter` with `page`, `pageBefore`, `offset`, or `sort`. Keep
  filters unchanged for the traversal. A missing `cursor` means there is no next
  page; do not assume an empty page, `length < limit`, or `total` is authoritative
  evidence of continuation.
- Cursor traversal is ordered by contact ID ascending and weakly consistent
  under concurrent inserts, deletes, and filter-field updates. Restart with
  `pageAfter=0` when a fresh traversal is required. `total`, when requested, is
  the complete filtered count and is not reduced by cursor position.

The notes-list endpoint is not cursor-paginated: it returns all notes, newest
first, with a maximum of 50. Do not add page parameters to it.

## Mutation safeguards and tests

Implement mutations only against mocks and verify them with no-network tests.
For any future external workflow, stop before the call, identify the exact
contact identifier or note ID and impact, require explicit operation-specific
confirmation, and leave an ambiguous result unresolved.

Tests should cover all ten routes and methods, required and optional body shape,
contact/note ID non-interchangeability, username-first ambiguity, note limits and
trimmed content, incremental note semantics, custom-attribute replacement, the
complete provider-shaped ContactPage envelope and item mapping, pagination mode
conflicts and terminal cursor absence, unknown fields/enums,
provider error/request-ID mapping, and no automatic mutation replay.

## Outcome requirements

Return matched operation IDs and exact method/paths, authority-labeled contract
facts, project-local artifacts or proposed seams, no-network test evidence,
identifier handling, pagination mode, explicit unknowns, and handoffs. Do not
claim implementation from only a route label, sample JSON, or mock response;
link each implemented row to its adapter/handler and behavioral tests.

### CANNOT

List unsupported operations, missing project facts, source conflicts,
unconfirmed SDK behavior, live credentials/customer data, real API calls,
external mutations, automatic mutation replay, inferred note ownership, or
downstream event/subscription/message claims. Do not move documented contact
identifier resolution, note-ID syntax, or cursor behavior into `CANNOT`.

### Handoff

Contacts is a producer for downstream capabilities, not their executor. Hand a
confirmed contact ID and the project-approved event payload to Custom Events;
hand a confirmed contact identity plus channel intent to Unsubscribers; hand a
confirmed E.164 recipient or supported recipient identity to Messages. Keep
contact IDs, note IDs, event IDs, unsubscriber records, and message IDs separate,
and do not infer that a contact mutation performed any downstream action.

Send authentication storage to `ycloud-api-authentication`. Return to Architect
with capability-row status, changed or proposed artifacts, tests/results,
pagination and identifier evidence, unknowns, and outgoing handoffs.

Referenced files: 5

View saved version →

---
name: ycloud-custom-events
description: Design, implement locally, or evaluate YCloud custom-event definition/property lifecycle and CONTACT-associated event ingestion. Use for the seven allowlisted Custom Events operations; exclude Contact lifecycle, webhook consumption, analytics, and real API mutations.
---

# YCloud Custom Events

Design or implement contract-aware custom-event schema management and event
ingestion with synthetic data and a mock transport only. Never call YCloud,
read credentials or customer data, mutate a real definition, or send a real
event.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor an Architect handoff for scope, deliverable, mutation, capability IDs,
project seams, Contact artifacts, and expected evidence. Without one, default
to focused read-only guidance unless the user explicitly requests local
implementation. Local-write authorization permits server-side request models,
builders, adapters, handlers, fixtures, and no-network tests in the scoped
project. It never authorizes an external create, update, delete, retrieve, or
send request. Use placeholders and synthetic identifiers throughout.

After this Skill is selected, read the pinned [OpenAPI
contract](references/openapi.md) and reviewed [runtime
boundaries](references/runtime.md). If retry, idempotency, outbox/queue, rate
limiting, or error translation is requested, also read
`references/shared/integration-boundaries.md`. If the source hash, operation
coverage, or contract facts drift, stop and report the mismatch instead of
guessing.

## Exact scope and routing

Definition and property lifecycle is separate from occurrence ingestion:

| Concern | Method and path | operationId |
| --- | --- | --- |
| Create definition | `POST /event/definitions` | `custom_events-create-definition` |
| Retrieve definition | `GET /event/definitions/{name}` | `custom_events-retrieve-definition` |
| Update definition metadata | `PATCH /event/definitions/{name}` | `custom_events-update-definition` |
| Create property definition | `POST /event/definitions/{name}/properties` | `custom_events-create-property-definition` |
| Delete property definition | `DELETE /event/definitions/{name}/properties/{propertyName}` | `custom_events_delete-property-definition` |
| Update property metadata | `PATCH /event/definitions/{name}/properties/{propertyName}` | `custom_events_update-property-definition` |
| Ingest event occurrence | `POST /event/events` | `custom_events-send-event` |

The first six operations manage reusable definitions; they do not ingest an
event. The final operation submits one occurrence; it does not create or alter
its definition. Contact create/retrieve/update/delete and identity resolution
belong to the Contact workflow. Webhook consumption, analytics, readiness, and
broad multi-domain planning are outside this Skill.

## Contract-first workflow

1. Match only the selected operations above to their exact method, path,
   parameters, request schema, responses, and descriptions in `openapi.md`.
   Treat `operationId` as an identifier, not an SDK method. Use raw HTTP shapes
   or an SDK artifact/version already confirmed in the project.
2. For definition creation, preserve required `name`, `label`, and `objectType`;
   the pinned enum contains only `CONTACT`. Preserve the exact source patterns
   and lengths without “correcting” or anchoring them. Definition update changes
   only `label` and/or `description` in the declared request shape.
3. For property creation, preserve required `name`, `label`, and `type`, and the
   declared types `STRING`, `NUMBER`, `TIMESTAMP`, and `URL`. Property update
   changes only `label` and/or `description`; changing a property's name or type
   is not an allowlisted update behavior. Treat delete as high risk: identify
   the exact definition/property pair and stop before any external execution.
4. Before ingestion, require an already-defined `eventName` and validate event
   property names and values against the confirmed definition. The source says
   NUMBER accepts numeric values with up to one decimal, TIMESTAMP accepts epoch
   milliseconds, and URL accepts strings beginning with `http://` or `https://`.
   Do not infer coercion, undeclared-property handling, schema evolution, or
   server-side validation behavior beyond the pinned descriptions.
5. Consume a Contact handoff artifact rather than looking up or changing a
   contact. Accept either a confirmed opaque contact ID for `objectId` or a
   confirmed contact phone number for `contactPhoneNumber`, together with its
   provenance. Choose one association form as project policy; the OpenAPI says
   the phone number is an alternative but does not define precedence when both
   fields are present. If the handoff is missing or supplies both without an
   explicit project decision, stop instead of resolving identity here.
6. Keep `occurTime` as RFC 3339 when supplied. The source says the current time
   is used when omitted, but does not define whose clock, timezone normalization,
   or replay semantics. Preserve omission intentionally and test supplied and
   omitted branches with a fake clock where project code needs deterministic
   behavior.
7. Treat a documented HTTP `200` as synchronous acceptance/success for the
   selected endpoint only. For event ingestion, the source declares no response
   body, event ID, processing state, callback, query operation, ordering rule,
   or downstream-completion guarantee. Never label an accepted occurrence as
   processed, delivered, or completed.
8. All seven external operations are mock-only in this workflow. Treat a timeout
   or lost response from create, update, delete, or send as an ambiguous outcome.
   Never replay automatically. Any idempotency key, outbox identity, deduplication
   ledger, retry budget, or reconciliation process is project-owned architecture
   unless a separate authoritative contract confirms it.

## Illustrative ingestion shape

This is documentation only; do not execute it:

```http
POST <YCLOUD_API_BASE_URL>/event/events
X-API-Key: <YCLOUD_API_KEY>
Content-Type: application/json

{"eventName":"<DEFINED_EVENT_NAME>","objectId":"<CONFIRMED_CONTACT_ID>","occurTime":"<RFC3339_TIME>","properties":{"<DEFINED_PROPERTY>":"<SYNTHETIC_VALUE>"}}
```

Use `contactPhoneNumber` instead of `objectId` only when that is the confirmed
Contact handoff artifact. Do not put a real key, contact, phone number, event, or
customer property in examples, fixtures, logs, or generated artifacts.

## Outcome requirements

Adapt the result to planning, implementation, or evaluation and make these
items explicit:

1. **Matched contract** — source hash, selected operation IDs, exact methods and
   paths, parameters, request/response schemas, and description-only rules.
2. **Lifecycle versus ingestion** — definition/property changes and occurrence
   submission remain distinct in architecture, handlers, permissions, and tests.
3. **Contact handoff** — record whether the input is a confirmed opaque contact
   ID or confirmed contact phone number, its provenance, and any project-owned
   choice when both could exist; perform no Contact lookup or mutation.
4. **Acceptance boundary** — distinguish endpoint `200` from unconfirmed
   downstream processing or completion and preserve unknown future fields.
5. **Safety** — trusted-server placement, placeholder authentication, mock-only
   transport, high-risk delete stop, timeout ambiguity, and no automatic replay.
6. **Tests** — exact routing and schemas; name/type constraints; CONTACT-only
   definition handling; update field allowlists; property-value validation;
   Contact artifact branches; supplied/omitted occurrence time; empty-body `200`;
   `404` lifecycle fixtures; ambiguous timeout/no replay; and proof of no network.
7. **CANNOT** — real API calls or credentials, Contact resolution/mutation,
   undocumented property coercion/precedence, safe replay or exactly-once claims,
   downstream status/completion, analytics, callbacks, guessed SDK methods, and
   unlisted errors or operations.
8. **Handoff** — send contact creation, retrieval, normalization, or identity
   choice to Contact; consume only its confirmed artifact. Return to Architect
   with capability-row status, artifacts, tests/results, accepted-versus-final
   evidence, unknowns, and outgoing handoffs.

## Safety and source priority

Use the pinned OpenAPI source first, these derived references second, and this
workflow third. Keep source facts, observed runtime evidence, and project policy
visibly separate. No local implementation authorization permits a network call
or external side effect.

Referenced files: 4

View saved version →

---
name: ycloud-developer-kit-smoke-test
description: Return a fixed readiness message without external side effects. Use when the user explicitly asks to verify that the local YCloud Developer Kit Codex plugin is installed, discoverable, or ready.
---

# YCloud Developer Kit Smoke Test

Return exactly this text and nothing else:

```text
YCloud Developer Kit is ready. No external API was called.
```

Do not call tools, run shell commands, access the network, invoke MCP servers, call APIs, read credentials, or inspect customer data.

Referenced files: 1

View saved version →

---
name: ycloud-integration-architect
description: Design, implement, or evaluate a cross-domain YCloud integration from local project context, with explicit scope, deliverable, mutation boundaries, domain handoffs, and coverage evidence. Use for broad integration or multi-domain orchestration; do not use for readiness, repository-maintenance, issue-tracker, support, or requests confined to one domain.
---

# YCloud Integration Architect

Orchestrate a contract-aware YCloud integration across every Developer Kit-owned
domain. Normalize the request before acting, delegate
domain contract decisions to the matching Skill, and merge their evidence into
one result. Never call a real YCloud API, read credentials or customer data, or
infer permission for an external action from permission to edit local files.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

## Normalize the request

Resolve these dimensions from the user's words and project context:

```text
scope: focused | full-first-wave | full-whatsapp-operations | full-supported-operations
deliverable: project-integration | test-console | production-plan
mutation: read-only | local-write-authorized
```

- Default to `focused` when the user names a concrete outcome or domain.
- “All currently supported capabilities” means `full-supported-operations`: 88
  API operations plus 2 cross-cutting capabilities = 90 coverage rows.
- `full-first-wave` remains a compatibility mode: 17 API operations + 2
  cross-cutting capabilities = 19 coverage rows.
- “All YCloud APIs” requires an explicit `88 API operations + 2 cross-cutting capabilities = 90 coverage rows`
  disclosure, with 7 operations excluded by product decision. Product exclusion
  is not provider deprecation; never claim all 95 are covered.
- Select `test-console` only when the user asks for a test UI, console, explorer,
  or comparable interactive surface. Do not turn `full-first-wave` into a
  dashboard on its own.
- Select `production-plan` for production architecture or rollout planning. It
  is read-only unless the user separately asks to implement local artifacts.
- Local implementation authorization permits writes only inside the scoped
  project. It never permits sending, uploading, deleting, rotating, changing a
  remote endpoint, or otherwise calling a real provider API.

Read only the selected mode reference:

- `focused` → [references/modes/focused.md](references/modes/focused.md)
- `full-first-wave` → [references/modes/full-first-wave.md](references/modes/full-first-wave.md)
- `full-whatsapp-operations` → [references/modes/full-whatsapp-operations.md](references/modes/full-whatsapp-operations.md)
- `full-supported-operations` → [references/modes/full-supported-operations.md](references/modes/full-supported-operations.md)
- `test-console` → [references/modes/test-console.md](references/modes/test-console.md)
- `production-plan` → [references/modes/production-plan.md](references/modes/production-plan.md)

When scope or completion is material, also read
[references/capability-catalog-summary.md](references/capability-catalog-summary.md)
and [references/coverage-matrix-schema.md](references/coverage-matrix-schema.md).
For multi-domain work, read
[references/handoff-contracts.md](references/handoff-contracts.md).

## Domain routing

| Concern | Owner Skill | Boundary |
| --- | --- | --- |
| API key, trusted-server header, storage, API-key rotation plan | `ycloud-api-authentication` | Never read or validate a real key; generic secret rotation must be disambiguated |
| Direct/queued message send construction or retrieve | `ycloud-whatsapp-messages` | Existing-template sending belongs here; accepted is not final |
| WhatsApp media upload construction | `ycloud-whatsapp-media` | Return a media handoff; upload is not send |
| Template lifecycle and analytics | `ycloud-whatsapp-templates` | Lifecycle is separate from template sending |
| Webhook endpoint management or receiver | `ycloud-webhook-endpoints` | Endpoint management and event receipt remain separate |
| WABA inventory or ACO settings | `ycloud-whatsapp-business-accounts` | Pass opaque WABA identity to Phone Numbers/Messages/Templates |
| Phone registration, profile, username, settings, or commerce | `ycloud-whatsapp-phone-numbers` | Calling settings do not include WhatsApp Calling sessions |
| Group lifecycle, membership, invite links, or settings | `ycloud-whatsapp-groups` | Group management and message final state remain separate |
| Flow lifecycle, preview, publish, deprecate, or delete | `ycloud-whatsapp-flows` | Flow management and Flow message sending remain separate |
| Mark inbound message read or show typing | `ycloud-whatsapp-inbound-messages` | Consume a verified Receiver message identity, not event ID |
| Account balance | `ycloud-balance` | Balance is readiness evidence, not a send/delivery guarantee |
| Contact CRUD, attributes, or notes | `ycloud-contacts` | Contact and note IDs remain distinct; writes are not replay-safe by default |
| Custom event definitions, properties, or ingestion | `ycloud-custom-events` | Definition lifecycle and event acceptance remain separate |
| Customer/channel unsubscribe state | `ycloud-unsubscribers` | Eligibility evidence is not provider send or delivery state |
| WhatsApp Calling session commands or call media | `ycloud-whatsapp-calling` | Command acceptance is not final call state; media is a separate handoff |

Read `references/openapi.md` and `references/runtime.md` for Architect-level
provenance, then load only the selected domain's narrow OpenAPI/runtime
references. Never load the full OpenAPI snapshot by default. For error
translation, retry, idempotency, rate limiting, webhook reliability, or
cross-domain policy, read `references/shared/integration-boundaries.md`. Stop on
source conflict or drift instead of guessing.
When any selected operation lists resources, also read
`references/shared/pagination-contract.md` and preserve its operation-specific
response envelope through client, service, handler, and UI-facing DTO tests.

When the user explicitly asks for sandbox/mock/no-real-side-effect integration
testing or a local YCloud base-URL replacement, also read
`references/shared/sandbox-contract.md`. Keep its provider-shaped surface,
Developer Kit policy, and mock-only control namespace separate; do not count the
Facade as additional OpenAPI coverage or silently substitute it for a real
production-readiness check.

When the user asks for a Java/Node reference project, SDK/Quickstart support,
generated-project evaluation, TTPRI, Beta evidence, or release readiness, also
read `references/shared/reference-integrations.md`. Treat executable paths as
source-distribution assets that may be absent from an installed Plugin. Keep
oracle harness results, caller-supplied candidate evidence, source-bound
receipts, synthetic TTPRI and real Beta evidence as separate trust layers.

## Project work

Inspect only non-secret project structure needed to identify runtime, framework,
build files, server/client boundary, configuration pattern, HTTP client, tests,
and an existing YCloud seam. Reuse the project's architecture and UI framework;
do not introduce React, Vue, Next.js, Spring, or another framework merely because
a test console was requested.

When local writes are authorized, implement the smallest complete vertical seam
for the selected scope and run proportionate no-network tests. Preserve unrelated
and concurrent edits. When writes are not authorized, provide a plan with
concrete project seams and do not change files. Do not apply project changes
unless the user has explicitly authorized local writes for that scoped project.

## Contract rules

- Exact paths, methods, schemas, and descriptions come from the selected
  generated reference. Use placeholders and synthetic IDs.
- `operationId`, codegen extensions, generated model names, and `allOf` do not
  establish an SDK method or new provider behavior.
- Use `runtime.md` for the documented error envelope, request ID, rate limits,
  pagination, compatibility, and asynchronous behavior. Keep provider contract,
  Developer Kit policy, and project decisions visibly separate.
- Include a provider error/request-ID/rate-limit adapter whenever selected
  operations need those cross-cutting runtime behaviors.
- Generate tolerant clients: preserve unknown properties and enum/event values,
  keep explicit unknown response/enum compatibility handling, and treat YCloud
  IDs as opaque case-sensitive strings up to 255 characters.
- Do not invent general idempotency, replay safety, fixed signature tolerance,
  delivery guarantees, or unlisted errors. Treat ambiguous mutation timeouts as
  ambiguous outcomes.

## Orchestration and evidence

Send each owner a handoff containing mode, selected capability IDs, project
seams, authorization level, preconditions, and evidence expected. Require the
domain result to return implemented/deferred/blocked rows, changed artifacts,
tests and results, unknowns, and any outgoing handoff. Merge those results
yourself; do not finish with instructions for the user to invoke every domain
Skill manually.

For `full-first-wave`, account for all 19 rows. For
`full-whatsapp-operations`, account for all 62 rows. For
`full-supported-operations`, account for all 90 rows. A row is not implemented merely
because a menu, card, route name, sample JSON, or button exists. Implemented rows
need a linked adapter/handler/service artifact and behavioral test evidence.
Deferred and blocked rows are allowed only with explicit reasons; silent omissions
fail coverage. Future and product-excluded operations remain disclosure rows and
must never be counted as implemented coverage.

## Outcome requirements

Adapt the response to the selected deliverable instead of forcing fixed headings.
Always make these facts easy to verify:

- normalized scope, deliverable, and mutation level;
- confirmed project facts and source provenance;
- selected capability rows and domain owners;
- architecture and cross-domain handoffs;
- local changes or proposed seams, with no claim that external actions ran;
- tests/evidence and accepted-versus-final state boundaries;
- deferred, blocked, unknown, unsupported, and authorization-gated items;
- next action needed from the user, if any.

### CANNOT

Keep real credentials, customer data, unconfirmed SDK behavior, unsupported
operations, and invented provider guarantees out of the result. Treat real
sends, uploads, deletes, endpoint changes, secret rotations, and production
changes as high-risk external actions. Local-write authorization never permits
them, and this workflow does not execute them.

### Handoff

Return a merged coverage/evidence result to the user. If further work requires a
new project scope, external action, production mutation, or missing material
decision, identify the owner and request that authorization or fact explicitly.
Do not substitute a list of Skills the user must invoke for the merged result.

Use placeholders and synthetic data. Readiness belongs to the smoke Skill.
Repository maintenance, issue tracking, ordinary product explanation, and
support cases remain outside this Skill.

Referenced files: 16

View saved version →

---
name: ycloud-unsubscribers
description: Design, implement locally, or evaluate YCloud customer unsubscribe creation, lookup, listing, and deletion. Use for opt-out records and message-eligibility evidence; exclude Contact CRUD, message sending, provider delivery status, and real API operations.
---

# YCloud Unsubscribers

For `unsubscriber-list`, read
[`references/shared/pagination-contract.md`](references/shared/pagination-contract.md)
with the generated OpenAPI/runtime references.

Design or implement contract-aware handling for the five Unsubscriber operations
in the pinned reference. Use synthetic customers and a mock transport only.
Never call YCloud, inspect credentials or customer data, or mutate a real
unsubscribe record.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor an Architect or Contact handoff for scope, deliverable, mutation,
capability IDs, project seams, confirmed customer identity, and expected
evidence. Without one, default to focused read-only guidance unless the user
explicitly requests local implementation. Local-write authorization permits
request/response models, adapters, handlers, mock fixtures, policy-evidence
mappers, and no-network tests in the scoped project. Create and delete remain
mock-only, and even GET operations must use mocks in this workflow.

After this Skill is selected, read the generated [OpenAPI
contract](references/openapi.md) and reviewed [runtime
behavior](references/runtime.md). For retry, idempotency, error translation, or
production architecture, also read
`references/shared/integration-boundaries.md`. If either local reference is
missing, stale, or inconsistent with its recorded source hash or operation
count, report drift and stop rather than reconstructing the contract from
memory.

## Exact operation scope

| Intent | Method and path | operationId |
| --- | --- | --- |
| Create an unsubscribe record | `POST /unsubscribers` | `unsubscriber-create` |
| Delete by composite identity | `DELETE /unsubscribers/{customer}/{channel}` | `unsubscriber-delete-by-customer-and-channel` |
| List unsubscribe records | `GET /unsubscribers` | `unsubscriber-list` |
| List all records for one customer | `GET /unsubscribers/{customer}` | `unsubscriber-list-all-by-customer` |
| Retrieve by composite identity | `GET /unsubscribers/{customer}/{channel}` | `unsubscriber-retrieve-by-customer-and-channel` |

Contact discovery and updates belong to a Contact capability; message request
construction, `filterUnsubscribed`, submission, retrieval, and message status
belong to `ycloud-whatsapp-messages`. Authentication belongs to
`ycloud-api-authentication`; broad multi-domain planning belongs to
`ycloud-integration-architect`. Webhook processing, keyword configuration,
marketing consent design, and non-WhatsApp channel behavior are out of scope.

## Contract-first workflow

1. Match only the five allowlisted operations. Report exact method, path,
   `operationId`, parameters, body, response schema, and documented status.
   Treat operation IDs and `x-*` fields as identifiers or codegen hints, not SDK
   method names or additional behavior.
2. Model `(customer, channel)` as the unique Unsubscriber identity. Do not use
   `regionCode`, `source`, or `createTime` as identity. For the documented
   `type=PHONE_NUMBER`, require `customer` to remain an E.164 string, never a
   number, and URL-encode it as one path segment (including the leading `+`).
   The only currently documented channel is lowercase `whatsapp`; do not
   normalize an unknown future channel into it. Consume a Contact handoff only
   when it supplies a confirmed customer value and its identity provenance;
   never infer an E.164 number from a contact name or unrelated identifier.
3. For create, send required `type`, `customer`, and `channel`; `regionCode` is
   optional. Preserve the documented `PHONE_NUMBER` and `whatsapp` values, but
   decode future `type`, `channel`, and `source` values through an explicit
   unknown branch. Preserve unknown response properties. Do not interpret the
   response `source` prose as an additional create/delete guarantee.
4. For `unsubscriber-list`, preserve `page` as 1-based with range 1-100,
   `limit` as 1-100, defaults of 1 and 10, optional `includeTotal`, optional
   `pageAfter`, and exact dotted filters `filter.customer`, `filter.channel`,
   and `filter.regionCode`. Parse the successful response as the merged Page
   envelope with required `offset`, `limit`, `length`, resource `items`, optional
   `total`, and optional `cursor`; `offset` is response metadata. Treat `total`
   as optional and present only when
   requested. Cursor traversal must use the returned opaque `cursor.after`
   unchanged and stop when it is absent. Add project-owned safety guards for an
   empty page, a repeated cursor, and a configured page/item budget. Do not
   synthesize a cursor from offsets, infer completion from `total`, or silently
   switch/mix page and cursor strategies beyond behavior confirmed by the
   contract.
5. Keep `GET /unsubscribers/{customer}` distinct: it returns an array, not an
   `UnsubscriberPage`, and documents `404`. Composite retrieve and delete also
   document `404`; list and create declare only `200`. Use reviewed runtime
   behavior for generic errors and do not invent endpoint-specific statuses.
6. Keep provider contract separate from local policy. Confirmation UX, local
   consent rules, audit retention, eligibility caches, retry budgets, and
   reconciliation are application-owned. A timeout or lost response to create
   or delete has an ambiguous outcome. The contract defines no general
   idempotency key, so never replay either mutation automatically. Honor
   `Retry-After` before later traffic without treating it as replay authority.
7. Use placeholders such as `<YCLOUD_API_KEY>` and `<E164_CUSTOMER>` and fully
   synthetic fixtures. Keep credentials server-side and hand credential work to
   Authentication. Do not read `.env`, secret stores, production logs, live
   Contacts, Unsubscribers, or Messages.

## Eligibility-policy evidence

An exact composite retrieve, a customer-wide list, or a deliberately complete
and defensively traversed filtered list can produce an evidence object for the
Messages capability. Include the queried customer/channel, match or no-match,
operation and source provenance, observation time/freshness, pagination
completeness, and unknown-value warnings. A local cache entry or incomplete
page traversal is not authoritative negative evidence.

This evidence is an input to the application's message-eligibility policy. It
does not submit or suppress a message by itself and is not a YCloud/WhatsApp
final status. Never label it sent, accepted, queued, failed, delivered, read, or
provider-rejected. Messages owns request-time policy (including whether to use
`filterUnsubscribed`) and provider response/webhook interpretation.

## Validation and evidence

For local implementation, add no-network tests for exact routes, required body
fields, E.164 string preservation and path encoding, composite identity,
array-versus-complete-page-envelope response shapes, all list parameters and dotted filters,
optional total, opaque cursor continuation, absent/repeated cursor termination,
empty pages, configured traversal budgets, `404` handling, standard errors and
request IDs, and unknown fields/enum values. Add mutation tests for explicit
authorization, ambiguous outcomes, and proof of no automatic replay. Mocks must
prove that no network client is invoked.

Return these sections, adapted to the requested deliverable:

1. **Matched contract** — source hash, selected operations, exact request and
   response shapes, and description-only constraints.
2. **Construction or implementation** — placeholder design, changed artifacts,
   and project facts still needed.
3. **Contract versus policy** — provider facts separated from local consent,
   eligibility, cache, pagination-budget, retry, and audit choices.
4. **Tests and evidence** — synthetic cases, actual no-network results, and
   pagination completeness.
5. **CANNOT** — live calls, credentials/customer data, unsupported operations,
   guessed SDK methods, automatic mutation replay, unconfirmed idempotency, or
   provider send/delivery/final-status claims.
6. **Handoff** — consume confirmed customer identity evidence from Contact;
   produce provenance-bearing eligibility-policy evidence for
   `ycloud-whatsapp-messages`; return capability status, artifacts, tests,
   unknowns, and outgoing handoffs to Architect. Do not claim a Contact exists
   merely because an Unsubscriber exists, or that an eligible result guarantees
   a message will be accepted or delivered.

## Safety stop

YCloud Provider API calls are prohibited during Skill execution, including
nominally read-only GETs. All mutations are mock-only. Stop before any request
that would use a real API key, customer identifier, Contact, Unsubscriber,
Message, or other live YCloud data.

Referenced files: 5

View saved version →

---
name: ycloud-webhook-endpoints
description: Design, implement locally, or evaluate YCloud webhook endpoint management and secure receivers from the official signature, retry, acknowledgement, and delivery contract. Use for endpoint CRUD/rotate-secret integration or event receiving; do not use for message sending, readiness, broad integration planning, or real endpoint/API mutations.
---

# YCloud Webhook Endpoints

For endpoint-list work, read
[`references/shared/pagination-contract.md`](references/shared/pagination-contract.md)
with the generated OpenAPI/runtime references.

Design or implement endpoint-management integrations from the pinned OpenAPI
contract and receiver integrations from the reviewed official runtime contract.
Keep those two modes distinct in the result.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor Architect handoffs for `scope`, `deliverable`, `mutation`, capability IDs,
project seams, and expected evidence. Without one, default to focused scope and
read-only guidance unless the user explicitly requests local implementation.
Local-write authorization permits endpoint request builders, adapters, receiver
handlers, inbox/state models, test-console bindings, synthetic fixtures, and
no-network tests inside the scoped project. It never authorizes endpoint create,
update, delete, secret rotation, callback delivery, or any real API call. Reuse
the project's existing UI/interface stack; do not create a dashboard or choose a
framework on your own.

## Trigger boundary

Use this skill for creating, listing, retrieving, updating, deleting, or rotating
the secret of a YCloud webhook endpoint, and for receiver acknowledgement,
signature verification, retry/deduplication handling, or event-delivery design.
Endpoint CRUD comes from `references/openapi.md`; receiver behavior comes from
`references/runtime.md`. Event-type-specific payload fields beyond the documented
common envelope require a selected event reference or remain `CANNOT`. Route message operations to `ycloud-whatsapp-messages`, media upload
to `ycloud-whatsapp-media`, template lifecycle to `ycloud-whatsapp-templates`,
and broad integration design to `ycloud-integration-architect`. Readiness and
Repository-maintenance and issue-tracker prompts do not trigger this skill.

After selection, read `references/openapi.md` and `references/runtime.md`. In
receiver mode, also read `references/shared/webhook-contract.md`,
`references/shared/webhook-event-types.txt`, and
`references/shared/webhook-signature-vectors.tsv`. For
`whatsapp.message.updated`, also execute
`references/shared/webhook-message-lifecycle-fixtures.json`. For receiver reliability,
error translation, replay, secret rotation, or callback-URL security, also read
`references/shared/integration-boundaries.md`. The OpenAPI reference mechanically lists the
six allowlisted endpoint-management operations: create, list, retrieve, update,
delete, and rotate-secret. Use the exact source-derived paths, methods,
operationIds, parameters, request/response schemas, and descriptions. Never
invent endpoint paths, event payload fields, retry behavior beyond the published
schedule, delivery semantics, or rotation choreography. The runtime reference
does confirm `YCloud-Signature`, HMAC-SHA256 over `<timestamp>.<raw-body>`, a
fast `2xx`, and seven retry intervals; do not put those facts in `CANNOT`. If
the reference is missing or its source hash/coverage drifts, report the drift
and stop.
Interpret `allOf` as schema composition and `x-*` extensions or generated model
names as codegen hints, not endpoint runtime behavior.

For explicitly requested sandbox/mock/no-real-side-effect receiver testing,
also read `references/shared/sandbox-contract.md`. Its local event producer and
`/_mock/*` transitions are synthetic test controls, not endpoint-management
operations or YCloud delivery guarantees.

## Workflow

1. Identify the intended endpoint operation and inspect only explicitly scoped,
   non-secret project files for runtime and deployment facts. Ask for missing
   facts; do not assume a framework, SDK, endpoint URL, environment, or secret
   store.
2. Match one of the six operations in the generated reference. Preserve exact
   path parameters, request/response schemas, and description-only constraints.
   Treat `operationId` as a contract identifier, never as an SDK method name.
3. Generate a raw HTTP or contract-aware typed example, or implement local
   request/receiver seams when authorized, with placeholders such as
   `<YCLOUD_API_KEY>`, `<ENDPOINT_ID>`, `<CALLBACK_URL>`, and synthetic values.
   Give SDK-specific code only when the user provides a confirmed artifact,
   version, and documentation. Do not make a live request or change a project.
4. Keep API keys and endpoint secrets server-side and out of browsers, mobile
   clients, URLs, logs, source control, and generated snippets. Never read,
   print, validate, or rotate a real credential.
5. In receiver mode, preserve the raw body bytes, require the exact lowercase
   `t=<unix-seconds>,s=<64-hex>` shape, and compute HMAC-SHA256 over ASCII
   timestamp, one period byte, and the unchanged body bytes. Add no trailing delimiter.
   Compare digest bytes in constant time against every
   explicitly configured candidate secret, and apply the configurable
   Developer Kit 300-second bidirectional tolerance before JSON processing.
   Resolve tenant identity from a trusted endpoint mapping, not an untrusted
   payload.
   Treat `X-Webhook-Endpoint-ID` as correlation metadata that must match the
   trusted route/configuration mapping. Never let that caller-controlled header
   select a tenant, secret, or inbox partition by itself.
   Do not parse or classify the event before successful verification. An invalid
   signature is rejected transport evidence, not a duplicate/conflict event.
   Persist a scoped inbox identity such as
   `(provider, webhook_endpoint_id, event_id)` and payload hash. Return `2xx`
   quickly (within 6 seconds is recommended) only after durable acceptance,
   then enqueue work. Label the 300-second tolerance, transport replay claim,
   and 24-hour event-inbox retention as recommended policy, not YCloud
   guarantees.
   Preserve `X-Webhook-Endpoint-ID` for routing/correlation without logging
   secrets.
6. In endpoint-design mode, require a publicly reachable URL, reject private or
   internal IPs, prefer HTTPS, and account for the documented limit of 20
   endpoints per account. List operations use 1-based page-number pagination
   with `page` and `limit` 1..100 and optional `includeTotal`. Parse the response
   as the merged Page envelope: required `offset`, `limit`, `length`, endpoint
   `items`, and optional `total`; do not send `offset` as a query parameter or
   unwrap a nonexistent `data` field.
7. Apply the recommended durable-acceptance response boundary: invalid
   signature returns `401` without enqueue; invalid common envelope before
   persistence returns `400`; a same-hash duplicate or durably recorded unknown
   event returns `2xx`; an inbox persistence failure returns `503`; business
   failure after the earlier `2xx` uses internal retry/DLQ. For a scoped event-ID
   collision with a different hash, quarantine and alert, and acknowledge only
   after the conflict is durably recorded. Label this matrix as platform policy,
   not a YCloud response schema.
   Never deduplicate by event type, `whatsappMessage.id`, status, `wamid`, or
   payload hash alone. Keep `inboxClassification` separate from message
   `projectionOutcome`: different event IDs for one message are new events even
   when a projection is unchanged or out of order. Ignore the Sandbox
   classification header and compute classification from verified bytes.
8. Explain response handling only from the references. Separate endpoint
   registration state from payload receipt and message delivery. If the user
   wants to send a message after endpoint setup, hand off to
   `ycloud-whatsapp-messages`.
9. Use the shared TSV vectors when generating or testing Java, Node, Go, or PHP
   verification code. The wrong-secret, stale/future timestamp, tampered body,
   JSON-reserialized body, trailing-delimiter, and malformed-header rows must
   fail. Do not create replacement vector values inside the response.
10. Provide synthetic tests for request validation, public-URL checks, endpoint
   count/pagination boundaries, endpoint identity mapping,
   raw-body signature verification, invalid/missing/stale signatures, same-event
   duplicate/conflict, distinct status events for one message, repeated status
   with a distinct event ID, out-of-order observations, unfamiliar event types,
   fast acknowledgement, duplicate/conflict events causing no projection side
   effects, invalid signatures creating no business-inbox row, trusted-route/header
   endpoint mismatch rejection, temporary URL suspension/automatic resume observability, response handling,
   and the chosen handoff. Do not call YCloud or deliver callbacks.

## High-risk delete and secret rotation

Treat delete and rotate-secret as high-risk external side effects. Stop before
execution, identify the target and impact, request explicit confirmation in a
future approved workflow, and state rollback or cutover considerations only when
confirmed by the contract or project facts. Receiver code may support an
explicit candidate-secret list, but do not claim that a provider dual-secret
window, old-secret validity period, atomic rotation, or recovery path exists.
The Skill never deletes endpoints, rotates secrets, or performs any other API
mutation.

SSRF controls belong to endpoint registration, not the receiver. For a project
that accepts callback URLs, propose scheme/port/redirect/DNS validation and
reject private, loopback, link-local, and metadata addresses, including DNS
rebinding checks. Treat IP allowlists and mTLS as project-dependent unless the
provider publishes stable support. Minimize raw payload retention; if required,
encrypt it, restrict access, and use a reviewed retention period.

## Outcome requirements

Adapt the result to planning, implementation, or evaluation. Preserve these
contract and evidence outcomes:

1. **Matched contract** — source hash, selected operation, exact path/method,
   parameters, request/response schemas, and confirmed constraints.
2. **Endpoint management plan** — placeholder raw HTTP or project-local
   construction and the selected create/list/retrieve/update/delete/rotate branch.
3. **Safety and boundary** — server-side credential placement, high-risk stop,
   and explicit separation of endpoint management from receiver processing.
4. **Tests** — synthetic contract and negative tests with no live endpoint/API.
5. **CANNOT** — event-type fields not covered by a selected payload reference,
   provider-fixed timestamp tolerance, provider retention, rotation
   overlap/rollback,
   unconfirmed SDK methods, missing project facts, unsupported operations, and
   actions not run. Do not list the confirmed HMAC/retry/acknowledgement rules.
6. **Handoff** — route message sending to `ycloud-whatsapp-messages`; return to
   Architect with selected operation and `crosscutting:webhook-receiver` row
   statuses, changed or proposed artifacts, tests/results, endpoint-to-receiver
   boundary, unknowns, and outgoing handoffs. Select an event-specific payload
   reference before mapping domain fields.

## Non-goals

This Skill does not send messages, upload media, manage templates, read real
credentials, call YCloud, deliver a callback, or mutate production configuration.
Receiver and endpoint client code may be implemented locally only when requested,
must use synthetic/no-network tests, and must state that no external operation
was performed.

Referenced files: 10

View saved version →

---
name: ycloud-whatsapp-business-accounts
description: Design, implement locally, or evaluate YCloud WhatsApp Business Account listing, retrieval, and automatic creative optimization operations. Use for WABA inventory or ACO integration; exclude phone-number management, messaging, template lifecycle, broad planning, and real API mutations.
---

# YCloud WhatsApp Business Accounts

Design or implement contract-aware support for the four WABA operations in the
generated reference. Never call YCloud or Meta, read credentials or customer
data, or mutate a real WABA.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor Architect handoffs for `scope`, `deliverable`, `mutation`, capability IDs,
project seams, and expected evidence. Without one, default to focused,
read-only guidance unless the user explicitly requests local implementation.
Local-write authorization permits request models/builders, adapters, handlers,
service bindings, mocks, synthetic fixtures, and no-network tests inside
the scoped project. The ACO PATCH operation is mock-only: local implementation
does not authorize a real enrollment update. Reuse the project's existing
interface stack and preserve concurrent work.

Load [the generated OpenAPI reference](references/openapi.md) and
[the reviewed runtime reference](references/runtime.md) only after this skill is
selected. If retry, idempotency, queueing, or error translation is requested,
also read `references/shared/integration-boundaries.md`. Exact paths, schemas,
responses, and descriptions come from `openapi.md`; cross-cutting pagination,
error, request-ID, rate-limit, and compatibility behavior comes from
`runtime.md`. If either generated reference is missing, stale, or inconsistent
with its recorded source hash and operation count, report drift and stop rather
than reconstructing the contract from memory.
For WABA list work, also read
[`references/shared/pagination-contract.md`](references/shared/pagination-contract.md).

## Exact operation scope

| Intent | Method and path | operationId |
| --- | --- | --- |
| List WABAs | `GET /whatsapp/businessAccounts` | `whatsapp_business_account-list` |
| Retrieve one WABA | `GET /whatsapp/businessAccounts/{id}` | `whatsapp_business_account-retrieve` |
| Retrieve ACO enrollment | `GET /whatsapp/businessAccounts/{wabaId}/automatic-creative-optimizations` | `whatsapp_waba-retrieve-automatic-creative-optimizations` |
| Partially update ACO enrollment | `PATCH /whatsapp/businessAccounts/{wabaId}/automatic-creative-optimizations` | `whatsapp_waba-update-automatic-creative-optimizations` |

Phone-number inventory and configuration belong to
`ycloud-whatsapp-phone-numbers`. Message submission/retrieval belongs to
`ycloud-whatsapp-messages`; template lifecycle and analytics belong to
`ycloud-whatsapp-templates`; authentication-only work belongs to
`ycloud-api-authentication`; broad multi-domain planning belongs to
`ycloud-integration-architect`. Readiness, repository maintenance, and issue
tracking are out of scope.

## Contract-first workflow

1. Match only an allowlisted operation and report its exact method, path,
   operationId, parameters, request/response schemas, and documented responses.
   Treat `operationId` and `x-*` fields as identifiers or codegen hints, not SDK
   method names or business rules. Use a project SDK only when its actual
   artifact, version, and method are confirmed.
2. Keep every WABA ID as an opaque, case-sensitive string. Do not parse prefixes,
   coerce it to a number, infer ownership, or rewrite it. Preserve the source's
   exact path parameter name: `{id}` for retrieve and `{wabaId}` for ACO.
3. For list, use 1-based `page`, `limit` from 1 through 100, and the documented
   defaults. Request `includeTotal=true` only when a count is needed, and apply
   `filter.accountReviewStatus` only as the source-defined string filter. Do not
   invent an enum or infer account eligibility from a review status. Parse the
   response as the merged Page envelope with required `offset`, `limit`,
   `length`, WABA `items`, and optional `total`; do not use response `offset` as
   a request parameter. Preserve
   unknown response properties and enum/status values.
4. For ACO GET, preserve the distinction between the response's extensible map
   and the PATCH request's closed map. GET returns Meta string fields without
   feature-key filtering, status validation, or case normalization; a successful
   response without the expected upstream object yields an empty
   `creativeOptimizationFeatures` object. Do not silently discard unknown keys
   or normalize unknown values.
5. For ACO PATCH, require the non-empty `creativeOptimizationFeatures` object,
   accept only the feature keys and `OPT_IN`/`OPT_OUT` values enumerated by the
   generated schema, and send only intended changes. The operation is a partial
   update: omitted keys are not a request to reset them. The contract says
   YCloud does not persist enrollment locally and does not pre-check Meta MM
   Lite/ACO onboarding; do not add either behavior as a claimed YCloud rule.
6. Keep contract facts separate from project policy. Input validation, approval
   UX, an audit record, an idempotency ledger, retry budgets, and rollback
   controls may be recommended or implemented locally when requested, but must
   be labeled application-owned. A mutating timeout is ambiguous; never replay
   ACO PATCH automatically. Honor documented `Retry-After` before later traffic
   without treating it as proof that replay is safe.
7. Use placeholders such as `<YCLOUD_API_KEY>`, `<WABA_ID>`, and synthetic
   feature values. Keep authentication server-side and hand credential storage
   to `ycloud-api-authentication`; do not inspect `.env`, secret stores, logs, or
   live responses.

## Validation and evidence

For local implementation, add no-network tests for operation routing, exact
parameter names, opaque/string IDs, pagination boundaries/defaults, optional
totals, filter encoding, standard error/request-ID mapping, unknown response
fields and enum values, ACO GET's extensible/empty map behavior, and ACO PATCH's
non-empty closed-key map, enum validation, partial-update construction, and
ambiguous-timeout/no-replay behavior. Mocks must prove that no network client is
invoked.

Return these sections, adapted to the requested deliverable:

1. **Matched contract** — source hash, selected operations, exact request and
   response shapes, and description-only constraints.
2. **Construction or implementation** — placeholder HTTP/project-local design,
   changed artifacts, and project facts still needed.
3. **Contract versus policy** — identify YCloud guarantees separately from local
   validation, approvals, persistence, retries, and rollback choices.
4. **Tests and evidence** — synthetic cases and actual no-network results.
5. **CANNOT** — real API/Meta calls, credentials/customer data, guessed SDK
   methods, unsupported operations, unknown lifecycle behavior, and any missing
   facts. Do not put confirmed pagination, error-envelope, request-ID, or ACO
   behavior in `CANNOT`.
6. **Handoff** — pass the selected opaque WABA ID to
   `ycloud-whatsapp-phone-numbers`; after a phone number is selected, route
   sending/retrieval to `ycloud-whatsapp-messages` and template lifecycle or
   analytics to `ycloud-whatsapp-templates`. Return to Architect with capability
   status, artifacts, tests, unknowns, and outgoing handoffs.

## Safety stop

YCloud Provider API calls are prohibited during Skill execution, including
nominally read-only GETs. All mutations are mock-only. Stop before any request
that would use a real API key, WABA/customer identifier, or live YCloud/Meta
resource.

Referenced files: 5

View saved version →

---
name: ycloud-whatsapp-calling
description: Design, implement locally, or evaluate YCloud WhatsApp Calling connect, pre-accept, accept, reject, terminate, and call-media download operations. Use for API-sourced call sessions after Phone Numbers and Webhook Receiver handoffs; exclude calling settings, media upload, message operations, and real API calls.
---

# YCloud WhatsApp Calling

Design or implement contract-aware WhatsApp Calling session commands and call
media downloads. Keep every example synthetic and every transport mock-only;
never call YCloud or Meta, inspect credentials or customer data, or claim that a
real call changed state.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor Architect handoffs for scope, deliverable, mutation, capability IDs,
project seams, and evidence. Without one, default to focused read-only guidance
unless the user explicitly requests local implementation. Local-write
authorization permits trusted-server request builders, adapters, handlers,
state models, synthetic webhook fixtures, mock transports, and no-network tests
inside the scoped project. It never authorizes a real call command or media
download.

After this Skill is selected, read the generated [OpenAPI
contract](references/openapi.md) and reviewed [runtime
behavior](references/runtime.md). If retry, idempotency, queueing, error
translation, or production architecture is requested, also read
`references/shared/integration-boundaries.md`. If either Calling reference is
missing, stale, or inconsistent with the pinned source hash and operation count,
report drift and stop rather than reconstructing the contract from memory.

## Exact operation scope

| Intent | Method and path | operationId |
| --- | --- | --- |
| Connect an outbound call | `POST /whatsapp/calls/connect` | `whatsapp_call-connect` |
| Pre-accept an inbound call | `POST /whatsapp/calls/preAccept` | `whatsapp_call-pre-accept` |
| Accept an inbound call | `POST /whatsapp/calls/accept` | `whatsapp_call-accept` |
| Reject an inbound call | `POST /whatsapp/calls/reject` | `whatsapp_call-reject` |
| Terminate an active call | `POST /whatsapp/calls/terminate` | `whatsapp_call-terminate` |
| Download call recording/transcription | `GET /whatsapp/calls/media/{mediaAssetId}` | `whatsapp_call-download-media` |

Calling/capture configuration belongs to `ycloud-whatsapp-phone-numbers`.
Webhook signature verification, raw-body handling, durable acceptance,
deduplication, and event parsing belong to the Webhook Receiver. Media upload
belongs to `ycloud-whatsapp-media`; WhatsApp message submission and message IDs
belong to `ycloud-whatsapp-messages`; authentication belongs to
`ycloud-api-authentication`; broad multi-domain planning belongs to
`ycloud-integration-architect`.

## Required incoming handoffs

- **Phone Numbers:** consume a separately confirmed WhatsApp Business
  `phoneId`, source E.164 phone number, and Calling/capture readiness evidence.
  Settings or registration success is only prerequisite evidence; it does not
  authorize a call command or prove that a call can connect.
- **Webhook Receiver:** consume only a signature-verified, durably accepted,
  deduplicated call event. For inbound pre-accept, accept, reject, or terminate,
  take `wacid` and `phoneId` from the parsed Call Connect/session event. For a
  recording or transcription, take `mediaAssetId`, `wacid`, `phoneId`, and
  `status` from the parsed media event. Do not alter the Receiver's already
  issued HTTP acknowledgement.

Never substitute one identifier for another. Keep these opaque, case-sensitive
values in separately named fields:

- `wacid`: WhatsApp call/session ID.
- `phoneId`: WhatsApp Business phone-number ID; not an E.164 phone number.
- `from` and `to`: E.164 phone-number strings; never numeric values.
- `recipient`: BSUID or parent BSUID; not a phone, call, message, or event ID.
- `event.id`: webhook envelope event ID; never a call-command identifier.
- message IDs and application correlation IDs: unrelated to Calling commands.
- `mediaAssetId`: call recording/transcription asset ID; only this value belongs
  in the media-download path.

## Contract-first workflow

1. Match only the six allowlisted operations. Report the pinned source hash,
   exact method/path, `operationId`, request schema, response schema, and
   description-only behavior. An `operationId` is not an SDK method name.
2. For outbound `connect`, require `from`, `sdpType: "offer"`, and SDP. Preserve
   the contract's `to`/`recipient` rule: provide exactly one; if an upstream
   caller supplies both, `to` takes precedence and `recipient` is ignored. Do
   not convert phone strings or BSUIDs into another identifier type.
3. For inbound `preAccept` and `accept`, require `phoneId`, `wacid`,
   `sdpType: "answer"`, and SDP. Pre-accept establishes the media connection to
   reduce connection time/audio clipping; accept begins media flow after the
   WebRTC connection. Do not skip local session-order validation merely because
   both endpoints share a request schema.
4. For `reject` and `terminate`, require only `phoneId` and `wacid`. Reject is
   for an incoming call; terminate is for an active call. Treat choosing the
   wrong lifecycle command as an application error, not as a retry strategy.
5. A `200` Calling response requires `success` and may return `wacid`. Interpret
   it only as the selected command being accepted or processed. It is not proof
   of ringing, connection, media flow, termination visibility, or any final session state.
   Correlate later verified call events by `wacid`, preserve
   duplicate/out-of-order/unknown states, and keep command records separate
   from the event-derived session projection.
6. Download call media only after a recording/transcription event reports
   `status: AVAILABLE` and supplies its own `mediaAssetId`. Encode that opaque ID
   as one path segment. Omit `Range` or send it blank; a non-empty `Range` is a
   documented `400` because byte ranges are unsupported. A `200` is the complete
   attachment, `Accept-Ranges` is `none`, recordings use `.ogg`, transcriptions
   use `.json`, and the owning tenant can download for 30 days. Treat `404` as
   intentionally non-disclosing across missing, unavailable, expired, or
   wrong-tenant assets.
7. Preserve the standard error envelope and redacted `YCloud-Request-ID` /
   `error.requestId`. Branch on HTTP status and `error.code`, never expose the
   diagnostic `error.message` directly to end users, and preserve unknown
   properties, event types, and statuses.
8. Do not automatically replay any Calling POST after timeout, connection loss,
   `429`, or an ambiguous response. `Retry-After` delays later traffic but does
   not make replay safe. A provider `retryable` flag on failed media processing
   concerns the upstream media operation; it does not authorize replay of a
   call command or download request. Require fresh session evidence and an
   explicit application-owned decision before any new command.
9. Use placeholders such as `<YCLOUD_API_KEY>`, `<PHONE_ID>`,
   `<SYNTHETIC_WACID>`, `<E164_PHONE_NUMBER>`, and `<MEDIA_ASSET_ID>`. Tests must
   use a fake transport that fails closed on real base URLs, credentials, or
   network clients.

## Media download handoff

Produce a typed handoff only after verified `whatsapp.call.recording.updated` or
`whatsapp.call.transcription.updated` evidence:

- event type, webhook `event.id`, `wacid`, `phoneId`, `mediaAssetId`, and
  `AVAILABLE` status, each in a separate field;
- owning-tenant context, media kind, 30-day expiry/freshness evidence, and the
  mock-only download authorization decision;
- complete-file semantics, expected `.ogg` or `.json` attachment, no byte-range
  support, redacted request ID, and destination/storage policy owned by the
  consuming application.

On `FAILED`, retain the structured `error.code` and `error.retryable` evidence
but do not construct a download request. Never pass `wacid`, `phoneId`, a
message ID, or `event.id` as `mediaAssetId`.

## Validation and evidence

For local implementation, add no-network tests for all six routes; exact body
requiredness; `offer` versus `answer`; `to`/`recipient` precedence; opaque ID and
E.164 preservation; lifecycle command selection; command acceptance versus
event-derived final state; duplicate/out-of-order/unknown events; timeout and
`429` no-replay behavior; standard errors/request IDs; `AVAILABLE` versus
`FAILED`; 30-day media eligibility; blank/non-empty `Range`; complete binary
responses and attachment metadata; `404` nondisclosure; and rejection of every
cross-ID substitution. Mocks must prove no network client is invoked.

Return these sections, adapted to the requested deliverable: **Matched
contract**, **Incoming handoffs**, **Construction or implementation**,
**Command versus session state**, **Media download handoff**, **Tests and
evidence**, **CANNOT**, and **Handoff**. Return capability status, artifacts,
results, unknowns, and outgoing handoffs to Architect when applicable.

## Safety stop

YCloud Provider API calls are prohibited during Skill execution, including the
media GET. Stop before any request using a real key, tenant, phone, call, event,
message, media, SDP, or customer identifier. Never claim a call or media
session changed in production.

Referenced files: 4

View saved version →

---
name: ycloud-whatsapp-flows
description: Design, implement locally, or evaluate all 9 YCloud WhatsApp Flows operations across draft creation, retrieval, metadata or structure updates, publishing, preview, deprecation, and deletion. Use for Flow lifecycle management; exclude Flow message sending and real API mutations.
---

# YCloud WhatsApp Flows

Design or implement contract-aware WhatsApp Flow lifecycle management against
mocks only. Never call YCloud, mutate a real Flow, open a live preview URL, read
credentials or customer data, or imply that managing a Flow sent a message.

## Execution and authority boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor an Architect handoff for `scope`, `deliverable`, `mutation`, capability
IDs, project seams, and evidence. Without one, default to focused, read-only
guidance unless the user explicitly requests local implementation. Local-write
authorization permits request models/builders, multipart adapters, handlers,
handler/service bindings, mocks, fixtures, and no-network tests inside the scoped
project. Every create, update, publish, deprecate, delete, or preview-link
invalidation remains mock-only; no authorization level in this Skill permits a
real API call.

Keep claims in three authority layers:

1. **Provider contract** — [references/openapi.md](references/openapi.md) and
   [references/runtime.md](references/runtime.md). State these as YCloud behavior.
2. **Developer Kit policy** — `references/shared/integration-boundaries.md` when
   retry, idempotency, queueing, error translation, or webhook reliability is in
   scope. Label its recommendations as local policy.
3. **Project decisions** — only facts confirmed in the user's scoped project.

Do not promote an `operationId`, generated model name, `x-*` extension, example,
platform recommendation, or project convention into provider behavior. If the
generated references are absent, stale, internally inconsistent, or do not list
all 9 operations below, stop and report the drift.

## Exact operation allowlist

Load both generated references after this Skill is selected. Match only these
operations and preserve every source-defined path/query parameter,
request/response schema, content type, status code, and description constraint.
For Flow list response adaptation, also read
[`references/shared/pagination-contract.md`](references/shared/pagination-contract.md).

| Intent | Method and path | operationId |
| --- | --- | --- |
| Create Flow | `POST /whatsapp/flows` | `whatsapp_flow-create` |
| List Flows | `GET /whatsapp/flows` | `whatsapp_flow-list` |
| Retrieve Flow | `GET /whatsapp/flows/{flowId}` | `whatsapp_flow-retrieve` |
| Update structure | `PATCH /whatsapp/flows/{flowId}/assets` | `whatsapp_flow-update-structure` |
| Update metadata | `PATCH /whatsapp/flows/{flowId}/metadata` | `whatsapp_flow-update-metadata` |
| Publish Flow | `POST /whatsapp/flows/{flowId}/publish` | `whatsapp_flow-publish` |
| Generate preview URL | `GET /whatsapp/flows/{flowId}/preview` | `whatsapp_flow-preview` |
| Deprecate Flow | `POST /whatsapp/flows/{flowId}/deprecate` | `whatsapp_flow-deprecate` |
| Delete Flow | `DELETE /whatsapp/flows/{flowId}` | `whatsapp_flow-delete` |

Flow interactive message composition and sending belong to
`ycloud-whatsapp-messages`, even when the Flow already exists. This Skill owns
only management of the Flow resource and its preview URL.

## Contract-first workflow

1. Confirm the selected operation and server-side project seam. Treat `flowId`,
   `cloneFlowId`, WABA IDs, request IDs, and later message IDs as opaque,
   case-sensitive strings; never parse example prefixes or formats. Preserve
   unknown response properties and enum/status values rather than failing
   exhaustive decoding or coercing them into a known lifecycle state.
   `whatsapp_flow-list` returns `{items: [...]}` without the common Page envelope;
   do not invent `page`, `offset`, `total`, `cursor`, or `data` fields.
2. Preserve create semantics: `wabaId`, `name`, and `categories` are required;
   a new Flow defaults to `DRAFT`. `flowJson` and `publish=true` can create it
   directly as `PUBLISHED`; `cloneFlowId` requires permission to the source Flow.
   Do not infer clone ownership, copy completeness, validation, or publish
   success beyond the returned contract.
3. Send structure updates as `multipart/form-data` with the required binary
   `flowJson` file field. Do not silently send JSON text under
   `application/json`. Preserve structured `validationErrors` on create and
   structure-update HTTP `400` responses, including unknown error codes and
   source locations. Metadata updates use JSON and only the source fields
   `name`, `categories`, and `endpointUri`.
4. Keep lifecycle gates exact: the status schema says `DRAFT` can be modified,
   `PUBLISHED` cannot be modified, and `DEPRECATED` cannot be used; delete says
   only `DRAFT` may be deleted; deprecate applies to a published Flow and states
   that published Flows cannot be modified or deleted. Do not mutate when status
   is absent or unknown.
5. Preserve the source conflict: the publish operation description also says a
   Flow can later be edited and returned to `DRAFT`, while the status and
   deprecate descriptions say a published Flow cannot be modified. These are
   equal-authority pinned OpenAPI statements. Report the contradiction and put
   post-publish editing/return-to-draft behavior in `CANNOT`; do not choose a
   rule, synthesize an endpoint, or weaken a lifecycle gate.
6. Preview generation returns a public, shareable URL. The reference says it
   expires after 30 days by default and `invalidate=true` generates a new link.
   Treat the URL as sensitive project output: do not open, crawl, log, commit,
   or expose a real URL. A GET with `invalidate=true` changes link state, so it
   remains a mock-only mutation despite its HTTP method.
7. Use placeholders and synthetic Flow JSON/data in examples and tests. Use an
   SDK method only when a confirmed SDK artifact and version exist in the
   project; operation IDs are not SDK methods. Keep `X-API-Key` injection on a
   trusted server through the Authentication handoff without reading a real key.
8. Treat mutating timeouts or lost responses as ambiguous outcomes. Never
   blindly replay create, structure/metadata update, publish, deprecate, delete,
   or preview invalidation. Any idempotency ledger, outbox, retry budget,
   reconciliation job, rollback artifact, or version history is project
   architecture unless the generated runtime reference confirms it.

## Lifecycle and message boundary

An HTTP `200`/`success=true` applies only to the selected Flow management
operation. It is not proof that a Flow message was submitted, accepted,
delivered, opened, completed, or reached any other user state. Publication makes
the management operation successful under the returned contract; sending and
tracking an interactive message remains a separate Messages workflow.

When a user wants to send a Flow, hand `ycloud-whatsapp-messages` the opaque Flow
ID, confirmed current status, and only the message-composition fields supported
by its generated contract. Preserve `DEPRECATED` as unusable and do not infer
message eligibility when status is unknown or when the lifecycle conflict above
matters. Messages owns request construction, message acceptance, YCloud message
ID correlation, retrieve/status handling, and accepted-versus-final semantics.

## Mutation safeguards and tests

Publish, deprecate, delete, clone, replacement of Flow JSON, endpoint URI
changes, and preview invalidation can be disruptive or irreversible. Implement
only local mock behavior and no-network tests. For any future external workflow,
stop before the call, identify the exact opaque Flow/WABA IDs and impact, require
explicit operation-specific confirmation, and treat an ambiguous result as
unresolved. Never claim rollback is available unless the provider contract or
project proves it.

Tests should cover every selected route and schema plus relevant negative cases:
required create fields, draft and create-and-publish branches, clone permission
as an external precondition, category/status unknown handling, exact multipart
encoding, validation-error preservation, metadata field mapping, each lifecycle
gate, the post-publish contradiction stop, draft-only delete, preview expiry and
invalidation behavior, public-URL redaction, provider error/request-ID mapping,
ambiguous mutation outcomes, and the Flow-to-Messages boundary.

## Outcome requirements

Return the matched operation IDs and exact method/paths, authority-labeled
contract facts, lifecycle preconditions/conflicts, project-local artifacts or
proposed seams, no-network test evidence, and explicit unknowns. Do not claim an
operation implemented because only a route label, button, sample JSON, or mock
response exists; link each implemented row to its adapter/handler and behavioral
tests.

### CANNOT

List unsupported operations, missing project facts, the unresolved published
Flow editing contradiction, unconfirmed SDK behavior, live preview URLs,
credentials/customer data, real API calls, external mutations, blind replay,
invented rollback, and message delivery/completion claims. Do not put confirmed
draft creation, draft-only deletion, deprecation, preview expiry/invalidation,
or validation-error behavior into `CANNOT`.

### Handoff

Send Flow message composition, submission, retrieval, and status tracking to
`ycloud-whatsapp-messages` with Flow ID, status evidence, and message IDs kept as
separate opaque values. Send authentication storage to
`ycloud-api-authentication` and webhook endpoint/receiver work to
`ycloud-webhook-endpoints`. Return to Architect with capability-row status,
changed or proposed artifacts, tests/results, lifecycle evidence and conflicts,
unknowns, and outgoing handoffs.

Referenced files: 5

View saved version →

---
name: ycloud-whatsapp-groups
description: Design, implement locally, or evaluate all 12 YCloud WhatsApp Groups operations, including asynchronous lifecycle tracking, join requests, participants, settings, invite links, and the invite-link message handoff. Use for group management; exclude ordinary or Flow message sending, Flow lifecycle, and real API mutations.
---

# YCloud WhatsApp Groups

Design or implement contract-aware WhatsApp group management against mocks only.
Never call YCloud, perform a real group or message mutation, read credentials or
customer data, or claim that an accepted request reached its final state.

## Execution and authority boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor an Architect handoff for `scope`, `deliverable`, `mutation`, capability
IDs, project seams, and evidence. Without one, default to focused, read-only
guidance unless the user explicitly requests local implementation. Local-write
authorization permits request models/builders, adapters, handlers, service
bindings, mocks, fixtures, and no-network tests inside the scoped project. Every
mutating operation remains mock-only; local-write authorization does not
authorize a real create, delete, update, participant action, invite-link reset,
join-request action, or message send.

Keep claims in three authority layers:

1. **Provider contract** — [references/openapi.md](references/openapi.md) and
   [references/runtime.md](references/runtime.md). State these as YCloud behavior.
2. **Developer Kit policy** — `references/shared/integration-boundaries.md` when
   retry, idempotency, queueing, error translation, or webhook reliability is in
   scope. Label its recommendations as local policy.
3. **Project decisions** — only facts confirmed in the user's scoped project.

Do not promote an `operationId`, generated model name, `x-*` extension, example,
platform recommendation, or project convention into provider behavior. If the
generated references are absent, stale, internally inconsistent, or do not list
all 12 operations below, stop and report the drift.

## Exact operation allowlist

Load both generated references after this Skill is selected. Match only these
operations and preserve every source-defined path parameter, query parameter,
request/response schema, status code, and description constraint.
For either list operation, also read
[`references/shared/pagination-contract.md`](references/shared/pagination-contract.md).

| Intent | Method and path | operationId |
| --- | --- | --- |
| Create group | `POST /whatsapp/{businessPhoneNumber}/groups` | `whatsapp_group-create` |
| List groups | `GET /whatsapp/{businessPhoneNumber}/groups` | `whatsapp_group-list` |
| Retrieve group | `GET /whatsapp/{businessPhoneNumber}/groups/{groupId}` | `whatsapp_group-retrieve` |
| Delete group | `DELETE /whatsapp/{businessPhoneNumber}/groups/{groupId}` | `whatsapp_group-delete` |
| Retrieve invite link | `GET /whatsapp/{businessPhoneNumber}/groups/{groupId}/inviteLink` | `whatsapp_group-retrieve-invite-link` |
| Reset invite link | `POST /whatsapp/{businessPhoneNumber}/groups/{groupId}/inviteLink/reset` | `whatsapp_group-reset-invite-link` |
| Send invite-link message | `POST /whatsapp/{businessPhoneNumber}/groups/inviteLink/messages` | `whatsapp_group-send-invite-link-message` |
| List join requests | `GET /whatsapp/{businessPhoneNumber}/groups/{groupId}/joinRequests` | `whatsapp_group-list-join-requests` |
| Approve join requests | `POST /whatsapp/{businessPhoneNumber}/groups/{groupId}/joinRequests/approve` | `whatsapp_group-approve-join-requests` |
| Reject join requests | `POST /whatsapp/{businessPhoneNumber}/groups/{groupId}/joinRequests/reject` | `whatsapp_group-reject-join-requests` |
| Update settings | `PATCH /whatsapp/{businessPhoneNumber}/groups/{groupId}/settings` | `whatsapp_group-update-settings` |
| Remove participants | `POST /whatsapp/groups/{groupId}/participants/remove` | `whatsapp_group-remove-participants` |

The participant-removal path intentionally omits `{businessPhoneNumber}`. Do
not normalize it to the shape of the other endpoints. Group conversation message
composition or sending belongs to `ycloud-whatsapp-messages`; only the dedicated
invite-link-message operation remains in this Skill. Flow lifecycle belongs to
`ycloud-whatsapp-flows`.

## Contract-first workflow

1. Confirm the selected operation and server-side project seam. Keep
   `businessPhoneNumber` in source-required E.164 form. Treat `groupId`,
   `joinRequestId`, `requestId`, user/parent-user IDs, message IDs, and cursors as
   opaque, case-sensitive strings; never parse examples, prefixes, suffixes, or
   cursor contents. Preserve unknown response properties and enum/event values.
2. Preserve request invariants exactly. Group create requires `subject`, applies
   source length limits, and defaults omitted `joinApprovalMode` to
   `auto_approve`. Settings updates require at least one of `subject` or
   `description`. Participant removal supports at most eight entries, each with
   exactly one of `user` or `fromUserId`; `userId` is a documented alias for
   `fromUserId`. Join-request actions pass the opaque IDs returned by list and
   retain per-item failures instead of treating a mixed result as atomic.
3. Preserve cursor pagination for group and join-request lists: `limit` is 1 to
   1024 with a default of 25, and `before`/`after` are opaque. Do not invent page
   numbers, totals, stable ordering, or combine both cursor directions unless
   the generated reference explicitly permits it. Parse the provider response as
   `{data: [...], paging?: {before?, after?}}`; it is not the common
   `offset/limit/length/items` Page envelope.
4. For invite-link messages, require an approved template name, language code,
   ordered body parameters, and one `type=group_id` parameter whose `group_id`
   is the target group ID. The message goes to one user, not into the group.
   Exactly one of `to` or `recipient` is required; if both exist, resolve and
   validate `to` first and ignore `recipient` completely. Never fall back to
   `recipient` when `to` is invalid. Hand accepted message state to Messages.
5. Use placeholders and synthetic IDs/data in examples and tests. Use an
   SDK-specific method only when the project contains a confirmed SDK artifact
   and version; an `operationId` is not an SDK method. Keep `X-API-Key` injection
   server-side through the Authentication handoff without reading a real key.
6. Treat mutating timeouts or lost responses as ambiguous outcomes. Never
   blindly replay a create, delete, update, participant action, invite-link
   reset, join-request action, or message send. Any outbox, idempotency key,
   retry budget, or reconciliation job is project architecture unless the
   generated runtime reference says otherwise.

## Accepted versus final state

Create, delete, settings update, and participant removal return
`WhatsappGroupAsyncResponse`: HTTP `200`, `status=pending`, and `requestId` mean
only that YCloud accepted the asynchronous request. Preserve `requestId` for
correlation with the separately confirmed group webhook event; do not label the
group created/deleted/updated or participants removed at acceptance time.

Join-request approve/reject responses are itemized processing results; preserve
approved/rejected IDs, failed items, and unknown errors. Invite-link reset returns
the new link synchronously but says nothing about message delivery. Invite-link
message HTTP `200` returns `WhatsappMessage` and means message-request acceptance,
not delivery. Send its YCloud message ID and accepted state to
`ycloud-whatsapp-messages`, which owns retrieve/status handling and the
accepted-versus-final boundary. Webhook endpoint management and receiver
reliability belong to `ycloud-webhook-endpoints`.

## Mutation safeguards and tests

Deletes, participant removals, join-request decisions, invite-link resets, and
settings changes can be disruptive or irreversible. Implement only local mock
behavior and no-network tests. For any future external workflow, stop before the
call, identify the exact opaque target IDs and impact, require explicit
operation-specific confirmation, and treat an ambiguous result as unresolved.

Tests should cover every selected route and schema plus relevant negative cases:
path asymmetry, E.164 validation, subject/description limits, join mode default,
cursor bounds/opacity, empty or mixed join-request outcomes, partial failures,
participant count and exactly-one identifier rules, unknown properties/statuses,
provider error/request-ID mapping, and accepted-versus-final correlation.

For invite-link messages, executable tests must cover neither recipient field,
each field alone, both valid fields selecting `to`, valid `to` with malformed or
wrong-typed `recipient` behaving exactly like `to` alone, invalid `to` with valid
`recipient` rejecting without fallback, the required `group_id` parameter, and
the fact that acceptance is not delivery.

## Outcome requirements

Return the matched operation IDs and exact method/paths, authority-labeled
contract facts, project-local artifacts or proposed seams, no-network test
evidence, asynchronous correlation behavior, and explicit unknowns. Do not
claim an operation implemented because only a route label, button, sample JSON,
or mock response exists; link each implemented row to its adapter/handler and
behavioral tests.

### CANNOT

List unsupported operations, missing project facts, source conflicts, unconfirmed
SDK behavior, live credentials/customer data, real API calls, external
mutations, automatic replay, final-state assumptions, and delivery claims.
Do not move documented async `pending`/`requestId` behavior or known partial
join-request results into `CANNOT`.

### Handoff

Send ordinary group messages and invite-link-message post-acceptance tracking to
`ycloud-whatsapp-messages` with the YCloud message ID kept separate from group,
request, and project correlation IDs. Send Flow lifecycle to
`ycloud-whatsapp-flows`, authentication storage to
`ycloud-api-authentication`, and webhook endpoint/receiver work to
`ycloud-webhook-endpoints`. Return to Architect with capability-row status,
changed or proposed artifacts, tests/results, accepted-versus-final evidence,
unknowns, and outgoing handoffs.

Referenced files: 5

View saved version →

---
name: ycloud-whatsapp-inbound-messages
description: Design, implement locally, or evaluate the two YCloud WhatsApp inbound-message acknowledgement operations for marking a received message as read or showing a typing indicator. Use after verified inbound-message receipt; exclude webhook receiving, message sending, and real API operations.
---

# YCloud WhatsApp Inbound Messages

Design or implement contract-aware acknowledgement of an already received
WhatsApp message. Keep all examples synthetic and every operation side effect
behind a mock transport; never call YCloud, read credentials or customer data,
or claim that a real read receipt or typing indicator was produced.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor an Architect handoff for scope, deliverable, mutation, capability IDs,
project seams, and evidence. Without one, default to focused read-only guidance
unless the user explicitly requests local implementation. Local-write
authorization permits server-side request builders, adapters, handlers, mock
transport bindings, synthetic fixtures, and no-network tests in the scoped
project. It does not authorize a real API call or a browser/mobile integration
that exposes `X-API-Key`.

## Scope and handoffs

After this Skill is selected, read the generated [OpenAPI
contract](references/openapi.md) and reviewed [runtime
behavior](references/runtime.md). If retry, idempotency, error translation, or
production architecture is requested, also read
`references/shared/integration-boundaries.md`. If either generated reference is
missing, stale, or conflicts with the pinned source, report the drift and stop
instead of guessing.

The allowlist is exact:

| Intent | Method and path | operationId |
| --- | --- | --- |
| Mark received message as read | `POST /whatsapp/inboundMessages/{id}/markAsRead` | `whatsapp_inbound_message-mark-as-read` |
| Mark as read and show typing | `POST /whatsapp/inboundMessages/{id}/typing` | `whatsapp_inbound_message-typing` |

The Webhook Receiver owns signature verification, exact raw-body handling,
durable acceptance, deduplication, and parsing of
`whatsapp.inbound_message.received`. This Skill begins only after that boundary.
Consume `event.whatsappInboundMessage.id` or its `wamid`; never substitute the
webhook envelope's `event.id`. Return acknowledgement results to the receiver's
asynchronous business-processing path without changing its already-issued HTTP
response.

Route message composition or sending to `ycloud-whatsapp-messages`, API-key
configuration to `ycloud-api-authentication`, webhook endpoint/receiver work to
`ycloud-webhook-endpoints`, and broad multi-domain work to
`ycloud-integration-architect`. Readiness and repository-maintenance workflows
are outside this Skill.

## Contract-first workflow

1. Confirm the selected operation's source hash, exact method/path,
   `operationId`, path parameter, response schemas, and descriptions in the
   generated references. Do not infer SDK methods from operation IDs.
2. Treat `{id}` as an opaque, case-sensitive path value. The operation accepts
   the YCloud inbound-message ID or the original WhatsApp `wamid`. Preserve the
   value, encode it as one URL-path segment, support contract-compatible future
   formats, and never parse prefixes or impose a local wamid grammar. Neither
   operation has a request body.
3. Preserve the effects exactly. `markAsRead` also marks earlier messages in
   the conversation as read. `typing` does the same and displays a typing
   indicator until a response is sent or 25 seconds elapse. Repeating `typing`
   refreshes the indicator, and the contract defines no idempotency key.
4. Interpret responses without filling gaps. `markAsRead` documents an empty
   `200` and a `404 ErrorResponse`. `typing` documents `200
   WhatsappInboundMessageTypingResponse` with `success: true`, plus
   `400`, `401`, `403`, `404`, `429`, and `500` `ErrorResponse` bodies. Preserve
   unknown properties and status/code values. Do not invent response bodies,
   endpoint errors, or delivery/read guarantees.
5. At the provider adapter, retain the standard error envelope and
   `YCloud-Request-ID` (or `error.requestId`) for redacted correlation. Branch on
   HTTP status and `error.code`, not diagnostic `error.message`. If the project
   translates errors, do so only at its own northbound boundary and label that
   mapping as project policy.
6. On `429`, honor `Retry-After` before another request and parse beta
   `RateLimit-*` headers defensively. Do not invent an inbound-operation quota.
   A typing repeat is a new visible side effect, not a harmless retry; do not
   automatically replay it after a timeout, connection loss, or ambiguous
   response. The source does not establish idempotency or replay safety for
   `markAsRead` either, so do not blindly replay that POST.
7. Use only a fake or mock HTTP transport for implementation evidence. Tests
   may assert a captured synthetic request and fixture response, but must fail
   closed if configured with a real base URL, credential, or network transport.

## Illustrative raw HTTP

These shapes are documentation only; do not execute them:

```http
POST <YCLOUD_API_BASE_URL>/whatsapp/inboundMessages/<SYNTHETIC_INBOUND_MESSAGE_ID>/markAsRead
X-API-Key: <YCLOUD_API_KEY>
```

```http
POST <YCLOUD_API_BASE_URL>/whatsapp/inboundMessages/<SYNTHETIC_WAMID>/typing
X-API-Key: <YCLOUD_API_KEY>
```

Do not put real IDs, keys, phone numbers, payloads, or customer identifiers in
examples, fixtures, URLs, or logs.

## Outcome requirements

Adapt the result to planning, implementation, or evaluation, while making these
items explicit:

1. **Matched contract** — selected operation IDs, methods/paths, source hash,
   path-ID provenance, response shapes, and documented side effects.
2. **Receiver handoff** — verified/durably accepted event precondition and the
   precise `whatsappInboundMessage.id` or `wamid` field used; keep the event ID
   distinct.
3. **Integration placement** — trusted-server adapter, mock transport seam,
   placeholder authentication handoff, and redacted request-ID observability.
4. **Response and rate handling** — exact documented statuses, standard error
   envelope, unknown-value preservation, `Retry-After`, and ambiguous-outcome
   behavior without blind POST replay.
5. **Tests** — no-body request construction, path-segment encoding, opaque and
   case-sensitive ID preservation, inbound ID versus wamid selection, rejection
   of an event ID substituted for a message ID, empty `200` handling for
   `markAsRead`, `success: true` for `typing`, every documented error fixture,
   request-ID mapping, `429` scheduling, timeout ambiguity, repeated-typing
   semantics, and proof that no network call occurs.
6. **CANNOT** — real read/typing operations, credentials or customer data,
   webhook verification/acknowledgement, message sending, inferred SDK methods,
   invented quotas/errors, general idempotency, blind replay, or claims about
   what a user actually saw.
7. **Handoff** — return capability-row status, changed or proposed artifacts,
   tests/results, unknowns, and outgoing Receiver, Authentication, Messages, or
   Architect handoffs. State when no handoff is needed.

## Safety and source priority

Use the pinned OpenAPI source first, generated references second, and this
workflow third. Keep provider contract, reviewed runtime facts, and project
policy visibly separate. External mutations remain prohibited even when local
implementation is authorized.

Referenced files: 4

View saved version →

---
name: ycloud-whatsapp-media
description: Design, implement locally, or evaluate the YCloud WhatsApp media upload contract, multipart request and response handling, and media-to-message handoff. Use for media upload integration; do not use for sending messages, template lifecycle, readiness, broad integration planning, or real API operations.
---

# YCloud WhatsApp Media

Design or implement a contract-aware media upload integration. Keep this skill
limited to the one media-upload operation and the handoff that follows it.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor Architect handoffs for `scope`, `deliverable`, `mutation`, capability IDs,
project seams, and expected evidence. Without one, default to focused scope and
read-only guidance unless the user explicitly requests local implementation.
Local-write authorization permits multipart builders, adapters, handlers,
test-console bindings, synthetic fixtures, and no-network tests inside the scoped
project. It does not authorize opening or transmitting a real user file or
calling the upload API. Reuse the project's existing UI/interface stack; do not
create a dashboard or select a framework without user/project support.

## Trigger boundary

Use this skill when the user asks to upload WhatsApp media, construct the upload
request, interpret its response, or connect an upload result to a later message.
Route these requests elsewhere:

- Send a message, including a message that references an existing media object: hand off to `ycloud-whatsapp-messages`.
- Create, edit, list, retrieve, delete, or analyze a template: hand off to `ycloud-whatsapp-templates`.
- Design a multi-domain YCloud integration: hand off to `ycloud-integration-architect`.
- Check Developer Kit readiness or run repository-maintenance/issue-tracker workflows: do not trigger this skill.
- Download, inspect, or transmit a real local file: stop and use a synthetic fixture instead.

Do not load the complete OpenAPI document. Read only
`references/openapi.md` and `references/runtime.md` after this skill has been selected. If retry, idempotency, queueing, or error translation is requested, also read `references/shared/integration-boundaries.md`. Treat the exact
source path, method, operationId, schema, and constraints in that generated
reference as authoritative. If the reference is missing, stale, or conflicts
with the pinned source, report the drift and stop rather than guessing.

## Workflow

1. Identify the server-side project location and runtime only from files the user
   explicitly places in scope. Ask for missing facts; do not assume a framework,
   SDK, package, deployment, or credential source. When local writes are
   authorized, preserve existing project patterns and concurrent edits.
2. Select the single upload operation documented in the reference:
   `POST /whatsapp/media/{phoneNumber}/upload`, operationId
   `whatsapp_media-upload`. Preserve its path parameter, multipart content type,
   required fields, request schema, response schema, and documented descriptions
   exactly as generated. Apply the standard error envelope, request ID, generic
   `429` headers, documented `413 CONTENT_TOO_LARGE`, the one-file rule,
   reviewed media type/size limits, and 30-day persistence from `runtime.md`.
   Reject multiple files locally even though the API would process only the
   first. Do not invent a media-specific quota, safe replay rule, idempotency,
   or durable retention beyond that period.
   Interpret `allOf` as schema composition and `x-*` extensions or generated
   model names as codegen hints, not additional business behavior.
3. Produce a contract-aware request construction using placeholders such as
   `<YCLOUD_API_KEY>`, `<PHONE_NUMBER>`, and synthetic media metadata. Raw HTTP
   examples are allowed. Use an SDK-specific example only when the project or
   user supplies a confirmed artifact and version; never derive a method name
   from `operationId`.
4. Explain the response only to the extent confirmed by the reference. Identify
   the media identifier/reference needed by a later message, without implying
   that an upload sent a WhatsApp message. Prefer the returned media ID for a
   normal media message, but preserve the documented exception that an
   interactive-message header must use a link instead of a Media ID.
5. Place the upload at the server-side integration boundary (for example, an
   application service or adapter) and keep the API key out of browsers, mobile
   apps, URLs, logs, source control, and generated snippets. Do not read `.env`,
   secret stores, logs, or customer media.
6. Treat upload timeouts as ambiguous and never replay automatically. Any
   project idempotency record, queue, retry budget, or Problem Details response
   is local policy, not a YCloud feature.
7. Give synthetic tests for multipart construction, exactly-one-file validation,
   supported type/size boundaries, 30-day lifecycle handling, path-parameter
   handling, response/reference mapping, the interactive-header link exception,
   and the upload-to-message handoff. Tests must not call YCloud or upload a real
   file.

## Outcome requirements

Adapt the result to planning, implementation, or evaluation. Preserve these
contract and evidence outcomes:

1. **Matched contract** — reference source hash, path, method, operationId,
   request content type/schema, response schema, and confirmed constraints.
2. **Request construction** — placeholder raw HTTP or project-local snippet;
   state any project facts still needed.
3. **Response and handoff** — map only confirmed response fields to a media
   reference, then hand off message composition/sending to
   `ycloud-whatsapp-messages`.
4. **Integration placement** — server-side module, configuration boundary, and
   redacted observability guidance.
5. **Tests** — synthetic unit/contract tests and negative cases.
6. **CANNOT** — list unknown contract facts, missing project facts, unsupported
   media operations, SDK uncertainties, and every action intentionally not run.
7. **Handoff** — return to Architect with `whatsapp_media-upload` status,
   changed or proposed artifacts, tests/results, unknowns, and the confirmed
   media-reference contract for Messages; otherwise state that no handoff is
   needed.

## Safety stop

Never call the YCloud API, open or transmit a real user file, persist credentials,
or claim that media was sent. Local code changes are allowed only when explicitly
requested and remain synthetic/no-network. A request to perform a real upload
stops before the external action even when local implementation was authorized.

Referenced files: 4

View saved version →

---
name: ycloud-whatsapp-messages
description: Design, implement locally, or evaluate contract-aware WhatsApp message submission and retrieval for direct, queued, or existing-template sends, including conditional request semantics and accepted-versus-final status handling. Use for message send/retrieve intent; exclude template lifecycle, media upload, webhook endpoint management, authentication-only, readiness, and repository maintenance.
---

# YCloud WhatsApp Messages

Design or implement project-local support for the three message operations in the generated reference. Never call YCloud, send a real message, read credentials or customer data, or claim that a submission was delivered.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor Architect handoffs for `scope`, `deliverable`, `mutation`, capability IDs,
project seams, and expected evidence. Without one, default to focused scope and
read-only guidance unless the user explicitly requests local implementation.
Local-write authorization permits request builders, adapters, handlers,
test-console bindings, mocks, and no-network tests inside the scoped project. It
never authorizes a real send or retrieve call. A `test-console` must expose the
selected conditional message shapes and must reuse the project's existing UI or
interface stack; do not create a dashboard or choose a framework on your own.

## Scope and operation routing

Load `references/openapi.md` and `references/runtime.md` only after this Skill is selected. If the request includes retry, idempotency, outbox/queue, circuit breaking, or error translation, also read `references/shared/integration-boundaries.md`. The allowlist is exact:

| Intent | Method and path | operationId |
| --- | --- | --- |
| Direct submission | `POST /whatsapp/messages/sendDirectly` | `whatsapp_message-send-directly` |
| Queued submission | `POST /whatsapp/messages` | `whatsapp_message-send` |
| Retrieve by message ID | `GET /whatsapp/messages/{id}` | `whatsapp_message-retrieve` |

Sending an already-created template message belongs here. Creating, editing, listing, retrieving, deleting, or analysing a template belongs to `ycloud-whatsapp-templates`. Uploading media belongs to `ycloud-whatsapp-media`; receive its confirmed media reference before constructing a media message. API-key-only questions belong to `ycloud-api-authentication`; broad/multi-domain planning belongs to `ycloud-integration-architect`. Readiness, repository-maintenance, and issue-tracker workflows are out of scope.

## Contract-first workflow

For an explicitly requested local sandbox/mock path, also read
`references/shared/sandbox-contract.md`. Use its fixed synthetic key, sender,
recipient, base URL, scenarios and lifecycle controls only in tests. Never expose
`X-YCloud-Mock-*` or `/_mock/*` as provider contract, and never let a mock
`accepted` result satisfy final delivery evidence.

1. Confirm the selected operation’s exact path, method, parameters, request schema, response schema, and descriptions in the generated reference. If the source/reference hash or operation list drifts, stop and report it.
2. For direct versus queued requests, preserve endpoint-specific fields and semantics from the reference. Do not substitute one endpoint for the other or imply that a queue is a delivery guarantee.
   For queued template messages, preserve the reference’s confirmed rule that the referenced template must be `APPROVED`; an `ARCHIVED` template cannot be sent. Do not generalize this into an unconfirmed template lifecycle policy.
3. Treat `WhatsappMessageSendRequest` as a flat codegen shape: it has `type` plus optional payload fields, not an automatic `oneOf`/discriminator. Apply the description’s type-dependent rules and include only fields valid for the selected `type`; do not treat every optional field as simultaneously valid.
   The request requires `from` and `type`; payload members such as `audio`, `contacts`, `document`, `image`, `interactive`, `location`, `reaction`, `sticker`, `template`, `text`, or `video` are required only for their matching type.
   For an existing-template send, never reuse the template create/edit definition: static component `text` and the definition's `buttons` array belong to the Templates workflow. Generate parameter-override components using the canonical lowercase spellings: `header`, `body`, `button`, `limited_time_offer`, `carousel`, or `order_status`. Preserve case-insensitive compatibility for component types, button subtypes, and parameter types; capitalization alone is not a reason to reject the send model. Each button is a separate `button` component with `sub_type`, zero-based `index`, and `parameters`; do not resend static header, body, or footer text. For carousel template sends, use one `carousel` component with `cards`, each containing a zero-based `card_index` and `header`, `body`, or `button` parameter overrides. A send may supply overrides for one card; do not apply the create/edit definition's two-card minimum to this array. Read the generated reference before constructing any component; the exact required parameters depend on the approved template.
4. The source requires exactly one of `to` or `recipient`; when both are provided, `to` takes precedence and `recipient` is ignored. Preserve this rule as an implementation invariant: when `to` exists, resolve and validate `to` before touching `recipient`; do not read, normalize, parse, or validate the ignored `recipient`, and do not fall back to it when `to` is invalid. A valid `to` plus an empty, malformed, or wrong-typed `recipient` must produce the same request as `to` alone, with `recipient` omitted. Keep endpoint-specific constraints too: `filterBlocked` and `filterUnsubscribed` apply only to queued `POST /whatsapp/messages`, while `ttlSeconds` and `useDirectSend` follow the direct-send descriptions. If the reference does not settle an edge case, put it in `CANNOT` rather than inventing precedence.
5. Explain the state boundary: request submission/enqueue and an HTTP `accepted` response are not the same as final asynchronous state or `delivered`. Use `runtime.md` for synchronous versus asynchronous errors, documented message quotas, `Retry-After`, and duplicate/out-of-order status events. Do not invent delivery guarantees or unlisted callback behavior.
6. On `429`, schedule later traffic after the documented `Retry-After` delay; the Errors page also recommends exponential backoff for `TOO_MANY_REQUESTS`. Treat any additional jitter policy as a project decision, not a YCloud contract. Retry only when the failure is transient and replay is safe; treat timeouts and lost responses as ambiguous outcomes. Never blindly replay a send POST: the public docs do not define a general idempotency key or exactly-once send guarantee. A project-owned `Idempotency-Key`, command/outbox identity, retry budget, or DLQ must be labeled as local architecture and must not be forwarded or attributed to YCloud without evidence. Do not infer Java/TypeScript/Python/Go/PHP SDK method names from operation IDs; use raw HTTP or confirmed project SDK artifacts only.
7. Apply the documented WhatsApp service-window rule: free-form messages require the 24-hour customer-service window; outside it, use an approved template. Track final state through retrieve-by-ID or `whatsapp.message.updated`, keep `externalId` as an application correlation value, and retain the YCloud message ID separately. Preserve unknown response properties/status values rather than failing exhaustive decoding.

## Illustrative raw HTTP

Examples are synthetic and explanatory only. Use the exact schema fields from the generated reference for the selected message `type`; the ellipsis is a reminder not to send an unreviewed payload.

```http
POST <YCLOUD_API_BASE_URL>/whatsapp/messages/sendDirectly
X-API-Key: <YCLOUD_API_KEY>
Content-Type: application/json

{"type":"<CONFIRMED_TYPE>","to":"<SYNTHETIC_RECIPIENT>","<TYPE_SPECIFIC_FIELD>":"<SYNTHETIC_VALUE>"}
```

```http
GET <YCLOUD_API_BASE_URL>/whatsapp/messages/<SYNTHETIC_MESSAGE_ID>
X-API-Key: <YCLOUD_API_KEY>
```

Do not execute these snippets. Do not put real keys, phone numbers, message bodies, or customer identifiers in examples or logs.

## Outcome requirements

Adapt the result to planning, implementation, or evaluation. Preserve the
following contract and evidence outcomes:

### Operation and Contract

Name exactly one or more allowlisted operation IDs, method/path, request/response schemas, and relevant description-only constraints. State whether the request is direct, queued, or retrieve.

### Request Construction

Show a placeholder-based raw HTTP or project-local typed example. Apply `type`-dependent flattened-field rules, `to`/`recipient` semantics, endpoint-specific fields, and the Authentication handoff without guessing.

### Response Semantics

Separate synchronous/direct submission, queued submission, HTTP accepted, and final asynchronous state. Direct failures may carry `error.whatsappApiError`; queued failures can arrive through `whatsapp.message.updated`. Status events may be duplicated or out of order; never equate accepted with delivered or assume a monotonic state sequence.
The generated reference confirms `200` accepted responses for both send operations and `200`/`404` responses for retrieve; preserve the `WhatsappMessage`/`ErrorResponse` schemas without inventing additional codes.

### Integration and Tests

Place the request in the confirmed server module and cover schema validation, each selected type branch, direct/queued routing, 24-hour-window/template routing, provider-envelope/request-ID mapping, `429` scheduling without blind replay, timeout ambiguity, transient-and-replay-safe classification, project idempotency versus YCloud contract, duplicate/out-of-order/unknown status events, `externalId` versus YCloud-ID correlation, synthetic retrieve IDs, accepted-versus-final state handling, and no-network tests.

For every selected send operation, `to`/`recipient` tests are mandatory. Cover: neither field rejects; valid `recipient` alone succeeds; valid `to` alone succeeds; both valid select `to` and omit `recipient`; valid `to` plus empty, malformed, or wrong-typed `recipient` still succeeds exactly as `to` alone; invalid `to` plus valid `recipient` rejects instead of falling back. Do not report implementation or tests complete without these executable assertions.

### CANNOT

List unsupported operations and unknowns: real API/message calls, actual customer data or credentials, template lifecycle, media upload, blind POST replay, delivery claims, guessed SDK methods/artifacts, general idempotency/exactly-once behavior, unlisted operation errors, or final-state guarantees. Do not put documented quotas, `429`, `Retry-After`, the standard error envelope, or asynchronous error routing into `CANNOT`. External mutations remain gated independently from local writes and are never executed by this workflow.

### Handoff

Send template create/edit/list/retrieve/delete/analytics to Templates. Send media upload to Media and consume only its confirmed media reference before a message request. Send authentication storage to Authentication. Return to Architect with capability-row status, changed or proposed artifacts, tests/results, accepted-versus-final evidence, unknowns, and outgoing Media/Template/Webhook handoffs. If the user asks for delivery/event consumption, require a reliable source or mark `CANNOT`.

## Safety and source priority

Use the exact OpenAPI path/schema first, generated reference second, and this workflow third. Keep `operationId` and codegen extensions as identifiers/hints, not SDK methods or business rules. Use placeholders (`<YCLOUD_API_KEY>`, `<YCLOUD_API_BASE_URL>`) and synthetic identifiers only. Shell and local project writes are permitted only when needed for an explicitly requested local implementation; network API, credential, customer-data, and external side effects remain prohibited.

Referenced files: 5

View saved version →

---
name: ycloud-whatsapp-phone-numbers
description: Design, implement locally, or evaluate YCloud WhatsApp business phone-number inventory, registration, profile, display-name, Business Username, contact-book, Calling/capture settings, and commerce settings operations. Use for phone-number management; exclude WABA management, message sending, template lifecycle, WhatsApp Calling sessions, and real API mutations.
---

# YCloud WhatsApp Phone Numbers

Design or implement contract-aware support for the fifteen phone-number
operations in the generated reference. Never call YCloud or Meta, read
credentials or customer data, or mutate a real phone-number resource.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor Architect handoffs for `scope`, `deliverable`, `mutation`, capability IDs,
project seams, and expected evidence. Without one, default to focused,
read-only guidance unless the user explicitly requests local implementation.
Local-write authorization permits request models/builders, adapters, handlers,
service bindings, mocks, synthetic fixtures, and no-network tests in the
scoped project. Register, PATCH, settings save, and both DELETE operations are
mock-only. Reuse the project's existing interface stack and preserve concurrent
work.

Load [the generated OpenAPI reference](references/openapi.md) and
[the reviewed runtime reference](references/runtime.md) only after this skill is
selected. If retry, idempotency, queueing, or error translation is requested,
also read `references/shared/integration-boundaries.md`. Exact paths, schemas,
responses, and descriptions come from `openapi.md`; cross-cutting pagination,
error, request-ID, rate-limit, and compatibility behavior comes from
`runtime.md`. If either generated reference is missing, stale, or inconsistent
with its recorded source hash and operation count, report drift and stop rather
than reconstructing the contract from memory.
For phone-number list work, also read
[`references/shared/pagination-contract.md`](references/shared/pagination-contract.md).

## Exact operation scope

| Intent | Method and path | operationId |
| --- | --- | --- |
| List phone numbers | `GET /whatsapp/phoneNumbers` | `whatsapp_phone_number-list` |
| Retrieve phone number | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}` | `whatsapp_phone_number-retrieve` |
| Retrieve Business Username | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername` | `whatsapp_phone_number-retrieve-business-username` |
| Update Business Username | `PATCH /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername` | `whatsapp_phone_number-update-business-username` |
| Delete active Business Username | `DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername` | `whatsapp_phone_number-delete-business-username` |
| Retrieve username suggestions | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername/suggestions` | `whatsapp_phone_number-retrieve-business-username-suggestions` |
| Delete Meta contact-book entry | `DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}` | `whatsapp_phone_number-delete-contact-book-entry` |
| Update display name | `PATCH /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/displayName` | `whatsapp_phone_number-update-displayName` |
| Retrieve profile | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/profile` | `whatsapp_phone_number-retrieve-profile` |
| Update profile | `PATCH /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/profile` | `whatsapp_phone_number-update-profile` |
| Register phone number | `POST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/register` | `whatsapp_phone_number-register` |
| Retrieve Calling/capture settings | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings` | `whatsapp_phone_number-retrieve-settings` |
| Save Calling/capture settings | `POST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings` | `whatsapp_phone_number-save-settings` |
| Retrieve commerce settings | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/whatsappCommerceSettings` | `whatsapp_phone_number-retrieve-commerce-settings` |
| Update commerce settings | `PATCH /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/whatsappCommerceSettings` | `whatsapp_phone_number-update-commerce-settings` |

WABA discovery belongs to `ycloud-whatsapp-business-accounts`. Message
submission/retrieval belongs to `ycloud-whatsapp-messages`; template lifecycle
and analytics belongs to `ycloud-whatsapp-templates`; authentication-only work
belongs to `ycloud-api-authentication`; broad multi-domain planning belongs to
`ycloud-integration-architect`. Readiness, repository maintenance, issue
tracking, WhatsApp Calling sessions, and contact CRUD are out of scope.

## Contract-first workflow

1. Match only allowlisted operations and report exact methods, paths,
   operationIds, parameters, request/response schemas, and documented responses.
   Treat `operationId` and `x-*` fields as identifiers or codegen hints, not SDK
   methods or business rules. Use an SDK-specific method only when its artifact,
   version, and documentation are confirmed in the project.
2. Preserve `wabaId`, YCloud phone-number IDs, and BSUIDs as opaque,
   case-sensitive strings; do not parse prefixes or coerce numeric-looking IDs.
   Preserve `phoneNumber` as an E.164 string, never a number. Encode path
   segments correctly; the contact-book contract explicitly requires the
   leading `+` to be encoded as `%2B` when constructing that path manually.
   Never infer that a phone belongs to a WABA: use only confirmed input or a
   WABA/phone lookup result.
3. For list, use 1-based `page`, `limit` from 1 through 100, and documented
   defaults. Request `includeTotal=true` only when a count is needed. Preserve
   `filter.wabaId` exactly; the contract says it is required when the account has
   more than 100 WABAs. Parse the response as the merged Page envelope with
   required `offset`, `limit`, `length`, phone-number `items`, and optional
   `total`; response `offset` is not a query parameter. Preserve unknown
   response fields and enum/status values.
4. Keep contract behavior distinct across operation families:

   - **Business Username:** PATCH sends a required plain username without `@`.
     Apply all generated length, character, letter, dot, prefix, and suffix
     constraints after the documented trim/lowercase normalization. A successful
     request may remain `reserved`; `pending_review` is a legacy response value,
     and an existing active username may coexist with the requested one. DELETE
     removes only the active username and does not cancel a reserved request.
     Suggestions flatten to `data: string[]`; no suggestions is an empty array.
   - **Meta contact book:** require a standard BSUID matching the generated
     shape; parent `.ENT.` BSUIDs are unsupported. The WABA, phone binding, and
     Meta business portfolio must match. This endpoint requires an account API
     key, not a Developer App key, but credential selection/storage remains an
     Authentication handoff. HTTP 200 always has `success=true`;
     `deleted=false` is a successful no-match, not a 404. The operation does not
     delete YCloud Contact/message/BSUID records, bypass Meta's 30-day cache, or
     prevent later recreation after another WhatsApp interaction.
   - **Profile and display name:** preserve requiredness and every generated
     field constraint exactly. Do not make `newName` required merely because the
     display-name endpoint's purpose suggests it if the schema does not. For
     profile updates, enforce field length, website count/item length, URL
     scheme, vertical values, and description-only `about` constraints without
     inventing replacement semantics for omitted fields.
   - **Registration:** preserve the no-body POST contract. Do not interpret a
     200 registration response as message readiness, template approval, or
     authorization to send.
   - **Calling/capture settings:** GET accepts optional `type=capture|calling`;
     omitted `type` follows the documented Calling response behavior. Save
     `calling`, `capture`, or both. When both are sent, each branch is attempted
     independently after shared authorization/phone validation; an error can
     mean the other branch was already saved. Enabling either capture switch
     requires the documented announcement language and purpose. Model combined
     failures as partial/ambiguous outcomes, not atomic rollback.
   - **Commerce settings:** preserve the two optional booleans and exact PATCH
     response shape. Do not add an undocumented catalog/cart dependency or infer
     omitted-field behavior.
5. Keep contract facts separate from local policy. Validation, confirmation UX,
   audit records, idempotency ledgers, retry budgets, and rollback controls are
   application-owned unless the references say otherwise. Both DELETEs are
   high-risk and all mutations are mock-only. Treat mutating timeouts and the
   combined-settings failure as ambiguous; never replay a mutation
   automatically. Honor documented `Retry-After` before later traffic without
   treating it as proof that replay is safe.
6. Use placeholders such as `<YCLOUD_API_KEY>`, `<WABA_ID>`,
   `<E164_PHONE_NUMBER>`, and `<STANDARD_BSUID>` plus synthetic payloads. Keep
   authentication server-side and hand credential storage to
   `ycloud-api-authentication`; do not inspect `.env`, secret stores, logs, live
   resources, profiles, usernames, or contact data.

## Validation and evidence

For local implementation, add no-network tests for all selected operation
routes, exact path/query/body construction, opaque IDs, E.164 string handling
and path encoding, pagination boundaries/defaults/optional totals, the
more-than-100-WABA filter condition, standard errors/request IDs, and unknown
response properties or statuses. Add family-specific tests for username
normalization and validation, active-versus-reserved state, empty suggestions,
contact-book account-key gating and `deleted` semantics, profile/display-name
constraints, no-body registration, settings `type`, capture prerequisites,
combined-settings partial failure, commerce booleans, delete confirmation stops,
ambiguous timeouts, and no mutation replay. Mocks must prove no network client is
invoked.

Return these sections, adapted to the requested deliverable:

1. **Matched contract** — source hash, selected operations, exact request and
   response shapes, and description-only constraints.
2. **Construction or implementation** — placeholder HTTP/project-local design,
   changed artifacts, and project facts still needed.
3. **Contract versus policy** — identify YCloud guarantees separately from local
   validation, approvals, persistence, retries, and rollback choices.
4. **Tests and evidence** — synthetic cases and actual no-network results.
5. **CANNOT** — real YCloud/Meta calls, credentials/customer data, guessed SDK
   methods, unsupported operations, unconfirmed retry/idempotency/atomicity, and
   missing facts. Do not put confirmed pagination, error-envelope, request-ID,
   status, or partial-success behavior in `CANNOT`.
6. **Handoff** — receive a confirmed opaque WABA ID from
   `ycloud-whatsapp-business-accounts`; once the WABA/phone pair is confirmed,
   hand message submission/retrieval to `ycloud-whatsapp-messages` and template
   lifecycle/analytics to `ycloud-whatsapp-templates`. Do not imply that phone
   registration or configuration authorizes either downstream mutation. Return
   to Architect with capability status, artifacts, tests, unknowns, and outgoing
   handoffs.

## Safety stop

YCloud Provider API calls are prohibited during Skill execution, including
nominally read-only GETs. All mutations are mock-only. Stop before any request
that would use a real API key, WABA/phone/BSUID/customer identifier, or live
YCloud/Meta resource.

Referenced files: 5

View saved version →

---
name: ycloud-whatsapp-templates
description: Design, implement locally, or evaluate YCloud WhatsApp template create, list, retrieve, edit, delete, and analytics operations. Use for template lifecycle integration; do not use for sending template messages, media uploads, readiness, broad integration planning, or real template/API mutations.
---

# YCloud WhatsApp Templates

Design or implement safe, contract-aware WhatsApp template lifecycle and
analytics work. This skill never mutates a real template.

## Execution boundary

These restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.

Honor Architect handoffs for `scope`, `deliverable`, `mutation`, capability IDs,
project seams, and expected evidence. Without one, default to focused scope and
read-only guidance unless the user explicitly requests local implementation.
Local-write authorization permits request models/builders, adapters, handlers,
component editors, test-console bindings, mocks, and no-network tests in the
scoped project. It does not authorize create, edit, delete, analytics, or any
other real API call. Reuse the project's existing UI/interface stack and do not
generate a dashboard or bind a framework without user/project support.

## Trigger boundary

Use this skill for template creation, listing, retrieval, editing, deletion, or
analytics. A request to send a message that happens to use a template belongs to
`ycloud-whatsapp-messages`, even when the template already exists. A request to
upload media belongs to `ycloud-whatsapp-media`. Broad integration design belongs
to `ycloud-integration-architect`; readiness, repository-maintenance, and issue-tracker prompts do
not trigger this skill.

Read only `references/openapi.md` and `references/runtime.md` after selection.
For create requests, component editors, or template smoke tests, also read
`references/create-examples.json`. If retry, idempotency, queueing, or error
translation is requested, also read `references/shared/integration-boundaries.md`. The generated OpenAPI reference is
the contract index for the seven allowlisted template operations: create, list,
retrieve, edit, delete-by-name, delete-by-name-and-language, and analytics. Use
the exact source-derived path, method, operationId, parameter, schema, response,
and descriptions from the reference; do not guess names or paths from prose.
For template-list work, also read `references/shared/pagination-contract.md`.
Interpret `allOf` as schema composition and `x-*` extensions or generated model
names as codegen hints, not additional lifecycle behavior.
If source hash, operation coverage, or reference content drifts, report the drift
and stop.

## Workflow

1. Establish the user’s intended lifecycle operation and the target server-side
   project context. Ask for missing language, framework, environment, or
   template identity rather than inferring them.
2. Match exactly one of the seven operations in the generated reference. Keep
   lifecycle operations separate from message sending. Preserve source-defined
   path parameters, request/response schemas, enum values, and description-only
   constraints. Use the runtime reference for the shared Management API quota,
   standard error envelope, request ID, pagination behavior, edit replacement
   semantics, extensible status handling, and documented template error codes.
   Do not fill gaps with imagined safe replay, idempotency, approval states,
   delivery semantics, or analytics meanings.
3. Generate raw HTTP or contract-aware typed request examples, or implement
   project-local request construction when authorized, with placeholders
   such as `<YCLOUD_API_KEY>`, `<TEMPLATE_NAME>`, `<LANGUAGE>`, and synthetic
   values. Use an SDK-specific method only when a confirmed SDK artifact/version
   and documentation are present in the user’s project; `operationId` is not an
   SDK method name.
   For the default create smoke test, use the documented
   `utility-order-confirmation` fixture unchanged except for replacing
   `<WABA_ID>` and, when collision avoidance is required, the template name.
   Use the documented `authentication-copy-code` fixture for authentication
   shape tests. `AUTHENTICATION`, `MARKETING`, and `UTILITY` are top-level
   category values, never component types. Do not manufacture a kitchen-sink
   request by adding one instance of every component enum; component
   combinations have cross-field constraints and must come from a selected
   documented example or a user-supplied valid design.
   Keep `wabaId` as part of template identity across list, retrieve, and edit.
   A UI or local route may encode a composite key, but its provider adapter must
   preserve the exact `/whatsapp/templates/{wabaId}/{name}/{language}` path for
   retrieve and edit; `name|language` alone is not a provider identity.
   Keep template definition components separate from message-send parameters:
   Generate template definitions using the canonical uppercase `CAROUSEL`,
   `HEADER`, `BODY`, and `BUTTONS` spellings (including nested `buttons`).
   Preserve case-insensitive parsing of definition component types, formats,
   and button types; capitalization alone does not distinguish a definition
   from a send payload. Route message parameter composition to
   `ycloud-whatsapp-messages`, which generates the lowercase send component model.
   For carousel create/edit fixtures, include 2..10 cards, a media `HEADER`
   and a `BUTTONS` component containing 1..2 buttons per card. Supply media
   examples as a non-empty `example.header_url` string array. The service uses
   its first URL, which must be HTTP(S) with `.jpg`, `.jpeg`, or `.png` for
   `IMAGE` and `.mp4` for `VIDEO`. If a card
   includes `BODY`, its text must be non-blank and at most 160 characters.
   The two-card minimum is a definition constraint, not a minimum count for
   the parameter overrides included in a later send request.
   Apply the same request validator before both sandbox storage and live
   transport so live mode cannot bypass component/category/button validation.
4. Keep API keys server-side and out of browser/mobile code, URLs, logs, source
   control, and snippets. Do not read `.env`, secret stores, logs, customer
   templates, or live analytics.
5. For create/edit/delete, describe the planned change and its validation and
   rollback considerations. An edit is a full content replacement: include all
   components that must survive, and allow it only for `APPROVED`, `REJECTED`,
   or `PAUSED`; never edit `ARCHIVED`. For list, use 1-based `page`, `limit`
   1..100, and `includeTotal` only when a count is required; archived matches
   remain visible. Parse the response as the merged Page envelope with required
   `offset`, `limit`, `length`, template `items`, and optional `total`; `offset`
   is response metadata, not a query parameter. Preserve unfamiliar status values and stop state-dependent
   mutation rather than mapping them to a known state.
6. Build synthetic tests for request/schema validation, full-replacement edits,
   editable/archived/unknown status gates, pagination boundaries and optional
   totals, path/query parameters, response mapping, and the selected lifecycle
   branch. Create tests must assert that category values never appear in
   `components[*].type` and that the selected documented example survives
   request construction without extra components. Retrieve/edit tests must
   assert that the captured provider path includes the WABA ID. Also test that
   live and sandbox handlers reject the same invalid component payload before
   transport. Do not call YCloud or alter a template.
7. Treat create/edit/delete timeouts as ambiguous outcomes and never replay
   automatically. Any project idempotency ledger, outbox, retry budget, or RFC
   9457 response is local architecture, not a YCloud contract.

## High-risk delete handling

Treat both delete operations as high-risk. Stop before execution, state the
target and potential impact, request explicit confirmation in a future approved
workflow, and outline a verification/rollback plan only where the source or
project facts support it. The MVP performs no delete, create, edit, or other
external API action. Never imply that deleting a template withdraws or changes
already-submitted messages.

## Outcome requirements

Adapt the result to planning, implementation, or evaluation. Preserve these
contract and evidence outcomes:

1. **Matched contract** — source hash, selected operation, exact path/method,
   parameters, request/response schemas, and confirmed constraints.
2. **Lifecycle plan** — placeholder raw HTTP or project-local construction and
   the intended create/list/retrieve/edit/delete/analytics behavior.
3. **Safety and integration placement** — server-side boundary, credential
   handling, validation, and (for delete) high-risk confirmation stop.
4. **Tests** — synthetic contract, mapping, and negative tests with no live call.
5. **CANNOT** — unknown metrics or runtime behavior, unsupported operations,
   unconfirmed SDK methods, missing project facts, and actions not performed.
6. **Handoff** — route template message composition/sending to
   `ycloud-whatsapp-messages`; return to Architect with each selected operation's
   row status, changed or proposed artifacts, tests/results, lifecycle/status
   preconditions, unknowns, and outgoing handoffs.

## Non-goals

Do not consume webhook payloads, verify signatures, upload media, send messages,
read credentials, make unrequested local changes, or invoke a remote API. A
template lifecycle result is not a sent or delivered message; keep that
distinction in every example and handoff.

Referenced files: 6