search_messages
Read-onlyIdempotent
Search message content across all chats — semantic + keyword. Use to find what was said: quotes, topics, info exchanged. Also finds captionless photos/screenshots by what they show or the words read from them: such a hit carries match_reason ('image' or 'attachment_text') and file_id — open that attachment. Pass direction, chat_kind or per_chat for an EXACT text search instead: who wrote it (outgoing = the owner), private chats or groups, one result per chat with the number of matches. That is the way to find the chat of a person by how the owner addresses them, e.g. query='Дима', direction='outgoing', chat_kind='dm', per_chat=true. For chats/threads themselves use search.threads; for files use search.files; for links use search.links.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum messages to return. | |
| query | No | What to search for in message content. | |
| channel | No | 'ai_panel' = search the workspace's AI-panel ("My AI") chats (owner/admin: all; a member: their own) by text; needs `query`. OMIT for the normal inbox. | |
| date_to | No | ISO8601 date (YYYY-MM-DD) upper bound. OMIT to skip. | |
| per_chat | No | Exact search only: one result per chat (its newest match) with `matches` = how many messages there matched. OMIT for every message. | |
| chat_kind | No | Exact search only: 'dm' = private chats, 'group' = groups and channels. OMIT for both. | |
| date_from | No | ISO8601 date (YYYY-MM-DD) lower bound. OMIT to skip. | |
| direction | No | Exact search only: 'outgoing' = messages the owner wrote, 'incoming' = messages others wrote. OMIT for both. | |
| whole_word | No | Exact search only: match the query as a whole word ('Дима' finds 'Привет, Дима!' but not 'Димасик'). OMIT to match any part of a word. | |
| image_limit | No | Maximum number of photo/screenshot rows in the results (0 to 50; 0 = no image rows). OMIT for the default: about a quarter of `limit`, at least 2, and more only when text hits leave slots unused. When given, it is a hard maximum. A value outside 0..50 is refused, never clamped. | |
| in_workspace | No | Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected. | |
| image_min_score | No | Minimum similarity (0 to 1) for photo/screenshot matches. Affects image hits only; text hits are unaffected. OMIT for the default (0.29 unless the deployment configures another). Image scores run lower than text scores: typically clear matches are about 0.40-0.50 and noise is usually below roughly 0.32. Raise it (e.g. 0.35) when photo hits are noisy; lower it (e.g. 0.25) to find weak matches such as scanned documents. A value outside 0..1 is refused, never clamped. | |
| image_hub_margin | No | How far (0 to 1) an image match must stand above that image's own similarity to unrelated queries; this hides images that look close to every query. OMIT it: the default is tuned. Change it only when the results show a problem, and then lower it a little (e.g. 0.04) rather than 0, which turns the check off. A value outside 0..1 is refused, never clamped. | |
| participant_name | No | Filter to messages involving this participant/contact name. OMIT to search across everyone (do NOT pass an empty string). | |
| image_strong_score | No | Similarity bar (0 to 1) that decides WHERE photo/screenshot matches go. At or above it a photo is interleaved near the top of the results (after the first text hit); below it (but above `image_min_score`) it is listed after all text results. Affects image hits only. OMIT for the default (0.40 unless the deployment configures another): typically clear matches score about 0.40-0.50. If it is below `image_min_score`, `image_min_score` is used as the bar. Raise it (e.g. 0.45) to keep photos out of the top unless they are clearly relevant; lower it (e.g. 0.33) when the answer is probably a photo. A value outside 0..1 is refused, never clamped. |