--- title: "List chats" method: GET path: "/v1/chats" tags: ["Chats"] --- # List chats `GET /v1/chats` List all chats sorted by last activity (most recent first). Combines all accounts into a single paginated list. ## Query parameters - `cursor` string — Opaque pagination cursor; do not inspect. Use together with 'direction'. - `direction` 'after' | 'before' — Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `accountIDs` string[] — Limit to specific account IDs. If omitted, fetches from all accounts. ## Response `200` Request executed successfully - ListChatsOutput - `items` object[], required — Chats ordered by last activity timestamp (most recent first). - `id` string, required — Unique identifier of the chat across Beeper. - `localChatID` string, nullable — Local chat ID specific to this Beeper Desktop installation. - `accountID` string, required — Account ID this chat belongs to. - `title` string, required — Display title of the chat as computed by the client/server. - `type` 'single' | 'group', required — Chat type: 'single' for direct messages, 'group' for group chats. - `participants` object, required — Chat participants information. - `items` object[], required — Participants returned for this chat (limited by the request; may be a subset). - `id` string, required — Stable Beeper user ID. Use as the primary key when referencing a person. - `username` string — Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `phoneNumber` string — User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `email` string — Email address if known. Not guaranteed verified. - `fullName` string — Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL` string — Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `cannotMessage` boolean — True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. - `isSelf` boolean — True if this user represents the authenticated account's own identity. - `hasMore` boolean, required — True if there are more participants than included in items. - `total` integer, required — Total number of participants in the chat. - `lastActivity` string, date-time — Timestamp of last activity. - `unreadCount` integer, required — Number of unread messages. - `lastReadMessageSortKey` string — Last read message sortKey. - `isArchived` boolean — True if chat is archived. - `isMuted` boolean — True if chat notifications are muted. - `isPinned` boolean — True if chat is pinned. - `preview` object — Last message preview for this chat, if available. - `id` string, required — Message ID. - `chatID` string, required — Unique identifier of the chat. - `accountID` string, required — Beeper account ID the message belongs to. - `senderID` string, required — Sender user ID. - `senderName` string — Resolved sender display name (impersonator/full name/username/participant name). - `timestamp` string, date-time, required — Message timestamp. - `sortKey` string, required — A unique, sortable key used to sort messages. - `type` 'TEXT' | 'NOTICE' | 'IMAGE' | 'VIDEO' | 'VOICE' | 'AUDIO' | 'FILE' | 'STICKER' | 'LOCATION' | 'REACTION' — Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages. - `text` string — Plain-text body if present. May include a JSON fallback with text entities for rich messages. - `isSender` boolean — True if the authenticated user sent the message. - `attachments` Attachment[] — Attachments included with this message, if any. - `id` string — Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path. - `type` 'unknown' | 'img' | 'video' | 'audio', required — Attachment type. - `srcURL` string — Public URL or local file path to fetch the asset. May be temporary or local-only to this device; download promptly if durable access is needed. - `mimeType` string — MIME type if known (e.g., 'image/png'). - `fileName` string — Original filename if available. - `fileSize` number — File size in bytes if known. - `isGif` boolean — True if the attachment is a GIF. - `isSticker` boolean — True if the attachment is a sticker. - `isVoiceNote` boolean — True if the attachment is a voice note. - `duration` number — Duration in seconds (audio/video). - `posterImg` string — Preview image URL for video attachments (poster frame). May be temporary or local-only to this device; download promptly if durable access is needed. - `size` object — Pixel dimensions of the attachment: width/height in px. - `width` number - `height` number - `isUnread` boolean — True if the message is unread for the authenticated user. May be omitted. - `linkedMessageID` string — ID of the message this is a reply to, if any. - `reactions` Reaction[] — Reactions to the message, if any. - `id` string, required — Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise. - `reactionKey` string, required — The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face". - `imgURL` string — URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed. - `participantID` string, required — User ID of the participant who reacted. - `emoji` boolean — True if the reactionKey is an emoji. - `hasMore` boolean, required — True if additional results can be fetched using the provided cursors. - `oldestCursor` string, nullable, required — Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect. - `newestCursor` string, nullable, required — Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect. ## Other responses - `400` — Invalid request parameters - `401` — Access token is missing or invalid - `403` — Access token does not have the required scope - `404` — Resource not found - `422` — Unprocessable entity - validation error - `429` — Too many requests - rate limit exceeded - `500` — Internal server error ## Changes - **2026-02-20** `4acef56b00be` — 14 info - added `subschema #1, subschema #2, subschema #3` to the `details` response property `anyOf` list for the response status `400` - added `subschema #1, subschema #2, subschema #3` to the `details` response property `anyOf` list for the response status `401` - added `subschema #1, subschema #2, subschema #3` to the `details` response property `anyOf` list for the response status `403` - added `subschema #1, subschema #2, subschema #3` to the `details` response property `anyOf` list for the response status `404` - …10 more - **2026-02-20** `ee25e67fc85c` — 1 breaking - removed the required property `items/items/allOf[#/components/schemas/Chat]/network` from the response with the `200` status - **2026-02-13** `3f6555bfea11` — 1 info - added the required property `items/items/allOf[#/components/schemas/Chat]/network` to the response with the `200` status - **2026-01-31** `099d55ac0e74` — 1 breaking - removed the required property `items/items/allOf[#/components/schemas/Chat]/network` from the response with the `200` status - …earlier changes not shown [Full history](https://skmtc.dev/beeper/apis/beeper-desktop-api/changes/v1/chats/get.md) --- [API](https://skmtc.dev/beeper/apis/beeper-desktop-api.md) · [All operations](https://skmtc.dev/beeper/apis/beeper-desktop-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/beeper/beeper-desktop-api/revisions/5a8ac7b545c4/schema)