Skip to content
Beeper Developer Docs
  • Auto
  • Light
  • Dark
Download Beeper

Search messages

Deprecated
GET
/v0/search-messages

Search messages across chats using Beeper’s message index. Use GET /v1/messages/search instead.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
query

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.

string
0
Example
dinner

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.

cursor

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

string
Example
1725489123456|c29tZUltc2dQYWdl

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

direction

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

string
Allowed values: after before
Example
before

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

chatIDs

Limit search to specific Beeper chat IDs.

Array<string>
Example
[
  "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "1231073"
]

Limit search to specific Beeper chat IDs.

accountIDs

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

Array<string>
Example
[
  "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
  "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU"
]

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

chatType

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

string
Allowed values: group single

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

mediaTypes

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

Array<string>
Allowed values: any video image link file

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

sender
Any of:
string
Allowed values: me

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

dateAfter

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

string format: date-time
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’).

dateBefore

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

string format: date-time
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’).

limit

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.

integer
default: 20 <= 500
Example
20

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.

excludeLowPriority

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

boolean
default: true nullable

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

includeMuted

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.

boolean
default: true 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.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Tool executed successfully

object
items
required

Messages matching the query and filters.

Array<object>
object
id
required

Stable message ID for cursor pagination.

string
Example
1343993
messageID
required

Stable message ID (same as id).

string
Example
1343993
chatID
required

Beeper chat/thread/room ID.

string
Example
!NCdzlIaMjZUmvmvyHU:beeper.com
accountID
required

Beeper account ID the message belongs to.

string
senderID
required

Sender user ID.

string
Example
@kishanbagaria:local-whatsapp.localhost
senderName

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

string
timestamp
required

Message timestamp.

string format: date-time
Example
2025-08-31T23:30:12.520Z
sortKey
required
Any of:
string
text

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

string
isSender

True if the authenticated user sent the message.

boolean
attachments

Attachments included with this message, if any.

Array<object>
object
type
required

Attachment type.

string
Allowed values: unknown img video audio
srcURL

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.

string
mimeType

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

string
fileName

Original filename if available.

string
fileSize

File size in bytes if known.

number
isGif

True if the attachment is a GIF.

boolean
isSticker

True if the attachment is a sticker.

boolean
isVoiceNote

True if the attachment is a voice note.

boolean
duration

Duration in seconds (audio/video).

number
posterImg

Preview image URL for video attachments (poster frame). May be temporary or local-only to this device; download promptly if durable access is needed.

string
size

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

object
width
number
height
number
isUnread

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

boolean
reactions

Reactions to the message, if any.

Array<object>
object
id
required

Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise.

string
reactionKey
required

The reaction key: an emoji (😄), a network-specific key, or a shortcode like “smiling-face”.

string
imgURL

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

string
participantID
required

User ID of the participant who reacted.

string
emoji

True if the reactionKey is an emoji.

boolean
Example
{
  "id": "1343993",
  "messageID": "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": 821744079,
  "text": "Hey, can we reschedule our meeting to 3pm?",
  "isSender": false,
  "isUnread": false
}
chats
required

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

object
key
additional properties
object
id
required

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

string
Example
!NCdzlIaMjZUmvmvyHU:beeper.com
localChatID

Local chat ID specific to this Beeper Desktop installation.

string
nullable
accountID
required

Beeper account ID this chat belongs to.

string
network
required

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

string
Example
WhatsApp
title
required

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

string
type
required

Chat type: ‘single’ for direct messages, ‘group’ for group chats.

string
Allowed values: single group
participants
required

Chat participants information.

object
items
required

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

Array<object>

A person on or reachable through Beeper. Values are best-effort and can vary by network.

object
id
required

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

string
username

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

string
phoneNumber

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

string
email

Email address if known. Not guaranteed verified.

string
fullName

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

string
imgURL

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

string
cannotMessage

True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

boolean
isSelf

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

boolean
hasMore
required

True if there are more participants than included in items.

boolean
total
required

Total number of participants in the chat.

integer
lastActivity

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

string format: date-time
Example
2025-08-31T23:30:12.520Z
unreadCount
required

Number of unread messages.

integer
Example
3
lastReadMessageSortKey
Any of:
integer
isArchived

True if chat is archived.

boolean
isMuted

True if chat notifications are muted.

boolean
isPinned

True if chat is pinned.

boolean
Example
{
  "id": "!instagram_mattwondra:local-instagram.localhost",
  "localChatID": "1229391",
  "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
  "network": "Instagram",
  "title": "Matt Wondra",
  "type": "single",
  "participants": {
    "items": [
      {
        "id": "@mattwondra:local-instagram.localhost",
        "username": "mattwondra",
        "fullName": "Matt Wondra",
        "cannotMessage": false,
        "isSelf": false
      },
      {
        "id": "@batuhan:local-instagram.localhost",
        "username": "batuhan",
        "fullName": "Batuhan İçöz",
        "cannotMessage": false,
        "isSelf": true
      }
    ],
    "hasMore": false,
    "total": 2
  },
  "lastActivity": "2025-08-31T19:41:41.000Z",
  "unreadCount": 0,
  "lastReadMessageSortKey": 449706228480,
  "isArchived": false,
  "isMuted": false,
  "isPinned": false
}
hasMore
required

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

boolean
oldestCursor
required

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

string
nullable
Example
1725489123456|c29tZUltc2dQYWdl
newestCursor
required

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

string
nullable
Example
1725489123456|c29tZUltc2dQYWdl
Example
{
  "items": [
    {
      "id": "1343993",
      "messageID": "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": 821744079,
      "text": "Hey, can we reschedule our meeting to 3pm?",
      "isSender": false,
      "isUnread": false
    },
    {
      "id": "1343994",
      "messageID": "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": 821755234,
      "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
}

400

Section titled “400 ”

Invalid request parameters

object
error
required

Error message

string
code

Error code

string
details

Additional error details

object
key
additional properties
string

401

Section titled “401 ”

Access token is missing or invalid

object
error
required

Error message

string
code

Error code

string
details

Additional error details

object
key
additional properties
string

403

Section titled “403 ”

Access token does not have the required scope

object
error
required

Error message

string
code

Error code

string
details

Additional error details

object
key
additional properties
string

404

Section titled “404 ”

Resource not found

object
error
required

Error message

string
code

Error code

string
details

Additional error details

object
key
additional properties
string

422

Section titled “422 ”

Unprocessable entity - validation error

object
error
required

Error message

string
code

Error code

string
details

Additional error details

object
key
additional properties
string

429

Section titled “429 ”

Too many requests - rate limit exceeded

object
error
required

Error message

string
code

Error code

string
details

Additional error details

object
key
additional properties
string

500

Section titled “500 ”

Internal server error

object
error
required

Error message

string
code

Error code

string
details

Additional error details

object
key
additional properties
string