# Messages ## Search `client.messages.search(MessageSearchParamsquery?, RequestOptionsoptions?): CursorSearch` **get** `/v1/messages/search` Search messages across chats using Beeper's message index ### Parameters - `query: MessageSearchParams` - `accountIDs?: Array` Limit search to specific account IDs. - `chatIDs?: Array` Limit search to specific chat IDs. - `chatType?: "group" | "single"` Filter by chat type: 'group' for group chats, 'single' for 1:1 chats. - `"group"` - `"single"` - `cursor?: string` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `dateAfter?: 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'). - `dateBefore?: 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?: "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"` - `excludeLowPriority?: boolean | null` Exclude messages marked Low Priority by the user. Default: true. Set to false to include all. - `includeMuted?: boolean | null` 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?: number` Maximum number of messages to return. - `mediaTypes?: Array<"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?: 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?: 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 - `Message` - `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?: Array` Attachments included with this message, if any. - `type: "unknown" | "img" | "video" | "audio"` Attachment type. - `"unknown"` - `"img"` - `"video"` - `"audio"` - `id?: string` Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path. - `duration?: number` Duration in seconds (audio/video). - `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. - `mimeType?: string` MIME type if known (e.g., 'image/png'). - `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?: Size` Pixel dimensions of the attachment: width/height in px. - `height?: number` - `width?: number` - `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. - `isSender?: boolean` True if the authenticated user sent the message. - `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?: Array` 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?: boolean` True if the reactionKey is an emoji. - `imgURL?: string` URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed. - `senderName?: string` Resolved sender display name (impersonator/full name/username/participant name). - `text?: string` Plain-text body if present. May include a JSON fallback with text entities for rich messages. - `type?: "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 ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); // Automatically fetches more pages as needed. for await (const message of client.messages.search()) { console.log(message.id); } ``` ## List `client.messages.list(stringchatID, MessageListParamsquery?, RequestOptionsoptions?): CursorSortKey` **get** `/v1/chats/{chatID}/messages` List all messages in a chat with cursor-based pagination. Sorted by timestamp. ### Parameters - `chatID: string` Unique identifier of the chat. - `query: MessageListParams` - `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. - `"after"` - `"before"` ### Returns - `Message` - `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?: Array` Attachments included with this message, if any. - `type: "unknown" | "img" | "video" | "audio"` Attachment type. - `"unknown"` - `"img"` - `"video"` - `"audio"` - `id?: string` Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path. - `duration?: number` Duration in seconds (audio/video). - `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. - `mimeType?: string` MIME type if known (e.g., 'image/png'). - `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?: Size` Pixel dimensions of the attachment: width/height in px. - `height?: number` - `width?: number` - `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. - `isSender?: boolean` True if the authenticated user sent the message. - `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?: Array` 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?: boolean` True if the reactionKey is an emoji. - `imgURL?: string` URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed. - `senderName?: string` Resolved sender display name (impersonator/full name/username/participant name). - `text?: string` Plain-text body if present. May include a JSON fallback with text entities for rich messages. - `type?: "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 ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); // Automatically fetches more pages as needed. for await (const message of client.messages.list('!NCdzlIaMjZUmvmvyHU:beeper.com')) { console.log(message.id); } ``` ## Send `client.messages.send(stringchatID, MessageSendParamsbody?, RequestOptionsoptions?): 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 - `chatID: string` Unique identifier of the chat. - `body: MessageSendParams` - `attachment?: Attachment` Single attachment to send with the message - `uploadID: string` Upload ID from uploadAsset endpoint. Required to reference uploaded files. - `duration?: number` Duration in seconds (optional override of cached value) - `fileName?: string` Filename (optional override of cached value) - `mimeType?: string` MIME type (optional override of cached value) - `size?: Size` Dimensions (optional override of cached value) - `height: number` - `width: number` - `type?: "gif" | "voiceNote" | "sticker"` Special attachment type (gif, voiceNote, sticker). If omitted, auto-detected from mimeType - `"gif"` - `"voiceNote"` - `"sticker"` - `replyToMessageID?: string` Provide a message ID to send this as a reply to an existing message - `text?: string` Text content of the message you want to send. You may use markdown. ### Returns - `MessageSendResponse` - `chatID: string` Unique identifier of the chat. - `pendingMessageID: string` Pending message ID ### Example ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); const response = await client.messages.send('!NCdzlIaMjZUmvmvyHU:beeper.com'); console.log(response.pendingMessageID); ``` ## Update `client.messages.update(stringmessageID, MessageUpdateParamsparams, RequestOptionsoptions?): MessageUpdateResponse` **put** `/v1/chats/{chatID}/messages/{messageID}` Edit the text content of an existing message. Messages with attachments cannot be edited. ### Parameters - `messageID: string` - `params: MessageUpdateParams` - `chatID: string` Path param: Unique identifier of the chat. - `text: string` Body param: New text content for the message ### Returns - `MessageUpdateResponse` - `chatID: string` Unique identifier of the chat. - `messageID: string` Message ID. - `success: boolean` Whether the message was successfully edited ### Example ```typescript import BeeperDesktop from '@beeper/desktop-api'; const client = new BeeperDesktop(); const message = await client.messages.update('messageID', { chatID: '!NCdzlIaMjZUmvmvyHU:beeper.com', text: 'x', }); console.log(message.chatID); ```