Search

API Reference

Chats

Search chats

client.chats.search(ChatSearchParamsquery?, RequestOptionsoptions?): Cursor<Chat>

get/v0/search-chats

Search and filter conversations across all messaging accounts

ParametersExpand Collapse

query: ChatSearchParams

accountIDs?: Array<string>

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

cursor?: string

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

direction?: "after" | "before"

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

Accepts one of the following:

"after"

"before"

inbox?: "primary" | "low-priority" | "archive"

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

Accepts one of the following:

"primary"

"low-priority"

"archive"

includeMuted?: boolean

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.

lastActivityAfter?: string

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

formatdate-time

lastActivityBefore?: string

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

formatdate-time

limit?: number

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

minimum1

maximum200

participantQuery?: string

Search string to filter chats by participant names. When multiple words provided, ALL words must match. Searches in username, displayName, and fullName fields.

query?: string

Search string to filter chats by title. When multiple words provided, ALL words must match. Matches are case-insensitive substrings.

type?: "single" | "group" | "channel" | "any"

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

Accepts one of the following:

"single"

"group"

"channel"

"any"

unreadOnly?: boolean

Set to true to only retrieve chats that have unread messages

ReturnsExpand Collapse

Chat

HTTPTypeScript

import BeeperDesktop from '@beeper/desktop-api';

const client = new BeeperDesktop({
  accessToken: 'My Access Token',
});

// Automatically fetches more pages as needed.
for await (const chat of client.chats.search()) {
  console.log(chat.id);
}

200 example

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

Returns Examples

200 example

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