Search

API Reference

Messages

Search messages

get/v0/search-messages

Search messages across chats using Beeper's message index

Query ParametersExpand Collapse

accountIDs: optional array of string

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

chatIDs: optional array of string

Limit search to specific Beeper chat IDs.

chatType: optional "group" or "single"

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

Accepts one of the following:

"group"

"single"

cursor: optional string

Opaque pagination cursor; do not inspect. Use together with 'direction'.

dateAfter: optional 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: optional 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: optional "after" or "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: optional boolean

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

includeMuted: optional 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: optional number

Maximum number of messages to return (1–500). Defaults to 20. The current implementation caps each page at 20 items even if a higher limit is requested.

minimum0

exclusiveMinimum

maximum500

mediaTypes: optional array of "any" or "video" or "image" or 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 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: optional "me" or "others" or 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:

UnionMember0 = "me" or "others"

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"

UnionMember1 = string

ReturnsExpand Collapse

chats: map[Chat { id, accountID, network, 10 more } ]

Map of chatID -> chat details for chats referenced in items.

id: string

Unique identifier of the chat (room/thread ID, same as id) across Beeper.

accountID: string

Beeper account ID this chat belongs to.

network: string

Display-only human-readable network name (e.g., 'WhatsApp', 'Messenger'). You MUST use 'accountID' to perform actions.

participants: object { hasMore, items, total }

Chat participants information.

hasMore: boolean

True if there are more participants than included in items.

items: array of User { id, cannotMessage, email, 5 more }

Participants returned for this chat (limited by the request; may be a subset).

id: string

Stable Beeper user ID. Use as the primary key when referencing a person.

cannotMessage: optional boolean

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 string

Email address if known. Not guaranteed verified.

fullName: optional string

Display name as shown in clients (e.g., 'Alice Example'). May include emojis.

imgURL: optional string

Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.

isSelf: optional boolean

True if this user represents the authenticated account's own identity.

phoneNumber: optional string

User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown.

username: optional string

Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique.

total: number

Total number of participants in the chat.

title: string

Display title of the chat as computed by the client/server.

type: "single" or "group"

Chat type: 'single' for direct messages, 'group' for group chats.

Accepts one of the following:

"single"

"group"

unreadCount: number

Number of unread messages.

isArchived: optional boolean

True if chat is archived.

isMuted: optional boolean

True if chat notifications are muted.

isPinned: optional boolean

True if chat is pinned.

lastActivity: optional string

Timestamp of last activity. Chats with more recent activity are often more important.

formatdate-time

lastReadMessageSortKey: optional number or string

Last read message sortKey (hsOrder). Used to compute 'isUnread'.

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

localChatID: optional string

Local chat ID specific to this Beeper Desktop installation.

hasMore: boolean

True if additional results can be fetched using the provided cursors.

items: array of Message { id, accountID, chatID, 10 more }

Messages matching the query and filters.

id: string

Stable message ID for cursor pagination.

accountID: string

Beeper account ID the message belongs to.

chatID: string

Beeper chat/thread/room ID.

messageID: string

Stable message ID (same as id).

senderID: string

Sender user ID.

sortKey: string or number

A unique key used to sort messages

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

timestamp: string

Message timestamp.

formatdate-time

attachments: optional array of Attachment { type, duration, fileName, 8 more }

Attachments included with this message, if any.

type: "unknown" or "img" or "video" or "audio"

Attachment type.

Accepts one of the following:

"unknown"

"img"

"video"

"audio"

duration: optional number

Duration in seconds (audio/video).

fileName: optional string

Original filename if available.

fileSize: optional number

File size in bytes if known.

isGif: optional boolean

True if the attachment is a GIF.

isSticker: optional boolean

True if the attachment is a sticker.

isVoiceNote: optional boolean

True if the attachment is a voice note.

mimeType: optional string

MIME type if known (e.g., 'image/png').

posterImg: optional 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: optional object { height, width }

Pixel dimensions of the attachment: width/height in px.

height: optional number

width: optional number

srcURL: optional 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: optional boolean

True if the authenticated user sent the message.

isUnread: optional boolean

True if the message is unread for the authenticated user. May be omitted.

reactions: optional array of Reaction { id, participantID, reactionKey, 2 more }

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: optional boolean

True if the reactionKey is an emoji.

imgURL: optional string

URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed.

senderName: optional string

Resolved sender display name (impersonator/full name/username/participant name).

text: optional string

Plain-text body if present. May include a JSON fallback with text entities for rich messages.

newestCursor: string

Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect.

oldestCursor: string

Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect.

Search messages

curl http://localhost:23373/v0/search-messages \
    -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN"

{
  "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": 449706228480,
      "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": 449706228480,
      "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

{
  "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": 449706228480,
      "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": 449706228480,
      "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"
}