# Client ## Focus `focus(ClientFocusParams**kwargs) -> FocusResponse` **post** `/v1/focus` Focus Beeper Desktop and optionally navigate to a specific chat, message, or pre-fill draft text and attachment. ### Parameters - `chat_id: Optional[str]` Optional Beeper chat ID (or local chat ID) to focus after opening the app. If omitted, only opens/focuses the app. - `draft_attachment_path: Optional[str]` Optional draft attachment path to populate in the message input field. - `draft_text: Optional[str]` Optional draft text to populate in the message input field. - `message_id: Optional[str]` Optional message ID. Jumps to that message in the chat when opening. ### Returns - `class FocusResponse: …` Response indicating successful app focus action. - `success: bool` Whether the app was successfully opened/focused. ### Example ```python from beeper_desktop_api import BeeperDesktop client = BeeperDesktop() response = client.focus() print(response.success) ``` ## Search `search(ClientSearchParams**kwargs) -> SearchResponse` **get** `/v1/search` Returns matching chats, participant name matches in groups, and the first page of messages in one call. Paginate messages via search-messages. Paginate chats via search-chats. ### Parameters - `query: str` User-typed search text. Literal word matching (non-semantic). ### Returns - `class SearchResponse: …` - `results: Results` - `chats: List[Chat]` Top chat results. - `id: str` Unique identifier of the chat across Beeper. - `account_id: str` Account ID this chat belongs to. - `participants: Participants` Chat participants information. - `has_more: bool` True if there are more participants than included in items. - `items: List[User]` Participants returned for this chat (limited by the request; may be a subset). - `id: str` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannot_message: Optional[bool]` 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[str]` Email address if known. Not guaranteed verified. - `full_name: Optional[str]` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `img_url: Optional[str]` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `is_self: Optional[bool]` True if this user represents the authenticated account's own identity. - `phone_number: Optional[str]` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: Optional[str]` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `total: int` Total number of participants in the chat. - `title: str` Display title of the chat as computed by the client/server. - `type: Literal["single", "group"]` Chat type: 'single' for direct messages, 'group' for group chats. - `"single"` - `"group"` - `unread_count: int` Number of unread messages. - `is_archived: Optional[bool]` True if chat is archived. - `is_muted: Optional[bool]` True if chat notifications are muted. - `is_pinned: Optional[bool]` True if chat is pinned. - `last_activity: Optional[datetime]` Timestamp of last activity. - `last_read_message_sort_key: Optional[str]` Last read message sortKey. - `local_chat_id: Optional[str]` Local chat ID specific to this Beeper Desktop installation. - `in_groups: List[Chat]` Top group results by participant matches. - `id: str` Unique identifier of the chat across Beeper. - `account_id: str` Account ID this chat belongs to. - `participants: Participants` Chat participants information. - `has_more: bool` True if there are more participants than included in items. - `items: List[User]` Participants returned for this chat (limited by the request; may be a subset). - `id: str` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannot_message: Optional[bool]` 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[str]` Email address if known. Not guaranteed verified. - `full_name: Optional[str]` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `img_url: Optional[str]` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `is_self: Optional[bool]` True if this user represents the authenticated account's own identity. - `phone_number: Optional[str]` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: Optional[str]` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `total: int` Total number of participants in the chat. - `title: str` Display title of the chat as computed by the client/server. - `type: Literal["single", "group"]` Chat type: 'single' for direct messages, 'group' for group chats. - `"single"` - `"group"` - `unread_count: int` Number of unread messages. - `is_archived: Optional[bool]` True if chat is archived. - `is_muted: Optional[bool]` True if chat notifications are muted. - `is_pinned: Optional[bool]` True if chat is pinned. - `last_activity: Optional[datetime]` Timestamp of last activity. - `last_read_message_sort_key: Optional[str]` Last read message sortKey. - `local_chat_id: Optional[str]` Local chat ID specific to this Beeper Desktop installation. - `messages: ResultsMessages` - `chats: Dict[str, Chat]` Map of chatID -> chat details for chats referenced in items. - `id: str` Unique identifier of the chat across Beeper. - `account_id: str` Account ID this chat belongs to. - `participants: Participants` Chat participants information. - `has_more: bool` True if there are more participants than included in items. - `items: List[User]` Participants returned for this chat (limited by the request; may be a subset). - `id: str` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannot_message: Optional[bool]` 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[str]` Email address if known. Not guaranteed verified. - `full_name: Optional[str]` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `img_url: Optional[str]` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `is_self: Optional[bool]` True if this user represents the authenticated account's own identity. - `phone_number: Optional[str]` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: Optional[str]` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `total: int` Total number of participants in the chat. - `title: str` Display title of the chat as computed by the client/server. - `type: Literal["single", "group"]` Chat type: 'single' for direct messages, 'group' for group chats. - `"single"` - `"group"` - `unread_count: int` Number of unread messages. - `is_archived: Optional[bool]` True if chat is archived. - `is_muted: Optional[bool]` True if chat notifications are muted. - `is_pinned: Optional[bool]` True if chat is pinned. - `last_activity: Optional[datetime]` Timestamp of last activity. - `last_read_message_sort_key: Optional[str]` Last read message sortKey. - `local_chat_id: Optional[str]` Local chat ID specific to this Beeper Desktop installation. - `has_more: bool` True if additional results can be fetched using the provided cursors. - `items: List[Message]` Messages matching the query and filters. - `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"` - `newest_cursor: Optional[str]` Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect. - `oldest_cursor: Optional[str]` Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect. ### Example ```python from beeper_desktop_api import BeeperDesktop client = BeeperDesktop() response = client.search( query="x", ) print(response.results) ```