Search

API Reference

Messages

Search messages

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

get/v0/search-messages

Search messages across chats using Beeper's message index

ParametersExpand Collapse

query: MessageSearchParams

accountIDs?: Array<string>

Limit search to specific Beeper account IDs (bridge instances).

chatIDs?: Array<string>

Limit search to specific Beeper chat IDs.

chatType?: "group" | "single"

Filter by chat type: 'group' for group chats, 'single' for 1:1 chats.

Accepts one of the following:

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

formatdate-time

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

formatdate-time

direction?: "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"

excludeLowPriority?: boolean

Exclude messages marked Low Priority by the user. Default: true. Set to false to include all.

includeMuted?: boolean

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 (1–500). Defaults to 50.

minimum0

exclusiveMinimum

maximum500

onlyWithFile?: boolean

Only return messages that contain file attachments.

onlyWithImage?: boolean

Only return messages that contain image attachments.

onlyWithLink?: boolean

Only return messages that contain link attachments.

onlyWithMedia?: boolean

Only return messages that contain any type of media attachment.

onlyWithVideo?: boolean

Only return messages that contain video attachments.

query?: string

Literal word search (NOT 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?: "me" | "others" | (string & {})

Filter by sender: 'me' (messages sent by the authenticated user), 'others' (messages sent by others), or a specific user ID string (user.id).

Accepts one of the following:

"me" | "others"

(string & {})

ReturnsExpand Collapse

Message

HTTPTypeScript

import BeeperDesktop from '@beeper/desktop-api';

const client = new BeeperDesktop({
  accessToken: 'My Access Token',
});

// Automatically fetches more pages as needed.
for await (const message of client.messages.search()) {
  console.log(message.id);
}

200 example

{
  "chats": {
    "!signal_adamvy:local-signal.localhost": {
      "id": "!signal_adamvy:local-signal.localhost",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "network": "Signal",
      "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": 0,
      "localChatID": "1229720"
    },
    "!telegram_nick:local-telegram.localhost": {
      "id": "!telegram_nick:local-telegram.localhost",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "network": "Telegram",
      "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": 0,
      "localChatID": "1229721"
    }
  },
  "hasMore": true,
  "items": [
    {
      "id": "1343993",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "messageID": "1343993",
      "senderID": "@adamvy:local-signal.localhost",
      "sortKey": 821744079,
      "timestamp": "2025-08-28T11:04:29.621Z",
      "attachments": [
        {
          "type": "unknown",
          "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,
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Adam Van Ymeren",
      "text": "Hey, can we reschedule our meeting to 3pm?"
    },
    {
      "id": "1343994",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "chatID": "!telegram_nick:local-telegram.localhost",
      "messageID": "1343994",
      "senderID": "@nick:local-telegram.localhost",
      "sortKey": 821755234,
      "timestamp": "2025-08-28T14:22:15.432Z",
      "attachments": [
        {
          "type": "unknown",
          "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,
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Nick Mills-Barrett",
      "text": "The deployment is complete, everything looks good"
    }
  ],
  "newestCursor": null,
  "oldestCursor": "1756379069621"
}

Returns Examples

200 example

{
  "chats": {
    "!signal_adamvy:local-signal.localhost": {
      "id": "!signal_adamvy:local-signal.localhost",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "network": "Signal",
      "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": 0,
      "localChatID": "1229720"
    },
    "!telegram_nick:local-telegram.localhost": {
      "id": "!telegram_nick:local-telegram.localhost",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "network": "Telegram",
      "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": 0,
      "localChatID": "1229721"
    }
  },
  "hasMore": true,
  "items": [
    {
      "id": "1343993",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "messageID": "1343993",
      "senderID": "@adamvy:local-signal.localhost",
      "sortKey": 821744079,
      "timestamp": "2025-08-28T11:04:29.621Z",
      "attachments": [
        {
          "type": "unknown",
          "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,
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Adam Van Ymeren",
      "text": "Hey, can we reschedule our meeting to 3pm?"
    },
    {
      "id": "1343994",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "chatID": "!telegram_nick:local-telegram.localhost",
      "messageID": "1343994",
      "senderID": "@nick:local-telegram.localhost",
      "sortKey": 821755234,
      "timestamp": "2025-08-28T14:22:15.432Z",
      "attachments": [
        {
          "type": "unknown",
          "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,
      "reactions": [
        {
          "id": "id",
          "participantID": "participantID",
          "reactionKey": "reactionKey",
          "emoji": true,
          "imgURL": "imgURL"
        }
      ],
      "senderName": "Nick Mills-Barrett",
      "text": "The deployment is complete, everything looks good"
    }
  ],
  "newestCursor": null,
  "oldestCursor": "1756379069621"
}