Perform an action on a given chat

PATCHhttps://api.postpress.ai/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 valueobject

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

Action with value object

actionstringrequired

setReadStatussetMuteStatussetArchiveStatussetPinnedStatusaddParticipantremoveParticipantsetLabel

Which action to perform on the chat. See the actions table below for provider support and value semantics.

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

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