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

Search

Deprecated
GET
/v0/search

Returns matching chats, participant name matches in groups, and the first page of messages in one call. Paginate messages via search-messages. Paginate chats via search-chats. Uses the same sorting as the chat search in the app. Use GET /v1/search instead.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
query
required

User-typed search text. Literal word matching (NOT semantic).

string
>= 1 characters

User-typed search text. Literal word matching (NOT semantic).

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Tool executed successfully

object
results
required
object
chats
required

Top chat results.

Array<object>
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
}
in_groups
required

Top group results by participant matches.

Array<object>
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
}
messages
required
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