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

Search chats

Deprecated
GET
/v0/search-chats

Search chats by title/network or participants using Beeper Desktop’s renderer algorithm. Use GET /v1/chats/search instead.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
cursor

Pagination cursor from previous response. Use with direction to navigate results

string
Example
eyJvZmZzZXQiOjE3MTk5OTk5OTl9

Pagination cursor from previous response. Use with direction to navigate results

direction

Pagination direction: “after” for newer page, “before” for older page. Defaults to “before” when only cursor is provided.

string
Allowed values: after before

Pagination direction: “after” for newer page, “before” for older page. Defaults to “before” when only cursor is provided.

inbox

Filter by inbox type: “primary” (non-archived, non-low-priority), “low-priority”, or “archive”. If not specified, shows all chats.

string
Allowed values: primary low-priority archive

Filter by inbox type: “primary” (non-archived, non-low-priority), “low-priority”, or “archive”. If not specified, shows all chats.

unreadOnly

Set to true to only retrieve chats that have unread messages

boolean
nullable

Set to true to only retrieve chats that have unread messages

limit

Set the maximum number of chats to retrieve. Valid range: 1-200, default is 50

integer
default: 50 >= 1 <= 200

Set the maximum number of chats to retrieve. Valid range: 1-200, default is 50

type
Any of:
string
Allowed values: single group

Specify the type of chats to retrieve: use “single” for direct messages, “group” for group chats, or “any” to get all types

query

Literal token search (non-semantic). Use single words users type (e.g., “dinner”). When multiple words provided, ALL must match. Case-insensitive.

string
>= 1 characters

Literal token search (non-semantic). Use single words users type (e.g., “dinner”). When multiple words provided, ALL must match. Case-insensitive.

scope

Search scope: ‘titles’ matches title + network; ‘participants’ matches participant names.

string
default: titles
Allowed values: titles participants

Search scope: ‘titles’ matches title + network; ‘participants’ matches participant names.

lastActivityBefore

Provide an ISO datetime string to only retrieve chats with last activity before this time

string format: date-time

Provide an ISO datetime string to only retrieve chats with last activity before this time

lastActivityAfter

Provide an ISO datetime string to only retrieve chats with last activity after this time

string format: date-time

Provide an ISO datetime string to only retrieve chats with last activity after this time

accountIDs

Provide an array of account IDs to filter chats from specific messaging accounts only

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

Provide an array of account IDs to filter chats from specific messaging accounts only

includeMuted

Include 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 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

Chats matching the filters.

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
}
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
newestCursor
required

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

string
nullable
Example
{
  "items": [
    {
      "id": "!KPFTtZYWuERwib8T702N9IfqiCc:ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc.local-whatsapp.localhost",
      "localChatID": "1229391",
      "accountID": "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
      "network": "WhatsApp",
      "title": "Kishan Bagaria",
      "type": "single",
      "participants": {
        "items": [
          {
            "id": "@kishanbagaria:local-whatsapp.localhost",
            "phoneNumber": "+15551112222",
            "fullName": "Kishan Bagaria",
            "cannotMessage": false,
            "isSelf": false
          }
        ],
        "hasMore": false,
        "total": 2
      },
      "lastActivity": "2025-08-31T19:41:41.000Z",
      "unreadCount": 3,
      "lastReadMessageSortKey": 449706228480,
      "isArchived": false,
      "isMuted": false,
      "isPinned": true
    },
    {
      "id": "!nZeX7dh67_RaPnmWGJIjUkV2svE:ba_sXf0adnbr287.local-telegram.localhost",
      "localChatID": "1229078",
      "accountID": "local-telegram_ba_sXf0adnbr287_pRup35Tgl-lsIg",
      "network": "Telegram",
      "title": "Brad Murray",
      "type": "single",
      "participants": {
        "items": [
          {
            "id": "@bradmurray:local-telegram.localhost",
            "phoneNumber": "+15553334444",
            "fullName": "Brad Murray",
            "cannotMessage": false,
            "isSelf": false
          }
        ],
        "hasMore": false,
        "total": 2
      },
      "lastActivity": "2025-08-31T18:05:20.648Z",
      "unreadCount": 0,
      "lastReadMessageSortKey": 449706782720,
      "isArchived": true,
      "isMuted": false,
      "isPinned": false
    },
    {
      "id": "!twitter_dm_photomatt:local-twitter.localhost",
      "localChatID": "1228956",
      "accountID": "local-twitter_ba_gUU1IHNGo_CsTZLp0vDFUYk9EuE",
      "network": "Twitter/X",
      "title": "Matt Mullenweg",
      "type": "single",
      "participants": {
        "items": [
          {
            "id": "@photomatt:local-twitter.localhost",
            "username": "photomatt",
            "fullName": "Matt Mullenweg",
            "cannotMessage": false,
            "isSelf": false
          }
        ],
        "hasMore": false,
        "total": 2
      },
      "lastActivity": "2025-08-31T12:30:15.123Z",
      "unreadCount": 1,
      "lastReadMessageSortKey": 449705982340,
      "isArchived": false,
      "isMuted": true,
      "isPinned": false
    }
  ],
  "hasMore": true,
  "oldestCursor": "1756667120648",
  "newestCursor": "1756669301000"
}

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