API Reference/Messaging/List all chats

List all chats

GEThttps://api.postpress.ai/v1/chats

Returns a paginated list of chats visible to one or more connected accounts. Optional filters narrow the result set by provider, account, read state, and time range.

Authorization

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

Query parameters

account_idstringoptional
A postpress account id or a comma-separated list of ids to filter chats by account.
account_typestringoptional
Filter by provider. One of `WHATSAPP`, `LINKEDIN`, `SLACK`, `TWITTER`, `MESSENGER`, `INSTAGRAM`, `TELEGRAM`.
unreadbooleanoptional
When `true`, only unread chats are returned. When `false`, only read chats.
beforestringoptional
ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). Returns chats created strictly before this datetime.
afterstringoptional
ISO 8601 UTC datetime. Returns chats created strictly after this datetime.
limitintegeroptional
Number of items returned per page. Between 1 and 250. Default 100.
cursorstringoptional
Pagination cursor returned by the previous response. Omit on the first call.

Response 200 OK

objectstringChatListrequired
itemsarray of objectsrequired
The page of chats.
items array
objectstringChatrequired
idstringlength ≥ 1required
Unique chat id.
account_idstringlength ≥ 1required
The postpress account that owns the chat.
account_typestringrequired
WHATSAPPLINKEDINSLACKTWITTERMESSENGERINSTAGRAMTELEGRAM
Provider behind the chat.
provider_idstringrequired
Provider-native chat identifier.
attendee_provider_idstring
Provider-native id of the other attendee, for 1:1 chats.
namestringrequired
Chat name or contact name. Nullable.
typenumberrequired
012
Chat type. 0 = 1:1, 1 = group, 2 = broadcast.
timestampstringrequired
Last activity timestamp. Nullable.
unread_countnumberrequired
Number of unread messages in the chat.
archivednumberrequired
01
Archive flag. 0 = not archived, 1 = archived.
muted_untilnumber or stringrequired
Mute state: -1 = muted indefinitely, ISO datetime = muted until that time, null = not muted.
read_onlynumberrequired
012
Read-only state. 0 = writable, 1 = read-only, 2 = locked.
disabledFeaturesarray of strings
Features disabled by the provider for this chat.
disabledFeatures array
<feature>string
reactionsreply
subjectstring
Chat subject (when applicable).
organization_idstring
LinkedIn-specific id for organization mailboxes.
mailbox_idstring
LinkedIn-specific id for organization mailboxes.
content_typestring
inmailsponsoredlinkedin_offer
LinkedIn-specific content classifier.
folderarray of strings
Folders the chat belongs to.
folder array
<folder>string
INBOXINBOX_LINKEDIN_CLASSICINBOX_LINKEDIN_RECRUITERINBOX_LINKEDIN_SALES_NAVIGATORINBOX_LINKEDIN_ORGANIZATION
Provider-known folders, plus arbitrary custom folder names.
pinnednumberrequired
01
Pin flag. 0 = not pinned, 1 = pinned.
cursorstringrequired
Cursor for the next page. `null` when this is the last page.

Example request

curl --request GET \
  --url 'https://api.postpress.ai/api/v1/chats?account_id=acc_01HXYZ4QK3WJ8FN3M6QH7TZ8GR&limit=100' \
  --header 'X-API-KEY: pp_live_...' \
  --header 'accept: application/json'

Example response

{
  "object": "ChatList",
  "items": [
    {
      "object": "Chat",
      "id": "chat_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
      "account_id": "acc_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
      "account_type": "LINKEDIN",
      "provider_id": "2-NTRkZDA4M2QtZDcxZS00YzY5LWE1MWUtZGM5...",
      "attendee_provider_id": "ACoAACr-1eYBl...",
      "name": "Jordan Walke",
      "type": 0,
      "timestamp": "2026-05-17T09:42:11.000Z",
      "unread_count": 2,
      "archived": 0,
      "muted_until": null,
      "read_only": 0,
      "folder": ["INBOX", "INBOX_LINKEDIN_CLASSIC"],
      "pinned": 0
    }
  ],
  "cursor": "eyJhY2NvdW50X2lkIjoiYWNjXzAxIn0="
}

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. Complete authentication on the provider's native application.
  • errors/resource_access_restricted - You don't have access to this resource.
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. Start again from the beginning.
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