Perform an action on a given chat

PATCHhttps://api.postpress.io/api/v1/chats/{chat_id}

Perform a mutating action on a chat: change its read or mute status, archive or pin it, add or remove participants from a group, label it, or retrieve its group invite link.

Authorization

X-API-KEYstringrequired

API key from your postpress dashboard. Sent as a request header.

Path parameters

chat_idstringrequired

The id of the chat to act on.

Request body

The body is one of two variants, chosen by the action value.

Action with valueobjectoptional

For all actions except `getInviteLink`. Requires both `action` and `value`.

Get invite linkobjectoptional

For `getInviteLink`. Only `action` is required; no `value`.

View full schema tree

Action with valueobject

For all actions except `getInviteLink`. Requires both `action` and `value`.

Action with value object

actionstringrequired

setReadStatussetMuteStatussetArchiveStatussetPinnedStatusaddParticipantremoveParticipantsetLabel

The action to perform on the chat:

setReadStatus - (WhatsApp & LinkedIn only) Set the read status of the chat.
setMuteStatus - (WhatsApp & LinkedIn only) Set the mute status of the chat.
setArchiveStatus - (WhatsApp only) Set the archive status of the chat.
setPinnedStatus - (WhatsApp only) Set the pinned status of the chat.
addParticipant - (WhatsApp & Telegram only) Add a participant to the group chat. Make sure that the account owner has the Add other members permission in the group to perform this action. postpress may respond successfully without actually adding the member if this limitation is not respected. Provide the provider ID (334455667788@s.whatsapp.net for WhatsApp, Telegram user ID/username/phone for Telegram) of the user as value.
removeParticipant - (WhatsApp & Telegram only) Remove a participant from the group chat. Provide the provider ID (334455667788@s.whatsapp.net for WhatsApp, Telegram user ID/username/phone for Telegram) of the user as value.
setLabel - (WhatsApp only) Add a label to the chat. If the label does not exist, it will be created and then assigned.

valueboolean or stringrequired

Boolean for status toggles (`setReadStatus`, `setMuteStatus`, `setArchiveStatus`, `setPinnedStatus`). String for `addParticipant`, `removeParticipant` (provider id) and `setLabel` (label name).

Get invite linkobject

For `getInviteLink`. Only `action` is required; no `value`.

Get invite link object

actionstringgetInviteLinkrequired

The action to perform on the chat:

getInviteLink - (WhatsApp & Telegram only) Generate or retrieve the full group invite link. The account owner must have the required invite permissions in the group.

Actions

action	Providers	Description
`setReadStatus`	WhatsApp & LinkedIn	Set the read status of the chat. Boolean.
`setMuteStatus`	WhatsApp & LinkedIn	Set the mute status of the chat. Boolean.
`setArchiveStatus`	WhatsApp	Set the archive status of the chat. Boolean.
`setPinnedStatus`	WhatsApp	Set the pinned status of the chat. Boolean.
`addParticipant`	WhatsApp & Telegram	Add a participant to a group chat. The account must have the “Add other members” permission. Provide a provider id (`334455667788@s.whatsapp.net` for WhatsApp; Telegram user id, username, or phone for Telegram) as `value`.
`removeParticipant`	WhatsApp & Telegram	Remove a participant from a group chat. Provide the same kind of provider id as `value`.
`setLabel`	WhatsApp	Assign a label to the chat. Creates the label if it does not exist. Provide the label name as `value`.
`getInviteLink`	WhatsApp & Telegram	Generate or retrieve the full group invite link. The account must have invite permissions. No `value` field.

Response 200 OK

objectstringChatPatchedrequired

invite_linkstring

Returned only for the `getInviteLink` action.

Example request

{
  "action": "setReadStatus",
  "value": true
}

Example response

{
  "object": "ChatPatched"
}

Errors

Every error response follows the same envelope:

titlestringrequired

Short error title.

detailstringoptional

Human-readable explanation.

instancestringoptional

Request identifier for support.

typestringrequired

Error type identifier.

statusnumberrequired

HTTP status code.

401 Unauthorized13 types

Credentials are missing, expired, or otherwise invalid.

errors/missing_credentials - Some credentials are necessary to perform the request.
errors/multiple_sessions - LinkedIn limits multiple sessions on certain Recruiter accounts. Use the cookie connection method.
errors/invalid_checkpoint_solution - The checkpoint resolution did not pass successfully. Retry.
errors/invalid_proxy_credentials - The provided proxy credentials are invalid.
errors/checkpoint_error - The checkpoint does not appear to be resolvable.
errors/invalid_credentials - The provided credentials are invalid.
errors/expired_credentials - Credentials have expired. Reconnect the account.
errors/insufficient_privileges - This resource is out of your API-key scopes.
errors/disconnected_account - The account is disconnected from the provider service.
errors/disconnected_feature - The service you're trying to reach is disconnected.
errors/invalid_credentials_but_valid_account_imap - IMAP/SMTP credentials are invalid but the account is otherwise valid.
errors/expired_link - This link has expired. Generate a new one.
errors/wrong_account - The provided credentials do not match the correct account.

403 Forbidden9 types

Authenticated but the account is restricted or the action is not allowed.

errors/account_restricted - The account has been restricted by the provider.
errors/account_mismatch - This action cannot be done with your account.
errors/insufficient_permissions - Valid authentication but insufficient permissions to perform the request.
errors/session_mismatch - Token user id does not match client session id.
errors/feature_not_subscribed - The requested feature has not been subscribed or authenticated properly.
errors/subscription_required - A subscription is required to use this feature.
errors/unknown_authentication_context - An additional step seems necessary to complete login.
errors/action_required - An additional step is required.
errors/resource_access_restricted - You don't have access to this resource.

404 Not Found2 types

The chat id does not match any chat visible to this API key.

errors/resource_not_found - The requested resource was not found.
errors/invalid_resource_identifier - The provided identifier is not a valid chat id.

500 Internal Server Error3 types

Something went wrong on our side or with the upstream provider.

errors/unexpected_error - Something went wrong.
errors/provider_error - The provider is experiencing operational problems. Retry later.
errors/authentication_intent_error - The current authentication intent was killed after failure.

501 Not Implemented1 types

This action is not supported for the chat's provider yet.

errors/feature_not_implemented - Requested feature is planned but has not been implemented yet.

503 Service Unavailable5 types

postpress is temporarily unable to handle the request.

errors/no_client_session - No client session is currently running.
errors/no_channel - No channel to client session.
errors/no_handler - Handler missing for that request.
errors/network_down - Network is down on the server side. Retry shortly.
errors/service_unavailable - Service temporarily unavailable. Retry later.

504 Gateway Timeout1 types

The upstream provider did not respond in time.

errors/request_timeout - Request timed out. Retry, and contact support if it persists.

Updated May 2026