paginated_search_conversations
Search conversations by reference number or contact email, apply filters, and page through results with a cursor. Exact reference matches appear first, and only accessible conversations are returned.
Instructions
Paginated Search Conversations
Matches conversations whose reference number equals the query or whose contact email contains it, with filters and cursor pagination. An exact reference number match is listed first. Returns only conversations the caller can access. Requires the conversations:read permission.
GET /api/v1/search/conversations
Tags: Search
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | `newest` and `oldest` sort by last message time. `started_last` and `started_first` sort by creation time. Defaults to `newest`. (query parameter) | newest |
| query | Yes | Search query (minimum 3 characters) (query parameter) | |
| cursor | No | `next_cursor` from the previous page. A cursor works only with the `sort` it was created with. (query parameter) | |
| filters | No | JSON-encoded filter. Either an array of conditions that are AND-ed, e.g. `[{"model":"conversations","field":"status_id","operator":"equals","value":"1"}]`, or a group `{"logic":"AND","rules":[...]}` with at most one level of nested groups. Operators: `equals`, `not equals`, `greater than`, `less than`, `set`, `not set`, `in`, `between`, `contains`, `ilike`, `not contains`. Filterable fields: `conversations` (status_id, priority_id, assigned_team_id, assigned_user_id, inbox_id, last_message_at, last_interaction_at, last_interaction_sender, created_at, waiting_since, next_sla_deadline_at, snoozed_until, sla_policy_id, tags), `conversation_statuses` (id, name), `users` (email, external_user_id), `inboxes` (channel). (query parameter) | |
| page_size | No | Number of results per page (defaults to 30). Values above 100 use 100. (query parameter) |