--- title: Search messages - Beeper Developer Docs --- Deprecated GET/v0/search-messages - Beeper Desktop API server http\://localhost:23373/v0/search-messages Search messages across chats using Beeper’s message index. **Use [`GET /v1/messages/search`](/desktop-api-reference/resources/messages/methods/search/index.md) instead.** ## Parameters ### Query Parameters **query** Literal word search (NOT semantic). Finds messages containing these EXACT words in any order. Use single words users actually type, not concepts or phrases. Example: use “dinner” not “dinner plans”, use “sick” not “health issues”. If omitted, returns results filtered only by other parameters. string 0 ##### Example ``` dinner ``` Literal word search (NOT semantic). Finds messages containing these EXACT words in any order. Use single words users actually type, not concepts or phrases. Example: use “dinner” not “dinner plans”, use “sick” not “health issues”. If omitted, returns results filtered only by other parameters. **cursor** Opaque pagination cursor; do not inspect. Use together with ‘direction’. string ##### Example ``` 1725489123456|c29tZUltc2dQYWdl ``` Opaque pagination cursor; do not inspect. Use together with ‘direction’. **direction** Pagination direction used with ‘cursor’: ‘before’ fetches older results, ‘after’ fetches newer results. Defaults to ‘before’ when only ‘cursor’ is provided. string Allowed values: after before ##### Example ``` before ``` Pagination direction used with ‘cursor’: ‘before’ fetches older results, ‘after’ fetches newer results. Defaults to ‘before’ when only ‘cursor’ is provided. **chatIDs** Limit search to specific Beeper chat IDs. Array\ ##### Example ``` [ "!NCdzlIaMjZUmvmvyHU:beeper.com", "1231073" ] ``` Limit search to specific Beeper chat IDs. **accountIDs** Limit search to specific Beeper account IDs (bridge instances). Array\ ##### Example ``` [ "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc", "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU" ] ``` Limit search to specific Beeper account IDs (bridge instances). **chatType** Filter by chat type: ‘group’ for group chats, ‘single’ for 1:1 chats. string Allowed values: group single Filter by chat type: ‘group’ for group chats, ‘single’ for 1:1 chats. **mediaTypes** Filter messages by media types. Use \[‘any’] for any media type, or specify exact types like \[‘video’, ‘image’]. Omit for no media filtering. Array\ Allowed values: any video image link file Filter messages by media types. Use \[‘any’] for any media type, or specify exact types like \[‘video’, ‘image’]. Omit for no media filtering. **sender** Any of: - [string](#tab-panel-69) - [string](#tab-panel-70) - [string](#tab-panel-71) string Allowed values: me string Allowed values: others string Filter by sender: ‘me’ (messages sent by the authenticated user), ‘others’ (messages sent by others), or a specific user ID string (user.id). **dateAfter** Only include messages with timestamp strictly after this ISO 8601 datetime (e.g., ‘2024-07-01T00:00:00Z’ or ‘2024-07-01T00:00:00+02:00’). string format: date-time ##### Example ``` 2025-08-01T00:00:00Z ``` Only include messages with timestamp strictly after this ISO 8601 datetime (e.g., ‘2024-07-01T00:00:00Z’ or ‘2024-07-01T00:00:00+02:00’). **dateBefore** Only include messages with timestamp strictly before this ISO 8601 datetime (e.g., ‘2024-07-31T23:59:59Z’ or ‘2024-07-31T23:59:59+02:00’). string format: date-time ##### Example ``` 2025-08-31T23:59:59Z ``` Only include messages with timestamp strictly before this ISO 8601 datetime (e.g., ‘2024-07-31T23:59:59Z’ or ‘2024-07-31T23:59:59+02:00’). **limit** Maximum number of messages to return (1–500). Defaults to 20. The current implementation caps each page at 20 items even if a higher limit is requested. integer default: 20 <= 500 ##### Example ``` 20 ``` Maximum number of messages to return (1–500). Defaults to 20. The current implementation caps each page at 20 items even if a higher limit is requested. **excludeLowPriority** Exclude messages marked Low Priority by the user. Default: true. Set to false to include all. boolean default: true nullable Exclude messages marked Low Priority by the user. Default: true. Set to false to include all. **includeMuted** Include messages in 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 messages in 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 Messages matching the query and filters. Array\ object **id** required Stable message ID for cursor pagination. string ##### Example ``` 1343993 ``` **messageID** required Stable message ID (same as id). string ##### Example ``` 1343993 ``` **chatID** required Beeper chat/thread/room ID. string ##### Example ``` !NCdzlIaMjZUmvmvyHU:beeper.com ``` **accountID** required Beeper account ID the message belongs to. string **senderID** required Sender user ID. string ##### Example ``` @kishanbagaria:local-whatsapp.localhost ``` **senderName** Resolved sender display name (impersonator/full name/username/participant name). string **timestamp** required Message timestamp. string format: date-time ##### Example ``` 2025-08-31T23:30:12.520Z ``` **sortKey** required Any of: - [string](#tab-panel-65) - [number](#tab-panel-66) string number **text** Plain-text body if present. May include a JSON fallback with text entities for rich messages. string **isSender** True if the authenticated user sent the message. boolean **attachments** Attachments included with this message, if any. Array\ object **type** required Attachment type. string Allowed values: unknown img video audio **srcURL** Public URL or local file path to fetch the asset. May be temporary or local-only to this device; download promptly if durable access is needed. string **mimeType** MIME type if known (e.g., ‘image/png’). string **fileName** Original filename if available. string **fileSize** File size in bytes if known. number **isGif** True if the attachment is a GIF. boolean **isSticker** True if the attachment is a sticker. boolean **isVoiceNote** True if the attachment is a voice note. boolean **duration** Duration in seconds (audio/video). number **posterImg** Preview image URL for video attachments (poster frame). May be temporary or local-only to this device; download promptly if durable access is needed. string **size** Pixel dimensions of the attachment: width/height in px. object **width** number **height** number **isUnread** True if the message is unread for the authenticated user. May be omitted. boolean **reactions** Reactions to the message, if any. Array\ object **id** required Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise. string **reactionKey** required The reaction key: an emoji (😄), a network-specific key, or a shortcode like “smiling-face”. string **imgURL** URL to the reaction’s image. May be temporary or local-only to this device; download promptly if durable access is needed. string **participantID** required User ID of the participant who reacted. string **emoji** True if the reactionKey is an emoji. boolean ##### Example ``` { "id": "1343993", "messageID": "1343993", "chatID": "!signal_adamvy:local-signal.localhost", "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY", "senderID": "@adamvy:local-signal.localhost", "senderName": "Adam Van Ymeren", "timestamp": "2025-08-28T11:04:29.621Z", "sortKey": 821744079, "text": "Hey, can we reschedule our meeting to 3pm?", "isSender": false, "isUnread": false } ``` **chats** required Map of chatID -> chat details for chats referenced in items. object ***key*** additional properties 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-67) - [string](#tab-panel-68) 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 ##### Example ``` 1725489123456|c29tZUltc2dQYWdl ``` **newestCursor** required Cursor for fetching newer results (use with direction=‘after’). Opaque string; do not inspect. string nullable ##### Example ``` 1725489123456|c29tZUltc2dQYWdl ``` ##### Example ``` { "items": [ { "id": "1343993", "messageID": "1343993", "chatID": "!signal_adamvy:local-signal.localhost", "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY", "senderID": "@adamvy:local-signal.localhost", "senderName": "Adam Van Ymeren", "timestamp": "2025-08-28T11:04:29.621Z", "sortKey": 821744079, "text": "Hey, can we reschedule our meeting to 3pm?", "isSender": false, "isUnread": false }, { "id": "1343994", "messageID": "1343994", "chatID": "!telegram_nick:local-telegram.localhost", "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI", "senderID": "@nick:local-telegram.localhost", "senderName": "Nick Mills-Barrett", "timestamp": "2025-08-28T14:22:15.432Z", "sortKey": 821755234, "text": "The deployment is complete, everything looks good", "isSender": false, "isUnread": true } ], "chats": { "!signal_adamvy:local-signal.localhost": { "id": "!signal_adamvy:local-signal.localhost", "localChatID": "1229720", "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY", "network": "Signal", "title": "Adam Van Ymeren", "type": "single", "participants": { "items": [ { "id": "@adamvy:local-signal.localhost", "fullName": "Adam Van Ymeren", "cannotMessage": false, "isSelf": false }, { "id": "@batuhan:local-signal.localhost", "fullName": "Batuhan İçöz", "cannotMessage": false, "isSelf": true } ], "hasMore": false, "total": 2 }, "lastActivity": "2025-08-31T17:38:20.393Z", "unreadCount": 0, "isArchived": false, "isMuted": false, "isPinned": true }, "!telegram_nick:local-telegram.localhost": { "id": "!telegram_nick:local-telegram.localhost", "localChatID": "1229721", "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI", "network": "Telegram", "title": "Nick Mills-Barrett", "type": "single", "participants": { "items": [ { "id": "@nick:local-telegram.localhost", "username": "nick", "fullName": "Nick Mills-Barrett", "cannotMessage": false, "isSelf": false }, { "id": "@batuhan:local-telegram.localhost", "username": "batuhan", "fullName": "Batuhan İçöz", "cannotMessage": false, "isSelf": true } ], "hasMore": false, "total": 2 }, "lastActivity": "2025-08-31T16:45:10.123Z", "unreadCount": 2, "isArchived": false, "isMuted": true, "isPinned": false } }, "hasMore": true, "oldestCursor": "1756379069621", "newestCursor": null } ``` ### 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