## Search

`client.messages.search(MessageSearchParamsquery?, RequestOptionsoptions?): CursorSearch<Message>`

**get** `/v1/messages/search`

Search messages across chats using Beeper's message index

### Parameters

- `query: MessageSearchParams`

  - `accountIDs?: Array<string>`

    Limit search to specific account IDs.

  - `chatIDs?: Array<string>`

    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<Attachment>`

    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<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?: 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);
}
```