# Chats ## Retrieve `$ beeper-desktop-cli chats retrieve` **get** `/v1/chats/{chatID}` Retrieve chat details including metadata, participants, and latest message ### Parameters - `--chat-id: string` Unique identifier of the chat. - `--max-participant-count: optional number` Maximum number of participants to return. Use -1 for all; otherwise 0–500. Defaults to all (-1). ### Returns - `chat: object { id, accountID, participants, 9 more }` - `id: string` Unique identifier of the chat across Beeper. - `accountID: string` Account ID this chat belongs to. - `participants: object { hasMore, items, total }` Chat participants information. - `hasMore: boolean` True if there are more participants than included in items. - `items: array of User` Participants returned for this chat (limited by the request; may be a subset). - `id: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional 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. - `email: optional string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `total: number` Total number of participants in the chat. - `title: string` Display title of the chat as computed by the client/server. - `type: "single" or "group"` Chat type: 'single' for direct messages, 'group' for group chats. - `"single"` - `"group"` - `unreadCount: number` Number of unread messages. - `isArchived: optional boolean` True if chat is archived. - `isMuted: optional boolean` True if chat notifications are muted. - `isPinned: optional boolean` True if chat is pinned. - `lastActivity: optional string` Timestamp of last activity. - `lastReadMessageSortKey: optional string` Last read message sortKey. - `localChatID: optional string` Local chat ID specific to this Beeper Desktop installation. ### Example ```cli beeper-desktop-cli chats retrieve \ --chat-id '!NCdzlIaMjZUmvmvyHU:beeper.com' ``` ## Create `$ beeper-desktop-cli chats create` **post** `/v1/chats` Create a single/group chat (mode='create') or start a direct chat from merged user data (mode='start'). ### Parameters - `--account-id: string` Account to create or start the chat on. - `--allow-invite: optional boolean` Whether invite-based DM creation is allowed when required by the platform. Used for mode='start'. - `--message-text: optional string` Optional first message content if the platform requires it to create the chat. - `--mode: optional "create" or "start"` Operation mode. Defaults to 'create' when omitted. - `--participant-id: optional array of string` Required when mode='create'. User IDs to include in the new chat. - `--title: optional string` Optional title for group chats when mode='create'; ignored for single chats on most platforms. - `--type: optional "single" or "group"` Required when mode='create'. 'single' requires exactly one participantID; 'group' supports multiple participants and optional title. - `--user: optional object { id, email, fullName, 2 more }` Required when mode='start'. Merged user-like contact payload used to resolve the best identifier. ### Returns - `ChatNewResponse: object { chatID, status }` - `chatID: string` Newly created chat ID. - `status: optional "existing" or "created"` Only returned in start mode. 'existing' means an existing chat was reused; 'created' means a new chat was created. - `"existing"` - `"created"` ### Example ```cli beeper-desktop-cli chats create \ --account-id accountID ``` ## List `$ beeper-desktop-cli chats list` **get** `/v1/chats` List all chats sorted by last activity (most recent first). Combines all accounts into a single paginated list. ### Parameters - `--account-id: optional array of string` Limit to specific account IDs. If omitted, fetches from all accounts. - `--cursor: optional string` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `--direction: optional "after" or "before"` Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. ### Returns - `ListChatsOutput: object { hasMore, items, newestCursor, oldestCursor }` - `hasMore: boolean` True if additional results can be fetched using the provided cursors. - `items: array of Chat` Chats ordered by last activity timestamp (most recent first). - `preview: optional object { id, accountID, chatID, 11 more }` Last message preview for this chat, if available. - `id: string` Message ID. - `accountID: string` Beeper account ID the message belongs to. - `chatID: string` Unique identifier of the chat. - `senderID: string` Sender user ID. - `sortKey: string` A unique, sortable key used to sort messages. - `timestamp: string` Message timestamp. - `attachments: optional array of Attachment` Attachments included with this message, if any. - `type: "unknown" or "img" or "video" or "audio"` Attachment type. - `"unknown"` - `"img"` - `"video"` - `"audio"` - `id: optional string` Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path. - `duration: optional number` Duration in seconds (audio/video). - `fileName: optional string` Original filename if available. - `fileSize: optional number` File size in bytes if known. - `isGif: optional boolean` True if the attachment is a GIF. - `isSticker: optional boolean` True if the attachment is a sticker. - `isVoiceNote: optional boolean` True if the attachment is a voice note. - `mimeType: optional string` MIME type if known (e.g., 'image/png'). - `posterImg: optional 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: optional object { height, width }` Pixel dimensions of the attachment: width/height in px. - `height: optional number` - `width: optional number` - `srcURL: optional 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. - `isSender: optional boolean` True if the authenticated user sent the message. - `isUnread: optional boolean` True if the message is unread for the authenticated user. May be omitted. - `linkedMessageID: optional string` ID of the message this is a reply to, if any. - `reactions: optional array of Reaction` Reactions to the message, if any. - `id: string` Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise. - `participantID: string` User ID of the participant who reacted. - `reactionKey: string` The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face". - `emoji: optional boolean` True if the reactionKey is an emoji. - `imgURL: optional string` URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed. - `senderName: optional string` Resolved sender display name (impersonator/full name/username/participant name). - `text: optional string` Plain-text body if present. May include a JSON fallback with text entities for rich messages. - `type: optional "TEXT" or "NOTICE" or "IMAGE" or 7 more` Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages. - `"TEXT"` - `"NOTICE"` - `"IMAGE"` - `"VIDEO"` - `"VOICE"` - `"AUDIO"` - `"FILE"` - `"STICKER"` - `"LOCATION"` - `"REACTION"` - `newestCursor: string` Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect. - `oldestCursor: string` Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect. ### Example ```cli beeper-desktop-cli chats list ``` ## Search `$ beeper-desktop-cli chats search` **get** `/v1/chats/search` Search chats by title/network or participants using Beeper Desktop's renderer algorithm. ### Parameters - `--account-id: optional array of string` Provide an array of account IDs to filter chats from specific messaging accounts only - `--cursor: optional string` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `--direction: optional "after" or "before"` Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `--inbox: optional "primary" or "low-priority" or "archive"` Filter by inbox type: "primary" (non-archived, non-low-priority), "low-priority", or "archive". If not specified, shows all chats. - `--include-muted: optional boolean` Include chats marked as Muted by the user, which are usually less important. Default: true. Set to false if the user wants a more refined search. - `--last-activity-after: optional string` Provide an ISO datetime string to only retrieve chats with last activity after this time - `--last-activity-before: optional string` Provide an ISO datetime string to only retrieve chats with last activity before this time - `--limit: optional number` Set the maximum number of chats to retrieve. Valid range: 1-200, default is 50 - `--query: optional string` Literal token search (non-semantic). Use single words users type (e.g., "dinner"). When multiple words provided, ALL must match. Case-insensitive. - `--scope: optional "titles" or "participants"` Search scope: 'titles' matches title + network; 'participants' matches participant names. - `--type: optional "single" or "group" or "any"` Specify the type of chats to retrieve: use "single" for direct messages, "group" for group chats, or "any" to get all types - `--unread-only: optional boolean` Set to true to only retrieve chats that have unread messages ### Returns - `SearchChatsOutput: object { hasMore, items, newestCursor, oldestCursor }` - `hasMore: boolean` True if additional results can be fetched using the provided cursors. - `items: array of Chat` Chats matching the filters. - `id: string` Unique identifier of the chat across Beeper. - `accountID: string` Account ID this chat belongs to. - `participants: object { hasMore, items, total }` Chat participants information. - `hasMore: boolean` True if there are more participants than included in items. - `items: array of User` Participants returned for this chat (limited by the request; may be a subset). - `id: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional 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. - `email: optional string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `total: number` Total number of participants in the chat. - `title: string` Display title of the chat as computed by the client/server. - `type: "single" or "group"` Chat type: 'single' for direct messages, 'group' for group chats. - `"single"` - `"group"` - `unreadCount: number` Number of unread messages. - `isArchived: optional boolean` True if chat is archived. - `isMuted: optional boolean` True if chat notifications are muted. - `isPinned: optional boolean` True if chat is pinned. - `lastActivity: optional string` Timestamp of last activity. - `lastReadMessageSortKey: optional string` Last read message sortKey. - `localChatID: optional string` Local chat ID specific to this Beeper Desktop installation. - `newestCursor: string` Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect. - `oldestCursor: string` Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect. ### Example ```cli beeper-desktop-cli chats search ``` ## Archive `$ beeper-desktop-cli chats archive` **post** `/v1/chats/{chatID}/archive` Archive or unarchive a chat. Set archived=true to move to archive, archived=false to move back to inbox ### Parameters - `--chat-id: string` Unique identifier of the chat. - `--archived: optional boolean` True to archive, false to unarchive ### Example ```cli beeper-desktop-cli chats archive \ --chat-id '!NCdzlIaMjZUmvmvyHU:beeper.com' ``` ## Domain Types ### Chat - `chat: object { id, accountID, participants, 9 more }` - `id: string` Unique identifier of the chat across Beeper. - `accountID: string` Account ID this chat belongs to. - `participants: object { hasMore, items, total }` Chat participants information. - `hasMore: boolean` True if there are more participants than included in items. - `items: array of User` Participants returned for this chat (limited by the request; may be a subset). - `id: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional 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. - `email: optional string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `total: number` Total number of participants in the chat. - `title: string` Display title of the chat as computed by the client/server. - `type: "single" or "group"` Chat type: 'single' for direct messages, 'group' for group chats. - `"single"` - `"group"` - `unreadCount: number` Number of unread messages. - `isArchived: optional boolean` True if chat is archived. - `isMuted: optional boolean` True if chat notifications are muted. - `isPinned: optional boolean` True if chat is pinned. - `lastActivity: optional string` Timestamp of last activity. - `lastReadMessageSortKey: optional string` Last read message sortKey. - `localChatID: optional string` Local chat ID specific to this Beeper Desktop installation. # Reminders ## Create `$ beeper-desktop-cli chats:reminders create` **post** `/v1/chats/{chatID}/reminders` Set a reminder for a chat at a specific time ### Parameters - `--chat-id: string` Unique identifier of the chat. - `--reminder: object { remindAtMs, dismissOnIncomingMessage }` Reminder configuration ### Example ```cli beeper-desktop-cli chats:reminders create \ --chat-id '!NCdzlIaMjZUmvmvyHU:beeper.com' \ --reminder '{remindAtMs: 0, dismissOnIncomingMessage: true}' ``` ## Delete `$ beeper-desktop-cli chats:reminders delete` **delete** `/v1/chats/{chatID}/reminders` Clear an existing reminder from a chat ### Parameters - `--chat-id: string` Unique identifier of the chat. ### Example ```cli beeper-desktop-cli chats:reminders delete \ --chat-id '!NCdzlIaMjZUmvmvyHU:beeper.com' ``` # Messages # Reactions ## Add `$ beeper-desktop-cli chats:messages:reactions add` **post** `/v1/chats/{chatID}/messages/{messageID}/reactions` Add a reaction to an existing message. ### Parameters - `--chat-id: string` Path param: Unique identifier of the chat. - `--message-id: string` Path param: ID of the message to add a reaction to - `--reaction-key: string` Body param: Reaction key to add (emoji, shortcode, or custom emoji key) - `--transaction-id: optional string` Body param: Optional transaction ID for deduplication and local echo tracking ### Returns - `ChatMessageReactionAddResponse: object { chatID, messageID, reactionKey, 2 more }` - `chatID: string` Unique identifier of the chat. - `messageID: string` Message ID. - `reactionKey: string` Reaction key that was added - `success: true` Whether the reaction was successfully added - `true` - `transactionID: string` Transaction ID used for the reaction event ### Example ```cli beeper-desktop-cli chats:messages:reactions add \ --chat-id '!NCdzlIaMjZUmvmvyHU:beeper.com' \ --message-id messageID \ --reaction-key x ``` ## Delete `$ beeper-desktop-cli chats:messages:reactions delete` **delete** `/v1/chats/{chatID}/messages/{messageID}/reactions` Remove the authenticated user's reaction from an existing message. ### Parameters - `--chat-id: string` Path param: Unique identifier of the chat. - `--message-id: string` Path param: ID of the message to remove a reaction from - `--reaction-key: string` Query param: Reaction key to remove ### Returns - `ChatMessageReactionDeleteResponse: object { chatID, messageID, reactionKey, success }` - `chatID: string` Unique identifier of the chat. - `messageID: string` Message ID. - `reactionKey: string` Reaction key that was removed - `success: true` Whether the reaction was successfully removed - `true` ### Example ```cli beeper-desktop-cli chats:messages:reactions delete \ --chat-id '!NCdzlIaMjZUmvmvyHU:beeper.com' \ --message-id messageID \ --reaction-key x ```