Messages

Search messages

Search messages across chats using Beeper's message index

get/v1/messages/search

Query parameters

querystring

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.

Example:dinner

cursorstring

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

Example:1725489123456|c29tZUltc2dQYWdl

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.

Example:before

Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided.

chatIDsstring[]

Limit search to specific chat IDs.

[
  "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "1231073"
]

accountIDsstring[]

Limit search to specific account IDs.

[
  "whatsapp",
  "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
  "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU"
]

chatType'group' | 'single'

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

mediaTypesstring[]

Filter messages by media types. Use ['any'] for any media type, or specify exact types like ['video', 'image']. Omit for no media filtering.

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

dateAfterstring date-time

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

Example:2025-08-01T00:00:00Z

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

dateBeforestring date-time

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

Example:2025-08-31T23:59:59Z

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

limitinteger

Maximum number of messages to return.

Example:20

Maximum number of messages to return.

excludeLowPriorityboolean nullable

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

includeMutedboolean nullable

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.

Response

Request executed successfully

chatsobject required

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

hasMoreboolean required

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

oldestCursorstring nullable required

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

newestCursorstring nullable required

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

Example response

{
  "items": [
    {
      "id": "1343993",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "senderID": "@adamvy:local-signal.localhost",
      "senderName": "Adam Van Ymeren",
      "timestamp": "2025-08-28T11:04:29.621Z",
      "sortKey": "aaaa1",
      "text": "Hey, can we reschedule our meeting to 3pm?",
      "isSender": false,
      "isUnread": false
    },
    {
      "id": "1343994",
      "chatID": "!telegram_nick:local-telegram.localhost",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "senderID": "@nick:local-telegram.localhost",
      "senderName": "Nick Mills-Barrett",
      "timestamp": "2025-08-28T14:22:15.432Z",
      "sortKey": "aaaa2",
      "text": "The deployment is complete, everything looks good",
      "isSender": false,
      "isUnread": true
    }
  ],
  "chats": {
    "!signal_adamvy:local-signal.localhost": {
      "id": "!signal_adamvy:local-signal.localhost",
      "localChatID": "1229720",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "network": "Signal",
      "title": "Adam Van Ymeren",
      "type": "single",
      "participants": {
        "items": [
          {
            "id": "@adamvy:local-signal.localhost",
            "fullName": "Adam Van Ymeren",
            "cannotMessage": false,
            "isSelf": false
          },
          {
            "id": "@batuhan:local-signal.localhost",
            "fullName": "Batuhan İçöz",
            "cannotMessage": false,
            "isSelf": true
          }
        ],
        "hasMore": false,
        "total": 2
      },
      "lastActivity": "2025-08-31T17:38:20.393Z",
      "unreadCount": 0,
      "isArchived": false,
      "isMuted": false,
      "isPinned": true
    },
    "!telegram_nick:local-telegram.localhost": {
      "id": "!telegram_nick:local-telegram.localhost",
      "localChatID": "1229721",
      "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
      "network": "Telegram",
      "title": "Nick Mills-Barrett",
      "type": "single",
      "participants": {
        "items": [
          {
            "id": "@nick:local-telegram.localhost",
            "username": "nick",
            "fullName": "Nick Mills-Barrett",
            "cannotMessage": false,
            "isSelf": false
          },
          {
            "id": "@batuhan:local-telegram.localhost",
            "username": "batuhan",
            "fullName": "Batuhan İçöz",
            "cannotMessage": false,
            "isSelf": true
          }
        ],
        "hasMore": false,
        "total": 2
      },
      "lastActivity": "2025-08-31T16:45:10.123Z",
      "unreadCount": 2,
      "isArchived": false,
      "isMuted": true,
      "isPinned": false
    }
  },
  "hasMore": true,
  "oldestCursor": "1756379069621",
  "newestCursor": null
}

Search messages

Query parameters

Response

Example response

Changes