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.
Presence observation#
Presence and typing observation default to off. Set the project's maximum with the project's Number configuration defaults: send API Update session configuration defaults with projectId, the project revision and the modes under configuration.set.observation:
{
"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.
Read the project ceiling with API Get project observation policy and a Number's policy with API Get 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 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.
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 API Subscribe presence. Then read the latest allowed observation with API Get chat presence. 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.
API Get 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 API List labels and one chat's assignments with API Get chat labels. 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.
API Set chat labels 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 API List 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 and its current revision:
{
"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}:
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:
{ "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.
Catalog, product, collection, and order reads are documented under Catalogs and commerce.
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:
{
"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:
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.