← Files YCloud Developer KitARCHIVED FILE
skills/ycloud-contacts/references/openapi.md
38.4 KB · Oct 2, 2026 · 00:32 UTC
<!-- Generated by scripts/build_openapi_skill_references.py; do not edit. -->
# OpenAPI contract: Contacts
## Provenance
- Source: `ycloud-api-v2.yaml` (pinned release snapshot).
- Source SHA-256: `8592bd4cc37186655a480dd86ce6bac6731543727327a2871d9103a0b8ed9e81`
- OpenAPI version: `3.0.0`
- API info.version: `v2`
- This derived reference does not replace the upstream API Owner's canonical source.
- Generated deterministically from normalized JSON; do not edit this file by hand.
## Scope and handoff
- These ten operations cover Contact CRUD, attribute listing, and notes lifecycle. Keep contact and note IDs separate and do not replay ambiguous mutations automatically.
- Operation coverage: `10`
## Operations
### `GET /contact/contacts/attributes` — `contact-attributes-list`
- Summary: List contact attributes
- Description:
> Returns a list of all available contact attributes and their configurations.
- Parameters: none
- Request body: none
- Responses:
- `200`: Successfully retrieved contact attributes.
- `application/json`: `array`
### `POST /contact/contacts` — `contact-create`
- Summary: Create a contact
- Description:
> Creates a contact.
- Parameters: none
- Request body: required
- `application/json`: `#/components/schemas/ContactCreateRequest`
- `$ref`: `#/components/schemas/ContactCreateRequest`
- Responses:
- `200`: Successfully created a contact.
- `application/json`: `#/components/schemas/Contact`
- `$ref`: `#/components/schemas/Contact`
- `400`: The notes array or note content is invalid.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
### `DELETE /contact/contacts/{id}` — `contact-delete`
- Summary: Delete a contact
- Description:
> Deletes a contact.
- Parameters:
- `id` (path, required): `string`
> Identifier of the contact. Supports a contact ID, a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format starting with `+` (for example, `+16315551111`), or a Meta username without the leading `@`.
> A Meta username must contain 3 to 35 letters, digits, periods, or underscores. If a numeric value can be interpreted as both a Meta username and a contact ID, it is resolved as a Meta username first. If no contact has that Meta username, the value is resolved as a contact ID.
- Constraints: maxLength=255; example="alice_01"
- Request body: none
- Responses:
- `200`: Successfully deleted the contact.
- `application/json`: `#/components/schemas/Contact`
- `$ref`: `#/components/schemas/Contact`
- `404`: The requested resource does not exist.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
### `GET /contact/contacts` — `contact-list`
- Summary: List contacts
- Description:
> Returns a paginated list of contacts.
>
> Omit `pageAfter` to use the existing page-based pagination. To use forward cursor pagination, set `pageAfter=0` for the first page, then pass the exact `cursor.after` value returned by the previous response. Cursor results are ordered by contact ID in ascending order.
>
> Do not combine `pageAfter` with `page`, `pageBefore`, `offset`, or `sort`. Keep all filters unchanged while following a cursor. Concurrent contact inserts, deletions, or filter-field updates use weak consistency; restart a full traversal with `pageAfter=0` when a fresh snapshot is required.
- Parameters:
- `page` (query, optional): `integer (int32)`
> Page number of the results to be returned, 1-based.
- Constraints: minimum=1; maximum=100; default=1
- `limit` (query, optional): `integer (int32)`
> A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
- Constraints: minimum=1; maximum=100; default=10
- `includeTotal` (query, optional): `boolean`
> Return results inside an object that contains the total result count or not.
- Constraints: default=false
- `pageAfter` (query, optional): `string`
> Contact ID cursor for forward pagination. Use `0` to start a new cursor traversal. For each subsequent page, pass the exact `cursor.after` value from the previous response.
> The value must be a non-negative decimal integer in the signed 64-bit range (`0` through `9223372036854775807`). It cannot be combined with `page`, `pageBefore`, `offset`, or `sort`.
- Constraints: pattern="^[0-9]+$"; example="0"
- `filter.tags` (query, optional): `string`
> Comma-separated list of tag names. If any tag does not exist, the request fails with a parameter error.
- Constraints: example="tag1,tag2"
- `filter.countryCode` (query, optional): `string`
> Two-letter country abbreviation. See [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
- Constraints: example="US"
- `filter.phoneNumber` (query, optional): `string`
> Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
- Constraints: example="+16315551111"
- `filter.email` (query, optional): `string`
> The contact's email address.
- Constraints: example="support@example.com"
- Request body: none
- Responses:
- `200`: Successfully retrieved a paginated list of objects.
- `application/json`: `#/components/schemas/ContactPage`
- `$ref`: `#/components/schemas/ContactPage`
- `400`: One or more query parameters are invalid, including an invalid cursor, incompatible pagination parameters, an out-of-range limit, or an unknown tag.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
### `POST /contact/contacts/{contactIdentifier}/notes` — `contact-note-create`
- Summary: Create a contact note
- Description:
> Creates one note for the contact and returns the created note.
> Leading and trailing whitespace is removed before storage. This operation does not use a client idempotency key; repeating the request creates another note with a different ID.
- Parameters:
- `contactIdentifier` (path, required): `string`
> Identifier of the contact that owns the note. Supports a contact ID, a username without the leading `@`, or a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format starting with `+`.
> Usernames contain 3 to 35 letters, digits, periods, or underscores. A numeric value is resolved as a username first and then as a contact ID when no matching username exists.
- Constraints: maxLength=255; example="alice_01"
- Request body: required
- `application/json`: `#/components/schemas/ContactNoteWriteRequest`
- `$ref`: `#/components/schemas/ContactNoteWriteRequest`
- Responses:
- `200`: Successfully created the contact note.
- `application/json`: `#/components/schemas/ContactNote`
- `$ref`: `#/components/schemas/ContactNote`
- `400`: The contact identifier or note content is invalid, or the contact already has 50 notes.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
- `404`: The contact does not exist.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
### `DELETE /contact/notes/{noteId}` — `contact-note-delete`
- Summary: Delete a contact note
- Description:
> Deletes one note in the current tenant by note ID and returns its snapshot before deletion.
> Deleting the same note again returns `404`; the operation does not use a client idempotency key.
- Parameters:
- `noteId` (path, required): `string`
> The 24-character ObjectId of the contact note.
- Constraints: minLength=24; maxLength=24; pattern="^[0-9a-fA-F]{24}$"; example="6a3de646e18f344f743aaa4d"
- Request body: none
- Responses:
- `200`: Successfully deleted the contact note.
- `application/json`: `#/components/schemas/ContactNote`
- `$ref`: `#/components/schemas/ContactNote`
- `400`: The contact note ID is invalid.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
- `404`: The contact note does not exist in the current tenant.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
### `PATCH /contact/notes/{noteId}` — `contact-note-update`
- Summary: Update a contact note
- Description:
> Updates one note in the current tenant by note ID and returns the updated note.
> Repeating the same request leaves the stored content unchanged, but an accepted update may still produce another `contact.note.updated` event.
- Parameters:
- `noteId` (path, required): `string`
> The 24-character ObjectId of the contact note.
- Constraints: minLength=24; maxLength=24; pattern="^[0-9a-fA-F]{24}$"; example="6a3de646e18f344f743aaa4d"
- Request body: required
- `application/json`: `#/components/schemas/ContactNoteWriteRequest`
- `$ref`: `#/components/schemas/ContactNoteWriteRequest`
- Responses:
- `200`: Successfully updated the contact note.
- `application/json`: `#/components/schemas/ContactNote`
- `$ref`: `#/components/schemas/ContactNote`
- `400`: The contact note ID or content is invalid.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
- `404`: The contact note does not exist in the current tenant.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
### `GET /contact/contacts/{contactIdentifier}/notes` — `contact-notes-list`
- Summary: List contact notes
- Description:
> Returns all notes for a contact, ordered by creation time descending.
> The `{contactIdentifier}` path parameter supports a contact ID, a phone number in E.164 format starting with `+`, or a Meta username without the leading `@`. Ambiguous numeric values are resolved as Meta usernames first and fall back to contact IDs only when no matching Meta username exists.
> Contact retrieve, list, and search responses do not include notes; use this endpoint to read contact notes.
- Parameters:
- `contactIdentifier` (path, required): `string`
> Identifier of the contact that owns the note. Supports a contact ID, a username without the leading `@`, or a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format starting with `+`.
> Usernames contain 3 to 35 letters, digits, periods, or underscores. A numeric value is resolved as a username first and then as a contact ID when no matching username exists.
- Constraints: maxLength=255; example="alice_01"
- Request body: none
- Responses:
- `200`: Successfully retrieved contact notes.
- `application/json`: `array`
- Constraints: maxItems=50
- `400`: The contact identifier is invalid.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
- `404`: The requested resource does not exist.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
### `GET /contact/contacts/{id}` — `contact-retrieve`
- Summary: Retrieve a contact
- Description:
> Retrieves a contact.
- Parameters:
- `id` (path, required): `string`
> Identifier of the contact. Supports a contact ID, a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format starting with `+` (for example, `+16315551111`), or a Meta username without the leading `@`.
> A Meta username must contain 3 to 35 letters, digits, periods, or underscores. If a numeric value can be interpreted as both a Meta username and a contact ID, it is resolved as a Meta username first. If no contact has that Meta username, the value is resolved as a contact ID.
- Constraints: maxLength=255; example="alice_01"
- Request body: none
- Responses:
- `200`: Successfully retrieved the contact.
- `application/json`: `#/components/schemas/Contact`
- `$ref`: `#/components/schemas/Contact`
- `404`: The requested resource does not exist.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
### `PATCH /contact/contacts/{id}` — `contact-update`
- Summary: Update a contact
- Description:
> Updates a contact. If every supplied persisted contact field already has
> the requested value, the contact is not updated and no
> `contact.attributes_changed` event is emitted. Note mutations in the
> same request are still applied.
- Parameters:
- `id` (path, required): `string`
> Identifier of the contact. Supports a contact ID, a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format starting with `+` (for example, `+16315551111`), or a Meta username without the leading `@`.
> A Meta username must contain 3 to 35 letters, digits, periods, or underscores. If a numeric value can be interpreted as both a Meta username and a contact ID, it is resolved as a Meta username first. If no contact has that Meta username, the value is resolved as a contact ID.
- Constraints: maxLength=255; example="alice_01"
- Request body: optional
- `application/json`: `#/components/schemas/ContactUpdateRequest`
- `$ref`: `#/components/schemas/ContactUpdateRequest`
- Responses:
- `200`: Successfully updated the contact.
- `application/json`: `#/components/schemas/Contact`
- `$ref`: `#/components/schemas/Contact`
- `400`: The notes array, note ID, or note content is invalid.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
- `404`: The contact or referenced contact note does not exist, or the note is not owned by the contact.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
## Referenced schema and parameter shapes
### `contactIdentifier-in_path_for_contact_note`
- Reference: `#/components/parameters/contactIdentifier-in_path_for_contact_note`
- Parameter name: `contactIdentifier`
- Location: `path`
- Required: `true`
- Description:
> Identifier of the contact that owns the note. Supports a contact ID, a username without the leading `@`, or a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format starting with `+`.
> Usernames contain 3 to 35 letters, digits, periods, or underscores. A numeric value is resolved as a username first and then as a contact ID when no matching username exists.
- Schema: `string`
- Constraints: maxLength=255; example="alice_01"
### `contactPageAfter`
- Reference: `#/components/parameters/contactPageAfter`
- Parameter name: `pageAfter`
- Location: `query`
- Required: `false`
- Description:
> Contact ID cursor for forward pagination. Use `0` to start a new cursor traversal. For each subsequent page, pass the exact `cursor.after` value from the previous response.
> The value must be a non-negative decimal integer in the signed 64-bit range (`0` through `9223372036854775807`). It cannot be combined with `page`, `pageBefore`, `offset`, or `sort`.
- Schema: `string`
- Constraints: pattern="^[0-9]+$"; example="0"
### `id-in_path_for_contact`
- Reference: `#/components/parameters/id-in_path_for_contact`
- Parameter name: `id`
- Location: `path`
- Required: `true`
- Description:
> Identifier of the contact. Supports a contact ID, a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format starting with `+` (for example, `+16315551111`), or a Meta username without the leading `@`.
> A Meta username must contain 3 to 35 letters, digits, periods, or underscores. If a numeric value can be interpreted as both a Meta username and a contact ID, it is resolved as a Meta username first. If no contact has that Meta username, the value is resolved as a contact ID.
- Schema: `string`
- Constraints: maxLength=255; example="alice_01"
### `includeTotal`
- Reference: `#/components/parameters/includeTotal`
- Parameter name: `includeTotal`
- Location: `query`
- Required: `false`
- Description:
> Return results inside an object that contains the total result count or not.
- Schema: `boolean`
- Constraints: default=false
### `limit`
- Reference: `#/components/parameters/limit`
- Parameter name: `limit`
- Location: `query`
- Required: `false`
- Description:
> A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
- Schema: `integer (int32)`
- Constraints: minimum=1; maximum=100; default=10
### `noteId-in_path_for_contact_note`
- Reference: `#/components/parameters/noteId-in_path_for_contact_note`
- Parameter name: `noteId`
- Location: `path`
- Required: `true`
- Description:
> The 24-character ObjectId of the contact note.
- Schema: `string`
- Constraints: minLength=24; maxLength=24; pattern="^[0-9a-fA-F]{24}$"; example="6a3de646e18f344f743aaa4d"
### `page`
- Reference: `#/components/parameters/page`
- Parameter name: `page`
- Location: `query`
- Required: `false`
- Description:
> Page number of the results to be returned, 1-based.
- Schema: `integer (int32)`
- Constraints: minimum=1; maximum=100; default=1
### `Contact`
- Reference: `#/components/schemas/Contact`
- Shape: `object`
- Description:
> Represents a contact.
- Required properties: `id`
- Properties:
- `countryCode`: `string`
- Description:
> Two-letter country abbreviation. See [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
- Constraints: example="US"
- `countryName`: `string`
- Description:
> Full country name.
- `createTime`: `string (date-time)`
- Description:
> The time at which the contact was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
- `customAttributes`: `array`
- Description:
> Contact's custom attributes.
- Items: `#/components/schemas/ContactCustomAttribute`
- `email`: `string`
- Description:
> The contact's email address.
> If present, the email address must be unique.
- Constraints: example="support@example.com"
- `id`: `string` (required)
- Description:
> Unique ID for the object.
- Constraints: maxLength=255; example=1693364594105000026
- `lastMessageToPhoneNumber`: `string`
- Description:
> The business phone number that the contact last sent a message to.
- Constraints: example="+16315551111"
- `lastSeen`: `string (date-time)`
- Description:
> The time at which the contact last sent a message to your business, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
- `metaUsername`: `string`
- Description:
> The read-only Meta username associated with the contact, without the leading `@`.
- Constraints: example="alice_01"
- `nickname`: `string`
- Description:
> The read-only nickname obtained from WhatsApp.
- Constraints: example="nickname"
- `ownerEmail`: `string`
- Description:
> The email address of the contact's owner.
- Constraints: maxLength=250; example="support@example.com"
- `phoneNumber`: `string`
- Description:
> Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
- Constraints: example="+16315551111"
- `remarkName`: `string`
- Description:
> The business-managed remark name for the contact.
- Constraints: maxLength=250; example="Priority customer"
- `sourceId`: `string`
- Description:
> Source identifier. A unique identifier related to the contact creation source.
- Constraints: maxLength=255; example="batch_import_123"
- `sourceType`: `#/components/schemas/ContactSourceType`
- Description:
> The source type of the contact. Indicates how the contact was created.
- `sourceUrl`: `string`
- Description:
> Source URL. The source link address where the contact was created.
- Constraints: maxLength=500; example="https://example.com/signup"
- `tags`: `array`
- Description:
> Contact's tags.
- Constraints: maxItems=50
- Items: `string`
### `ContactAttribute`
- Reference: `#/components/schemas/ContactAttribute`
- Shape: `object`
- Description:
> Represents a contact attribute configuration.
> Contains information about the attribute's metadata and available values.
- Required properties: `id`, `name`, `key`, `type`
- Properties:
- `desc`: `string`
- Description:
> Description of the contact attribute.
- Constraints: example=""
- `id`: `string` (required)
- Description:
> Unique identifier for the contact attribute.
- Constraints: example="6865e6c17c3854485be550b0"
- `key`: `string` (required)
- Description:
> Key name used to reference this attribute.
- Constraints: example="blocked"
- `name`: `string` (required)
- Description:
> Display name of the contact attribute.
- Constraints: example="Blocked"
- `type`: `string` (required)
- Description:
> Data type of the contact attribute.
- Constraints: enum=["BOOLEAN", "TEXT", "TIME", "ARRAY"]; example="BOOLEAN"
- `values`: `array`
- Description:
> Array of possible values for this attribute.
> Only present when type is "ARRAY".
- Constraints: example=["a1", "wa", "a3"]
- Items: `string`
- Constraints: example={"desc": "", "id": "6865e6c17c3854485be550b0", "key": "blocked", "name": "Blocked", "type": "BOOLEAN", "values": []}
### `ContactCreateRequest`
- Reference: `#/components/schemas/ContactCreateRequest`
- Shape: `object`
- Description:
> Contains the properties of the contact to be created.
- Required properties: `phoneNumber`
- Properties:
- `countryCode`: `string`
- Description:
> Two-letter country abbreviation. See [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
- Constraints: example="US"
- `customAttributes`: `array`
- Description:
> Contact's custom attributes.
- Items: `#/components/schemas/ContactCustomAttribute`
- `email`: `string`
- Description:
> Contact's email address.
> If present, the email address must be unique.
- Constraints: maxLength=250; example="support@example.com"
- `nickname`: `string`
- Description:
> Deprecated compatibility alias for `remarkName`.
> When `remarkName` is absent, this value is saved as the contact's remark name. It does not update the read-only WhatsApp nickname.
> Maximum length: 250 characters.
- Constraints: maxLength=250; deprecated=true; example="remark name"
- `notes`: `array`
- Description:
> Optional notes created atomically with the contact. The response remains the Contact schema;
> use the List Contact Notes endpoint to retrieve generated note IDs.
- Constraints: maxItems=50
- Items: `#/components/schemas/ContactNoteCreateInput`
- `ownerEmail`: `string`
- Description:
> The email address of the contact's owner.
- Constraints: maxLength=250; example="support@example.com"
- `phoneNumber`: `string` (required)
- Description:
> Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
- Constraints: example="+16315551111"
- `remarkName`: `string`
- Description:
> Contact's remark name. Maximum length: 250 characters.
- Constraints: maxLength=250; example="remark name"
- `tags`: `array`
- Description:
> Contact's tags. Max items: 50. Max characters per tag: 50.
- Constraints: maxItems=50
- Items: `string`
### `ContactCustomAttribute`
- Reference: `#/components/schemas/ContactCustomAttribute`
- Shape: `object`
- Properties:
- `name`: `string`
- Description:
> Name of the attribute that you've previously defined.
- `value`: `object`
- Description:
> Value of the attribute.
> Its data type depends on the format of the attribute you defined:
> For Text, the `value` is a string with a maximum length of 250.
> For Array, the `value` is an array of strings with a maximum length of 250.
> For Number, the `value` is a signed decimal number.
> For Boolean, the `value` is either `true` or `false`.
> For Time, the `value` is a Unix timestamp in milliseconds.
> For Long Text, the `value` is a string with a maximum length of 5000.
### `ContactNote`
- Reference: `#/components/schemas/ContactNote`
- Shape: `object`
- Description:
> Represents an internal note attached to a contact.
- Required properties: `id`, `contactId`, `content`
- Properties:
- `contactId`: `string` (required)
- Description:
> Unique ID of the contact that owns this note.
- Constraints: example=1693364594105000026
- `content`: `string` (required)
- Description:
> Note content.
- Constraints: maxLength=500; example="Customer prefers follow-up in the morning."
- `createTime`: `string (date-time)`
- Description:
> The time at which the note was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
- `id`: `string` (required)
- Description:
> Unique 24-character ObjectId for the contact note. IDs remain unchanged after storage migration.
- Constraints: minLength=24; maxLength=24; pattern="^[0-9a-fA-F]{24}$"; example="6a3de646e18f344f743aaa4d"
- `operatorId`: `string`
- Description:
> ID of the actor who created the note.
- Constraints: example="user_123"
- `updateOperatorId`: `string`
- Description:
> ID of the actor who last updated the note.
- Constraints: example="user_123"
- `updateTime`: `string (date-time)`
- Description:
> The time at which the note was last updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
### `ContactNoteCreateInput`
- Reference: `#/components/schemas/ContactNoteCreateInput`
- Shape: `object`
- Description:
> A contact note to create together with a contact.
- Required properties: `content`
- Properties:
- `content`: `string` (required)
- Description:
> Note content. Leading and trailing whitespace is removed before validation and storage.
- Constraints: minLength=1; maxLength=500; example="Customer prefers follow-up in the morning."
### `ContactNoteMutationInput`
- Reference: `#/components/schemas/ContactNoteMutationInput`
- Shape: `object`
- Description:
> An incremental note mutation for a contact update. When `id` is absent, a new note is created.
> When `id` is present, the owned note is updated. Notes omitted from the array remain unchanged.
- Required properties: `content`
- Properties:
- `content`: `string` (required)
- Description:
> Note content. Leading and trailing whitespace is removed before validation and storage.
- Constraints: minLength=1; maxLength=500; example="Customer now prefers afternoon follow-up."
- `id`: `string`
- Description:
> Existing note ID. Omit to create a new note.
- Constraints: minLength=24; maxLength=24; pattern="^[0-9a-fA-F]{24}$"; example="6a3de646e18f344f743aaa4d"
### `ContactNoteWriteRequest`
- Reference: `#/components/schemas/ContactNoteWriteRequest`
- Shape: `object`
- Description:
> Request body for creating or updating one contact note.
- Required properties: `content`
- Properties:
- `content`: `string` (required)
- Description:
> Note content. Leading and trailing whitespace is removed before validation and storage.
- Constraints: minLength=1; maxLength=500; example="Customer now prefers afternoon follow-up."
### `ContactPage`
- Reference: `#/components/schemas/ContactPage`
- Shape: `object`
- Description:
> Represents a given page of contacts. In cursor mode, `offset` is `0`, items are ordered by contact ID in ascending order, and `cursor` is returned only when another page exists. When `includeTotal=true`, `total` is the complete filtered count and is not reduced by the cursor position.
- `allOf` composition (preserved; not inferred SDK inheritance):
- `#/components/schemas/Page`
- `$ref`: `#/components/schemas/Page`
- Properties:
- `cursor`: `#/components/schemas/ContactPageCursor`
- `items`: `array`
- Description:
> An array containing contact objects.
- Items: `#/components/schemas/Contact`
- Effective wire object after merging `allOf` (use this shape in response adapters):
- Required properties: `offset`, `limit`, `length`
- Properties:
- `items`: `array`
- Items: `#/components/schemas/Contact`
- `length`: `integer (int32)` (required)
- `limit`: `integer (int32)` (required)
- `offset`: `integer (int32)` (required)
- `total`: `integer (int32)`
- `cursor`: `#/components/schemas/ContactPageCursor`
### `ContactPageCursor`
- Reference: `#/components/schemas/ContactPageCursor`
- Shape: `object`
- Description:
> Position of the next Contact page. This object is returned only when another page exists.
- Required properties: `after`
- Properties:
- `after`: `string` (required)
- Description:
> Contact ID of the last public item in this page. Pass this value unchanged as `pageAfter` to fetch the next page.
- Constraints: pattern="^[1-9][0-9]{0,18}$"; example="1866762588313988096"
### `ContactSourceType`
- Reference: `#/components/schemas/ContactSourceType`
- Shape: `string`
- Description:
> Contact source type enumeration values. These are internal type identifiers, not the display names shown on the contact page.
> Each enumeration value corresponds to the following display names:
> - WHATSAPP: "Inbound message"
> - GROWTH_TOOL: "Link/QR Code"
> - MANUALLY_ADDED: "Manually added"
> - FILE_IMPORT: "File import"
> - SHOPIFY: "Shopify"
> - API: "API added"
> - AD: "AD"
> - POST: "Post"
> - CALLING: "Calling"
> - SMB: "Whatsapp Business App"
> - UNKNOWN: "Unknown"
- Constraints: enum=["WHATSAPP", "GROWTH_TOOL", "MANUALLY_ADDED", "FILE_IMPORT", "SHOPIFY", "API", "AD", "POST", "CALLING", "SMB", "UNKNOWN"]; example="API"
### `ContactUpdateRequest`
- Reference: `#/components/schemas/ContactUpdateRequest`
- Shape: `object`
- Description:
> Contains the properties of the contact to be updated.
- Properties:
- `countryCode`: `string`
- Description:
> Two-letter country abbreviation. See [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
- Constraints: example="US"
- `customAttributes`: `array`
- Description:
> Contact's custom attributes.
> If present (i.e., not `null`), all previous attributes of this contact will be replaced.
- Items: `#/components/schemas/ContactCustomAttribute`
- `email`: `string`
- Description:
> The contact's email address.
> If present, the email address must be unique.
- Constraints: maxLength=250; example="support@example.com"
- `nickname`: `string`
- Description:
> Deprecated compatibility alias for `remarkName`.
> When `remarkName` is absent, this value is saved as the contact's remark name. It does not update the read-only WhatsApp nickname.
> Maximum length: 250 characters.
- Constraints: maxLength=250; deprecated=true; example="remark name"
- `notes`: `array`
- Description:
> Optional incremental note mutations. An empty array changes nothing. Items without `id` create notes;
> items with `id` update owned notes. Notes not listed remain unchanged. Delete notes with the dedicated endpoint.
- Constraints: maxItems=50
- Items: `#/components/schemas/ContactNoteMutationInput`
- `ownerEmail`: `string`
- Description:
> The email address of the contact's owner.
- Constraints: maxLength=250; example="support@example.com"
- `phoneNumber`: `string`
- Description:
> Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
- Constraints: example="+16315551111"
- `remarkName`: `string`
- Description:
> Contact's remark name. Maximum length: 250 characters.
- Constraints: maxLength=250; example="remark name"
- `tags`: `array`
- Description:
> Contact's tags. Maximum items: 50.
- Constraints: maxItems=50
- Items: `string`
### `Error`
- Reference: `#/components/schemas/Error`
- Shape: `object`
- Required properties: `status`, `code`
- Properties:
- `code`: `string` (required)
- Description:
> One of a server-defined error codes. Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported.
- Constraints: example="NOT_FOUND"
- `docUrl`: `string`
- Description:
> A URL to more information about the error.
- Constraints: example=""
- `message`: `string`
- Description:
> A human-readable representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users.
- Constraints: example="The requested resource does not exist."
- `requestId`: `string`
- Description:
> Each API request has an associated request ID. It conveys the response header `YCloud-Request-ID` used for the convenience of the consumer.
- Constraints: example="req_1KjtKI80IKoaJNa6n6p"
- `status`: `integer (int32)` (required)
- Description:
> HTTP status code, [RFC 7231, Section 6](https://datatracker.ietf.org/doc/html/rfc7231#section-6). It conveys the HTTP status code used for the convenience of the consumer.
- Constraints: pattern="[45]\\d{2}"; example=404
- `target`: `string`
- Description:
> The target of the error.
- Constraints: example=""
- `whatsappApiError`: `#/components/schemas/WhatsappApiError`
- Description:
> The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
>
> Note: This field is returned if we tried to request the WhatsApp Business API and got an error response.
### `ErrorResponse`
- Reference: `#/components/schemas/ErrorResponse`
- Shape: `object`
- Required properties: `error`
- Properties:
- `error`: `#/components/schemas/Error` (required)
### `Page`
- Reference: `#/components/schemas/Page`
- Shape: `object`
- Description:
> Represents a given page of items.
- Required properties: `offset`, `limit`, `length`
- Properties:
- `items`: `array`
- Items: `object`
- `length`: `integer (int32)` (required)
- Description:
> The actual number of items in the page.
- Constraints: minimum=0
- `limit`: `integer (int32)` (required)
- Description:
> A limit on the number of items to be returned, between 1 and 100, defaults to 10.
- Constraints: minimum=1
- `offset`: `integer (int32)` (required)
- Description:
> The position of the item this page starts from, zero-based. e.g., the 11th item is at offset 10.
- Constraints: minimum=0
- `total`: `integer (int32)`
- Description:
> The total number of items. This field is returned only when the request parameter `includeTotal` is set to `true`.
- Constraints: minimum=0
### `WhatsappApiError`
- Reference: `#/components/schemas/WhatsappApiError`
- Shape: `object`
- Description:
> The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
- Required properties: `message`, `code`
- Properties:
- `code`: `string` (required)
- Description:
> An error code.
- Constraints: example=200002
- `error_data`: `object`
- Description:
> Additional data about the error. A string or map.
> - For template APIs, this field is a string describing the reason for the error.
> - For message APIs, this field is a map with property `details` describing the reason for the error.
- `error_subcode`: `string`
- Description:
> Additional code about the error.
- Constraints: example=2388109
- `error_user_msg`: `string`
- Description:
> The message to display to the user. The language of the message is based on the locale of the API request.
- Constraints: example="This message template cannot be created."
- `error_user_title`: `string`
- Description:
> The title of the dialog, if shown. The language of the message is based on the locale of the API request.
- Constraints: example="Message Cannot Be Submitted"
- `fbtrace_id`: `string`
- Description:
> Internal support identifier. When reporting a bug related to a Graph API call, include the fbtrace_id to help us find log data for debugging.
- Constraints: example="AVGjJ7ia2zJkrHG"
- `is_transient`: `boolean`
- Description:
> Whether the error is transient.
- Constraints: example=false
- `message`: `string` (required)
- Description:
> A human-readable description of the error.
- Constraints: example="HSM Template creation failed"
- `type`: `string`
- Description:
> Error type.
- Constraints: example="OAuthException"
## Codegen interpretation and unknowns
- `operationId` identifies the OpenAPI operation; it is not an SDK method name.
- `allOf` is wire-level schema composition. Response adapters must merge inherited and local properties; generated model inheritance/flattening is only a codegen shape, not additional API behavior.
- `x-group-parameters`, `x-enum-varnames`, and `x-enum-descriptions` are generator hints, not business rules.
- Description-only constraints (including conditional fields, precedence, and endpoint-specific behavior) remain verbatim above.
- This OpenAPI snapshot does not confirm cross-cutting error, retry/`Retry-After`, rate-limit, idempotency, delivery, or webhook-signature behavior. Consult the reviewed `runtime.md`; if neither source confirms a fact, do not fill it in.
SHA-256: 30202815cb3ad0cb6cdf0b3c1b9205b2ad6ef10bb1142dabe3c40975e2fd64d5