Search messages

messages.search() -> SyncCursorSearch[Message]

GET/v1/messages/search

Search messages across chats using Beeper's message index

ParametersExpand Collapse

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.

Accepts one of the following:

"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').

formatdate-time

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').

formatdate-time

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.

Accepts one of the following:

"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.

minimum0

exclusiveMinimum

maximum20

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.

Accepts one of the following:

"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.

minLength0

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).

ReturnsExpand Collapse

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.

formatdate-time

attachments: Optional[List[Attachment]]

Attachments included with this message, if any.

type: Literal["unknown", "img", "video", "audio"]

Attachment type.

Accepts one of the following:

"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.

Accepts one of the following:

"TEXT"

"NOTICE"

"IMAGE"

"VIDEO"

"VOICE"

"AUDIO"

"FILE"

"STICKER"

"LOCATION"

"REACTION"

Search messages

from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
page = client.messages.search()
page = page.items[0]
print(page.id)

{
  "chats": {
    "!signal_adamvy:local-signal.localhost": {
      "id": "!signal_adamvy:local-signal.localhost",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@adamvy:local-signal.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Adam Van Ymeren",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "username"
          },
          {
            "id": "@batuhan:local-signal.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "username"
          }
        ],
        "total": 2
      },
      "title": "Adam Van Ymeren",
      "type": "single",
      "unreadCount": 0,
      "isArchived": false,
      "isMuted": false,
      "isPinned": true,
      "lastActivity": "2025-08-31T17:38:20.393Z",
      "lastReadMessageSortKey": "449706228480",
      "localChatID": "1229720"
    },
    "!telegram_nick:local-telegram.localhost": {
      "id": "!telegram_nick:local-telegram.localhost",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@nick:local-telegram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Nick Mills-Barrett",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "nick"
          },
          {
            "id": "@batuhan:local-telegram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "batuhan"
          }
        ],
        "total": 2
      },
      "title": "Nick Mills-Barrett",
      "type": "single",
      "unreadCount": 2,
      "isArchived": false,
      "isMuted": true,
      "isPinned": false,
      "lastActivity": "2025-08-31T16:45:10.123Z",
      "lastReadMessageSortKey": "449706228480",
      "localChatID": "1229721"
    }
  },
  "hasMore": true,
  "items": [
    {
      "id": "1343993",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "senderID": "@adamvy:local-signal.localhost",
      "sortKey": "aaaa1",
      "timestamp": "2025-08-28T11:04:29.621Z",
      "attachments": [
        {
          "type": "unknown",
          "id": "id",
          "duration": 0,
          "fileName": "fileName",
          "fileSize": 0,
          "isGif": true,
          "isSticker": true,
          "isVoiceNote": true,
          "mimeType": "mimeType",
          "posterImg": "posterImg",
          "size": {
            "height": 0,
            "width": 0
          },
          "srcURL": "srcURL"
        }
      ],
      "isSender": false,
      "isUnread": false,
      "linkedMessageID": "linkedMessageID",
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Adam Van Ymeren",
      "text": "Hey, can we reschedule our meeting to 3pm?",
      "type": "TEXT"
    },
    {
      "id": "1343994",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "chatID": "!telegram_nick:local-telegram.localhost",
      "senderID": "@nick:local-telegram.localhost",
      "sortKey": "aaaa2",
      "timestamp": "2025-08-28T14:22:15.432Z",
      "attachments": [
        {
          "type": "unknown",
          "id": "id",
          "duration": 0,
          "fileName": "fileName",
          "fileSize": 0,
          "isGif": true,
          "isSticker": true,
          "isVoiceNote": true,
          "mimeType": "mimeType",
          "posterImg": "posterImg",
          "size": {
            "height": 0,
            "width": 0
          },
          "srcURL": "srcURL"
        }
      ],
      "isSender": false,
      "isUnread": true,
      "linkedMessageID": "linkedMessageID",
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Nick Mills-Barrett",
      "text": "The deployment is complete, everything looks good",
      "type": "TEXT"
    }
  ],
  "newestCursor": null,
  "oldestCursor": "1756379069621"
}

Returns Examples

{
  "chats": {
    "!signal_adamvy:local-signal.localhost": {
      "id": "!signal_adamvy:local-signal.localhost",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@adamvy:local-signal.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Adam Van Ymeren",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "username"
          },
          {
            "id": "@batuhan:local-signal.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "username"
          }
        ],
        "total": 2
      },
      "title": "Adam Van Ymeren",
      "type": "single",
      "unreadCount": 0,
      "isArchived": false,
      "isMuted": false,
      "isPinned": true,
      "lastActivity": "2025-08-31T17:38:20.393Z",
      "lastReadMessageSortKey": "449706228480",
      "localChatID": "1229720"
    },
    "!telegram_nick:local-telegram.localhost": {
      "id": "!telegram_nick:local-telegram.localhost",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "participants": {
        "hasMore": false,
        "items": [
          {
            "id": "@nick:local-telegram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Nick Mills-Barrett",
            "imgURL": "imgURL",
            "isSelf": false,
            "phoneNumber": "phoneNumber",
            "username": "nick"
          },
          {
            "id": "@batuhan:local-telegram.localhost",
            "cannotMessage": false,
            "email": "email",
            "fullName": "Batuhan İçöz",
            "imgURL": "imgURL",
            "isSelf": true,
            "phoneNumber": "phoneNumber",
            "username": "batuhan"
          }
        ],
        "total": 2
      },
      "title": "Nick Mills-Barrett",
      "type": "single",
      "unreadCount": 2,
      "isArchived": false,
      "isMuted": true,
      "isPinned": false,
      "lastActivity": "2025-08-31T16:45:10.123Z",
      "lastReadMessageSortKey": "449706228480",
      "localChatID": "1229721"
    }
  },
  "hasMore": true,
  "items": [
    {
      "id": "1343993",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "senderID": "@adamvy:local-signal.localhost",
      "sortKey": "aaaa1",
      "timestamp": "2025-08-28T11:04:29.621Z",
      "attachments": [
        {
          "type": "unknown",
          "id": "id",
          "duration": 0,
          "fileName": "fileName",
          "fileSize": 0,
          "isGif": true,
          "isSticker": true,
          "isVoiceNote": true,
          "mimeType": "mimeType",
          "posterImg": "posterImg",
          "size": {
            "height": 0,
            "width": 0
          },
          "srcURL": "srcURL"
        }
      ],
      "isSender": false,
      "isUnread": false,
      "linkedMessageID": "linkedMessageID",
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Adam Van Ymeren",
      "text": "Hey, can we reschedule our meeting to 3pm?",
      "type": "TEXT"
    },
    {
      "id": "1343994",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "chatID": "!telegram_nick:local-telegram.localhost",
      "senderID": "@nick:local-telegram.localhost",
      "sortKey": "aaaa2",
      "timestamp": "2025-08-28T14:22:15.432Z",
      "attachments": [
        {
          "type": "unknown",
          "id": "id",
          "duration": 0,
          "fileName": "fileName",
          "fileSize": 0,
          "isGif": true,
          "isSticker": true,
          "isVoiceNote": true,
          "mimeType": "mimeType",
          "posterImg": "posterImg",
          "size": {
            "height": 0,
            "width": 0
          },
          "srcURL": "srcURL"
        }
      ],
      "isSender": false,
      "isUnread": true,
      "linkedMessageID": "linkedMessageID",
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Nick Mills-Barrett",
      "text": "The deployment is complete, everything looks good",
      "type": "TEXT"
    }
  ],
  "newestCursor": null,
  "oldestCursor": "1756379069621"
}