## Search `$ beeper-desktop-cli messages search` **get** `/v1/messages/search` Search messages across chats using Beeper's message index ### Parameters - `--account-id: optional array of string` Limit search to specific account IDs. - `--chat-id: optional array of string` Limit search to specific chat IDs. - `--chat-type: optional "group" or "single"` Filter by chat type: 'group' for group chats, 'single' for 1:1 chats. - `--cursor: optional string` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `--date-after: optional string` Only include messages with timestamp strictly after this ISO 8601 datetime (e.g., '2024-07-01T00:00:00Z' or '2024-07-01T00:00:00+02:00'). - `--date-before: optional string` Only include messages with timestamp strictly before this ISO 8601 datetime (e.g., '2024-07-31T23:59:59Z' or '2024-07-31T23:59:59+02:00'). - `--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. - `--exclude-low-priority: optional boolean` Exclude messages marked Low Priority by the user. Default: true. Set to false to include all. - `--include-muted: optional boolean` Include messages in 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. - `--limit: optional number` Maximum number of messages to return. - `--media-type: optional array of "any" or "video" or "image" or 2 more` Filter messages by media types. Use ['any'] for any media type, or specify exact types like ['video', 'image']. Omit for no media filtering. - `--query: optional string` Literal word search (non-semantic). Finds messages containing these EXACT words in any order. Use single words users actually type, not concepts or phrases. Example: use "dinner" not "dinner plans", use "sick" not "health issues". If omitted, returns results filtered only by other parameters. - `--sender: optional string` Filter by sender: 'me' (messages sent by the authenticated user), 'others' (messages sent by others), or a specific user ID string (user.id). ### Returns - `SearchMessagesOutput: object { chats, hasMore, items, 2 more }` - `chats: map[Chat]` Map of chatID -> chat details for chats referenced in items. - `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. - `hasMore: boolean` True if additional results can be fetched using the provided cursors. - `items: array of Message` Messages matching the query and filters. - `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 messages search ```