# Messages ## Search `messages.search(MessageSearchParams**kwargs) -> SyncCursorSearch[Message]` **get** `/v1/messages/search` Search messages across chats using Beeper's message index ### Parameters - `account_ids: Optional[SequenceNotStr[str]]` Limit search to specific account IDs. - `chat_ids: Optional[SequenceNotStr[str]]` Limit search to specific chat IDs. - `chat_type: Optional[Literal["group", "single"]]` Filter by chat type: 'group' for group chats, 'single' for 1:1 chats. - `"group"` - `"single"` - `cursor: Optional[str]` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `date_after: Optional[Union[str, datetime]]` 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[Union[str, datetime]]` 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[Literal["after", "before"]]` Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `"after"` - `"before"` - `exclude_low_priority: Optional[bool]` Exclude messages marked Low Priority by the user. Default: true. Set to false to include all. - `include_muted: Optional[bool]` 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[int]` Maximum number of messages to return. - `media_types: Optional[List[Literal["any", "video", "image", 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. - `"any"` - `"video"` - `"image"` - `"link"` - `"file"` - `query: Optional[str]` 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[str]` Filter by sender: 'me' (messages sent by the authenticated user), 'others' (messages sent by others), or a specific user ID string (user.id). ### Returns - `class Message: …` - `id: str` Message ID. - `account_id: str` Beeper account ID the message belongs to. - `chat_id: str` Unique identifier of the chat. - `sender_id: str` Sender user ID. - `sort_key: str` A unique, sortable key used to sort messages. - `timestamp: datetime` Message timestamp. - `attachments: Optional[List[Attachment]]` Attachments included with this message, if any. - `type: Literal["unknown", "img", "video", "audio"]` Attachment type. - `"unknown"` - `"img"` - `"video"` - `"audio"` - `id: Optional[str]` Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path. - `duration: Optional[float]` Duration in seconds (audio/video). - `file_name: Optional[str]` Original filename if available. - `file_size: Optional[float]` File size in bytes if known. - `is_gif: Optional[bool]` True if the attachment is a GIF. - `is_sticker: Optional[bool]` True if the attachment is a sticker. - `is_voice_note: Optional[bool]` True if the attachment is a voice note. - `mime_type: Optional[str]` MIME type if known (e.g., 'image/png'). - `poster_img: Optional[str]` 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[Size]` Pixel dimensions of the attachment: width/height in px. - `height: Optional[float]` - `width: Optional[float]` - `src_url: Optional[str]` 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. - `is_sender: Optional[bool]` True if the authenticated user sent the message. - `is_unread: Optional[bool]` True if the message is unread for the authenticated user. May be omitted. - `linked_message_id: Optional[str]` ID of the message this is a reply to, if any. - `reactions: Optional[List[Reaction]]` Reactions to the message, if any. - `id: str` Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise. - `participant_id: str` User ID of the participant who reacted. - `reaction_key: str` The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face". - `emoji: Optional[bool]` True if the reactionKey is an emoji. - `img_url: Optional[str]` URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed. - `sender_name: Optional[str]` Resolved sender display name (impersonator/full name/username/participant name). - `text: Optional[str]` Plain-text body if present. May include a JSON fallback with text entities for rich messages. - `type: Optional[Literal["TEXT", "NOTICE", "IMAGE", 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"` ### Example ```python from beeper_desktop_api import BeeperDesktop client = BeeperDesktop() page = client.messages.search() page = page.items[0] print(page.id) ``` ## List `messages.list(strchat_id, MessageListParams**kwargs) -> SyncCursorSortKey[Message]` **get** `/v1/chats/{chatID}/messages` List all messages in a chat with cursor-based pagination. Sorted by timestamp. ### Parameters - `chat_id: str` Unique identifier of the chat. - `cursor: Optional[str]` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `direction: Optional[Literal["after", "before"]]` Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `"after"` - `"before"` ### Returns - `class Message: …` - `id: str` Message ID. - `account_id: str` Beeper account ID the message belongs to. - `chat_id: str` Unique identifier of the chat. - `sender_id: str` Sender user ID. - `sort_key: str` A unique, sortable key used to sort messages. - `timestamp: datetime` Message timestamp. - `attachments: Optional[List[Attachment]]` Attachments included with this message, if any. - `type: Literal["unknown", "img", "video", "audio"]` Attachment type. - `"unknown"` - `"img"` - `"video"` - `"audio"` - `id: Optional[str]` Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path. - `duration: Optional[float]` Duration in seconds (audio/video). - `file_name: Optional[str]` Original filename if available. - `file_size: Optional[float]` File size in bytes if known. - `is_gif: Optional[bool]` True if the attachment is a GIF. - `is_sticker: Optional[bool]` True if the attachment is a sticker. - `is_voice_note: Optional[bool]` True if the attachment is a voice note. - `mime_type: Optional[str]` MIME type if known (e.g., 'image/png'). - `poster_img: Optional[str]` 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[Size]` Pixel dimensions of the attachment: width/height in px. - `height: Optional[float]` - `width: Optional[float]` - `src_url: Optional[str]` 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. - `is_sender: Optional[bool]` True if the authenticated user sent the message. - `is_unread: Optional[bool]` True if the message is unread for the authenticated user. May be omitted. - `linked_message_id: Optional[str]` ID of the message this is a reply to, if any. - `reactions: Optional[List[Reaction]]` Reactions to the message, if any. - `id: str` Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise. - `participant_id: str` User ID of the participant who reacted. - `reaction_key: str` The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face". - `emoji: Optional[bool]` True if the reactionKey is an emoji. - `img_url: Optional[str]` URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed. - `sender_name: Optional[str]` Resolved sender display name (impersonator/full name/username/participant name). - `text: Optional[str]` Plain-text body if present. May include a JSON fallback with text entities for rich messages. - `type: Optional[Literal["TEXT", "NOTICE", "IMAGE", 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"` ### Example ```python from beeper_desktop_api import BeeperDesktop client = BeeperDesktop() page = client.messages.list( chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com", ) page = page.items[0] print(page.id) ``` ## Send `messages.send(strchat_id, MessageSendParams**kwargs) -> MessageSendResponse` **post** `/v1/chats/{chatID}/messages` Send a text message to a specific chat. Supports replying to existing messages. Returns a pending message ID. ### Parameters - `chat_id: str` Unique identifier of the chat. - `attachment: Optional[Attachment]` Single attachment to send with the message - `upload_id: str` Upload ID from uploadAsset endpoint. Required to reference uploaded files. - `duration: Optional[float]` Duration in seconds (optional override of cached value) - `file_name: Optional[str]` Filename (optional override of cached value) - `mime_type: Optional[str]` MIME type (optional override of cached value) - `size: Optional[AttachmentSize]` Dimensions (optional override of cached value) - `height: float` - `width: float` - `type: Optional[Literal["gif", "voiceNote", "sticker"]]` Special attachment type (gif, voiceNote, sticker). If omitted, auto-detected from mimeType - `"gif"` - `"voiceNote"` - `"sticker"` - `reply_to_message_id: Optional[str]` Provide a message ID to send this as a reply to an existing message - `text: Optional[str]` Text content of the message you want to send. You may use markdown. ### Returns - `class MessageSendResponse: …` - `chat_id: str` Unique identifier of the chat. - `pending_message_id: str` Pending message ID ### Example ```python from beeper_desktop_api import BeeperDesktop client = BeeperDesktop() response = client.messages.send( chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com", ) print(response.pending_message_id) ``` ## Update `messages.update(strmessage_id, MessageUpdateParams**kwargs) -> MessageUpdateResponse` **put** `/v1/chats/{chatID}/messages/{messageID}` Edit the text content of an existing message. Messages with attachments cannot be edited. ### Parameters - `chat_id: str` Unique identifier of the chat. - `message_id: str` - `text: str` New text content for the message ### Returns - `class MessageUpdateResponse: …` - `chat_id: str` Unique identifier of the chat. - `message_id: str` Message ID. - `success: bool` Whether the message was successfully edited ### Example ```python from beeper_desktop_api import BeeperDesktop client = BeeperDesktop() message = client.messages.update( message_id="messageID", chat_id="!NCdzlIaMjZUmvmvyHU:beeper.com", text="x", ) print(message.chat_id) ```