v10

latestOpenAPI 3.1.0MITraw.githubusercontent.com2026-02-242335121.2 KB

Chats

Search chats

Search chats by title/network or participants using Beeper Desktop's renderer algorithm.

get/v1/chats/search

Query parameters

cursorstring

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

Example:1725489123456|c29tZUltc2dQYWdl

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

direction'after' | 'before'

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

Example:before

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

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.

unreadOnlyboolean nullable

Set to true to only retrieve chats that have unread messages

limitinteger

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

type'single' | 'group' | 'any'

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

querystring

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

scope'titles' | 'participants'

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

lastActivityBeforestring date-time

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

lastActivityAfterstring date-time

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

accountIDsstring[]

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

[
  "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
  "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI"
]

includeMutedboolean 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.

Response

Request executed successfully

hasMoreboolean required

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

oldestCursorstring nullable required

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

newestCursorstring nullable required

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

Example response

{
  "items": [
    {
      "id": "!KPFTtZYWuERwib8T702N9IfqiCc:ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc.local-whatsapp.localhost",
      "localChatID": "1229391",
      "accountID": "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
      "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",
      "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",
      "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": "eyJ0cyI6MTc1NjY2NzEyMDY0OCwiaWQiOiIhS1BGVHRaWVd1RVJ3aWI4VDcwMjlOSWZxaUNjOmJhX0V2WURCQnNamlFSd0F5M1VPU1dxRzBMdVRWa2MiLCJzY29yZSI6MTJ9",
  "newestCursor": "eyJ0cyI6MTc1NjY2OTMwMTAwMCwiaWQiOiIhblplWDdkZDY3X1JhUG5tV0dKSWpVa1Yyc3ZFOmJhX3NYZjBhZG5icjI4Ny5sb2NhbC10ZWxlZ3JhbS5sb2NhbGhvc3QiLCJzY29yZSI6MTAuNX0="
}