Search messages
search_messagesSearch the user's messages and return those whose text — the message content or an audio
message's transcript — matches query. Omit conversation_id to search every conversation at
once: that is how to find which conversation mentions something, and each match names its
conversation; add phone to keep it to the conversations of one connected number. Pass a
conversation_id (from search_conversations or an earlier match) to search inside that one
only. Matches come back most recent first with timestamps and
senders, so the latest activity is on the first page. Optionally bound the search to a
start_date / end_date window (e.g. "what came up this week"). To continue, pass cursor (the
next_cursor from the previous page) with the same query and conversation_id, or again
without one; the cursor carries the date range and the number, and a null next_cursor means
the end. Only
conversations the user owns or has been shared are accessible.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "search_messages"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max matches per page (default 50, capped at 200). | |
| phone | No | Optional, without `conversation_id`: search only the conversations of this connected number, in E.164 as `list_connected_numbers` lists it. Omit it to search every number's. | |
| query | Yes | Text matched against message content and audio transcripts. | |
| cursor | No | The `next_cursor` from a previous page; omit for the first page. | |
| end_date | No | Optional ISO 8601 date (YYYY-MM-DD) upper bound on the match timestamp. | |
| start_date | No | Optional ISO 8601 date (YYYY-MM-DD) lower bound on the match timestamp. | |
| conversation_id | No | The conversation to search within (from `search_conversations`). Omit it to search every conversation. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Its name; present and absent together with `conversation_id`. | |
| query | No | The query these matches came from. | |
| results | No | ||
| next_step | No | Present only when capture is paused for billing on one of the user's numbers — what is here still searches, but nothing new is arriving. Relay it to the user. | |
| next_cursor | No | Pass back as `cursor` for the next page. It already carries the query and date range. `null` means there are no more matches. | |
| conversation_id | No | The conversation that was searched; absent when the search covered all of them. |