--- title: Search chats - Beeper Developer Docs --- Deprecated GET/v0/search-chats - Beeper Desktop API server http\://localhost:23373/v0/search-chats Search chats by title/network or participants using Beeper Desktop’s renderer algorithm. **Use [`GET /v1/chats/search`](/desktop-api-reference/resources/chats/methods/search/index.md) instead.** ## Parameters ### 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](#tab-panel-63) - [string](#tab-panel-64) string Allowed values: single group string Allowed values: any 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\ ##### 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 ### 200 Tool executed successfully Select media typeapplication/json object **items** required Chats matching the filters. Array\ 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\ 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](#tab-panel-61) - [string](#tab-panel-62) integer string **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 Invalid request parameters Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 401 Access token is missing or invalid Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 403 Access token does not have the required scope Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 404 Resource not found Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 422 Unprocessable entity - validation error Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 429 Too many requests - rate limit exceeded Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 500 Internal server error Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string