Search

API Reference

Chats

Search chats

get/v0/search-chats

Search and filter conversations across all messaging accounts

Query ParametersExpand Collapse

accountIDs: optional array of string

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

cursor: optional string

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

direction: optional "after" or "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: optional "primary" or "low-priority" or "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: optional 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: optional string

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

formatdate-time

lastActivityBefore: optional string

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

formatdate-time

limit: optional number

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

minimum1

maximum200

participantQuery: optional 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: optional string

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

type: optional "single" or "group" or "channel" or "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: optional boolean

Set to true to only retrieve chats that have unread messages

ReturnsExpand Collapse

hasMore: boolean

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

items: array of Chat

Chats matching the filters.

newestCursor: string

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

oldestCursor: string

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

HTTPTypeScript

curl http://localhost:23373/v0/search-chats \
    -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN"

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"
}