# Linked-device controls

> Control privacy, presence, labels, history sync, groups, channels and incoming calls on Linked Devices Numbers.

A Linked Devices Number is a WhatsApp account that Polymorfa joined as a
linked device. These native Messaging API methods control that account:
what it shares, what Polymorfa observes and remembers, and how it handles
groups, channels and calls.

Paths below start with `https://api.polymorfa.com/messaging/{session}`, where
`{session}` is the Number ID, and require the scope shown in each method's
reference.

Most paths accept a team key. The presence and observation-policy paths also
accept a project token. A credential kind that a path does not accept returns
`403` before the request reaches the Number, whatever its scopes. Client tokens are
authorized by their recorded actions rather than by scopes. The per-operation
credential kinds and client actions for presence are listed in
[SDK availability](https://docs.polymorfa.com/api/presence/subscribe-presence).

## Presence observation

Presence and typing observation default to `off`. Set the project's maximum
with the project's Number configuration defaults: send
`PUT /platform/session-configuration` with `projectId`, the project revision
and the modes under `configuration.set.observation`:

```json
{
  "projectId": "00000000-0000-4000-8000-000000000001",
  "revision": 3,
  "configuration": {
    "set": {
      "observation": {
        "presenceMode": "events",
        "typingMode": "cache",
        "labelMode": "events",
        "quickReplyMode": "events"
      }
    }
  }
}
```

Each setting accepts one of these modes:

| Mode | Webhooks | In-memory lookup cache |
| --- | --- | --- |
| `off` | No | No |
| `events` | Yes | No |
| `cache` | Yes | Yes |

`labelMode` accepts one further mode, `project`, which adds a durable
project-scoped projection. See [Label observation](#label-observation).

Read the project ceiling with `GET /messaging/projects/{projectId}/observation-policy`
and a Number's policy with `GET /messaging/{session}/observation-policy`. The
older `PUT` on those paths returns `410` `configuration_migration_required`.

A Number inherits the project ceiling until it overrides a mode with
[Update session](https://docs.polymorfa.com/api/numbers/update-session) under
`configuration.set.observation`. Remove an override with
`configuration.reset`, for example `["observation.presenceMode"]`. A mode above
the project ceiling returns `400`. See
[Configure a Number](https://docs.polymorfa.com/numbers/manage#configuration).

Policy updates require `presence:observe`. Changing `labelMode` additionally
requires `labels:manage`; an older client can omit `labelMode` without changing
the existing label policy. Presence subscriptions require `presence:observe`.
Reading the policy or cached state requires `presence:read`, while changing the
linked account's own presence requires `presence:write`.

Subscribe to one user for 120 seconds with
`POST /messaging/{session}/presence/{conversation}/subscribe`. Then read the latest
allowed observation with `GET /messaging/{session}/presence/{conversation}`. A GET never
subscribes and never performs a live WhatsApp lookup. It returns `status` as
`unknown`, `fresh`, or `stale`; `unknownReason` is `disabled`, `not_observed`,
or `suspended`. Cached records include `observedAt`, may include `lastSeen`, and
become stale after 180 seconds.

`GET /messaging/{session}/presence` reports the Number's last requested and last
successfully sent presence. Its `authoritative` field is always `false`; the
linked-device protocol has no synchronous read of the Number's current
presence.

Observation is bounded per Number to 256 cached identities and 64 active targets.
Within ten minutes, a Number can request at most 128 unique targets, 240 total
subscriptions, and 12 renewals for one target. Exceeding a limit returns
`429`, clears cached presence records and active subscriptions, and suspends
presence observation for 15 minutes. Subscription attempts during that window
also return `429`. Typing observation is unaffected: its policy, its webhooks,
and any cached chat state continue under `typingMode`.
Messaging remains connected. Presence observations are ephemeral and are never
stored.

## Label observation

`labelMode` controls whether Polymorfa retains label definitions and chat-label
associations. It accepts `off`, `events`, `cache`, or `project`. The default is
`off`: label observation is opt-in, like presence and typing observation. A
Number override cannot exceed the project setting.

| Mode | `labels.update` webhooks | Synchronous reads | Retention |
| --- | --- | --- | --- |
| `off` | No | Disabled | None |
| `events` | Yes | Unknown | None |
| `cache` | Yes | Best-effort | Bounded memory per Number |
| `project` | Yes | Best-effort | Project-scoped durable projection |

Changing `project` to a lower-retention mode removes the durable projection,
including projections for disconnected Numbers. Removal runs in the
background. Re-enabling `project` while that removal is still in progress
returns `409`; retry once it completes. If `409` persists, contact support.

Read definitions with `GET /messaging/{session}/labels` and one chat's assignments
with `GET /messaging/{session}/labels/chats/{conversation}`. These existing routes return
the label array by default. Add `?includeObservation=true` to receive `policy`,
`status`, and `labels`. `status` is `disabled`, `unknown`, `partial`, or `fresh`.
An `unknown` response includes `unknownReason` as `observation_disabled`,
`not_retained`, `not_observed`, or `expired`. Cache results include `observedAt`
and `expiresAt`; cache observations expire after 15 minutes. Durable results
include `observedAt` without a cache expiry.

A full linked-device sync replaces the durable projection as one generation.
Incremental events received before that snapshot return `partial`, so clients
can distinguish remembered data from a complete snapshot.

`PUT /messaging/{session}/labels/chats/{conversation}` has replacement semantics and accepts
an empty `labels` array to remove all assignments. Replacement requires an
authoritative cached or durable view of the chat. If that view is unavailable,
the endpoint returns `409` without sending a partial update. Label updates that
omit `name` or `color` have the same requirement so omitted fields are never
overwritten with empty values.

## Quick-reply observation

`quickReplyMode` controls observation of WhatsApp Business App quick replies.
It accepts `off`, `events`, or `cache` and defaults to `events`. A Number
override cannot exceed the project setting.

| Mode | `business.quick_reply.update` webhooks | Synchronous reads | Retention |
| --- | --- | --- | --- |
| `off` | No | Disabled | None |
| `events` | Yes | Unknown | None |
| `cache` | Yes | Best-effort | Bounded memory per Number |

Read remembered entries with
`GET /messaging/{session}/business/quick-replies`. The response includes `policy`,
`status`, and `quickReplies`. `status` is `disabled`, `unknown`, `partial`, or
`fresh`. An `unknown` response includes `unknownReason` as
`observation_disabled`, `not_retained`, or `not_observed`.

A full linked-device sync replaces the in-memory projection atomically.
Incremental changes received before that snapshot return `partial`. The cache
retains at most 256 entries within a 256 KiB payload budget per Number and is
cleared when observation is disabled. A GET never performs a live WhatsApp
lookup, and quick-reply content is never stored. During a full
sync, the incoming 256 KiB payload budget is staged separately until it
replaces the previous snapshot or the sync fails.

## History sync processing

History sync defaults to metadata-only processing. Configure a Linked Devices
Number with [Update session](https://docs.polymorfa.com/api/numbers/update-session) and its
current revision:

```json
{
  "revision": 2,
  "configuration": {
    "set": {
      "historySync": { "mode": "metadata_only", "requestFull": false }
    }
  }
}
```

`mode` accepts `metadata_only` or `deliver`. `metadata_only` keeps a
project-scoped record of each chunk's identity, sync type, order, progress,
file length, item counts, outcome and timestamps. It does not publish message
bodies or keep per-message history secrets. `deliver` publishes the compressed protobuf through
the durable `history.sync` webhook path before acknowledging the chunk.

The linked device sends `hist_sync` only after the selected acceptance point.
Duplicate notifications reuse the stored outcome and event identity, including a
chunk the device re-uploads under a new identifier after a failure: it resolves
to the original record and is not delivered twice. A chunk whose delivery
attempt fails keeps its record unacknowledged so it is retried. A chunk whose
record cannot be written is not acknowledged; the phone sends it again on the
next sync. Records contain no protobuf, message body, contact body, media key,
or download path. Acknowledged metadata is retained for 30 days. Unacknowledged
or failed metadata is retained for 90 days so delivery failures remain diagnosable
without allowing the table to grow without bound.

`deliver` refuses a chunk larger than the event transport carries, records the
outcome as `payload_too_large`, and does not acknowledge it. The chunk's record
is still written, so the sync type, item counts, and size stay visible in
`metadata_only` terms. Keep `requestFull` disabled if you need every chunk of a
large history delivered as a webhook payload.

`requestFull` defaults to `false`. When enabled, it applies on the next pairing
registration and requests at most 30 days, 64 MB per full sync, and 128 MB of
declared storage quota. A change made while the Number is waiting for a QR scan
still reaches that pairing. A new processing mode applies to a connected
Number immediately; changing `requestFull` does not start a live lookup or
download.

Deleting a Number deletes its history-sync records with it, before the
retention windows above elapse.

History processing keeps message identifiers and routing metadata even in
`metadata_only` mode. These identifiers contain no message bodies and last
until the Number is deleted; the chunk-status retention windows above do
not expire message IDs.

In `deliver` events, `messages` indexes each identifiable historical message
with its Polymorfa `id`, `whatsapp_ids` provider references, and conversation identity. The
unmodified provider archive is separate in `whatsapp.data`, with encoding
`gzip-base64-protobuf`. That archive retains provider addresses inside its
protobuf. Use the public index for message references. The event's
`whatsapp_ids` and optional `original_whatsapp_ids` contain the Linked Device
references for the provider's sync
notification and re-upload, not ordinary chat messages.

## Privacy and disappearing messages

Read all privacy categories with `GET /privacy`. Update one category with
`PUT /privacy/{setting}`:

```bash
curl -X PUT "https://api.polymorfa.com/messaging/$SESSION/privacy/readreceipts" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"none"}'
```

The available setting names and values are defined by the
`SetPrivacySettingRequest` schema in the generated reference. Invalid
setting/value combinations return `400` without changing the account.

Set the default timer for new conversations with
`PUT /privacy/disappearing/default`. Set a timer for one direct or group chat
with `PUT /chats/{conversation}/disappearing`:

```json
{ "durationSeconds": 86400 }
```

`durationSeconds` accepts `0`, `86400`, `604800`, or `7776000`, representing
off, 24 hours, 7 days, or 90 days. A direct-chat timer update uses the same
encrypted message transport as other outgoing direct-chat messages.

## Contact metadata and blocklist

The contact endpoints expose cached contact names and live account metadata:

| Operation | Path |
| --- | --- |
| Read live status, stable user ID, aliases, picture ID, and device metadata | `GET /contacts/{contactId}/info` |
| Resolve a phone number or username to a stable user ID | `GET /identities/resolve` |
| Read the identity verification code for a stable user ID | `GET /users/{id}/security-code` |
| List linked devices | `GET /contacts/{contactId}/devices` |
| Read a WhatsApp business profile | `GET /contacts/{contactId}/business-profile` |
| Read blocked contact IDs | `GET /contacts/blocked` |
| Block or unblock a contact | `POST /contacts/{contactId}/block`, `POST /contacts/{contactId}/unblock` |

Live metadata comes from the linked account. Empty profile fields remain empty
strings or arrays; they do not imply that the contact is a business account.
Contact and participant objects use the stable `id` as their primary key;
phone numbers and usernames are optional aliases. See
[User identities](https://docs.polymorfa.com/messaging/user-identities).

Catalog, product, collection, and order reads are documented under
[Catalogs and commerce](https://docs.polymorfa.com/numbers/catalog).

## Group settings

Use these operations after creating or joining a group:

| Setting | Path | Request |
| --- | --- | --- |
| Who can edit group information | `PUT /groups/{id}/settings/info-edit` | `{ "adminsOnly": true }` |
| Who can send messages | `PUT /groups/{id}/settings/messages` | `{ "adminsOnly": true }` |
| Who can add members | `PUT /groups/{id}/settings/member-add` | `{ "mode": "admin_add" }` |
| Require join approval | `PUT /groups/{id}/settings/join-approval` | `{ "required": true }` |

`member-add` accepts `admin_add` or `all_member_add`.

## Channels

Create a channel with `POST /channels`, and delete a channel you own with
`DELETE /channels/{id}`. Deletion is permanent. The delete request returns
success only after WhatsApp confirms that the channel state is `DELETED`:

```json
{
  "success": true,
  "data": { "status": "DELETED" }
}
```

After creating or following a channel, you can read and interact with its
messages:

| Operation | Path |
| --- | --- |
| List messages | `GET /channels/{id}/messages?count=50&before={position}` |
| List view and reaction updates | `GET /channels/{id}/message-updates?count=50&since={unixSeconds}&after={position}` |
| Mark a message viewed | `POST /channels/{id}/messages/{messageId}/viewed` |
| Add or remove your reaction | `POST /channels/{id}/messages/{messageId}/reaction` |
| Subscribe temporarily to live updates | `POST /channels/{id}/live-updates` |

Send an empty `reaction` string to remove your existing reaction. The live
updates response contains `durationSeconds`; subscribe again after that period
if you still need live channel updates.

## Reject an incoming call

Use the `callId` and caller ID from the incoming-call webhook:

```bash
curl -X POST "https://api.polymorfa.com/messaging/$SESSION/calls/$CALL_ID/reject" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"731604928517263"}'
```

The operation rejects an incoming call. It does not initiate or answer calls.

## Unsupported operations

An operation that cannot be performed by the linked-device protocol returns
`501`. Treat `501` as a capability boundary rather than retrying it. The
generated native endpoint reference lists the exact request and response
schemas for every operation.

## See also

- [Configure a Number](https://docs.polymorfa.com/numbers/manage#configuration)
- [Contacts and groups](https://docs.polymorfa.com/messaging/contacts-and-groups)
- [User identities](https://docs.polymorfa.com/messaging/user-identities)
- [Channels](https://docs.polymorfa.com/messaging/channels)
