messages_search

messages_search finds messages in one channel or thread. You can search by text, by filters such as author or attachment type, or both.

Request

{
  "cmd": "messages_search",
  "channel": "general",
  "query": "release notes",
  "filters": {
    "from": "alice",
    "has": "link"
  },
  "limit": 20
}

Field	Type	Required	Description
`channel`	string	One of `channel` or `thread_id`	Channel name.
`thread_id`	string	One of `channel` or `thread_id`	Thread ID. If you also send `channel`, it must be the thread’s parent.
`query`	string	See below	Text to find. Trimmed, at most 200 characters.
`fuzzy`	boolean	No	Also match similar words. Defaults to `false`.
`filters`	object	See below	Conditions every result must meet. Unknown keys are rejected.
`limit`	integer	No	Results per page. Clamped to 1 through `limits.search_results` (from the handshake; 30 by default), which is also the default.
`offset`	integer	No	How many results to skip, for paging. Defaults to `0`.

Send a non-empty query, at least one filter, or both.

Filters

Filter	Type	Matches messages that
`from`	string or array	Were sent by any of these usernames.
`mentions`	string or array	Mention all of these usernames with `@username`.
`mentions_role`	string or array	Mention all of these roles. Give role names; a leading `@` or `@&` is ignored.
`pinged`	boolean	With `true`, mention you, mention one of your roles, or reply to you with a ping. `false` adds no condition.
`has`	string or array	Have every listed feature. See below.
`pinned`	boolean	Are pinned (`true`) or not pinned (`false`).
`edited`	boolean	Were edited (`true`) or never edited (`false`).
`before`	number	Were sent before this time. Unix seconds; values that look like milliseconds are converted.
`after`	number	Were sent after this time. Same units as `before`.

has accepts these values:

attachment, embed, reaction, reply, edit, poll
image: an image attachment, or an embed with an image or thumbnail
video, audio: an attachment of that type
link: text containing http://, https://, or www.
mention: text containing @
webhook: sent by a webhook
command: a slash command response

pinged checks the message text as it is now, using your current roles. For a record of the times you were actually mentioned, use pings_get.

How text matching works

The server ignores case and treats punctuation as spaces.

Without fuzzy, a message matches only if its text contains the whole query. These matches always rank highest.
With fuzzy: true, a message also matches if every word in the query matches some word in it. A word matches when it is equal, when the message word starts with it (queries of 2 or more letters), or when it is a close misspelling (queries of 4 or more letters).
Results are sorted by match quality, then newest first.

Response

{
  "cmd": "messages_search",
  "channel": "general",
  "query": "release notes",
  "results": [
    {
      "id": "7d0e4c1a-5b8f-4b0e-8f55-2d3c9a61e7b4",
      "user": "alice",
      "author_id": "<alice's user ID>",
      "timestamp": 1788940000.31,
      "content": "Release notes are up: https://example.com/changelog"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20,
  "has_more": false,
  "fuzzy": false,
  "filters": {
    "from": ["alice"],
    "has": ["link"]
  }
}

Field	Description
`results`	Matching message objects for this page.
`total`	Number of matches across all pages.
`offset`, `limit`	The values the server used.
`has_more`	`true` when more results follow. Send `offset + limit` to get the next page.
`query`, `fuzzy`	Your search, echoed back.
`filters`	Your filters after validation. Single values come back as one-item arrays. Left out when you sent none.

A thread response has thread_id, and channel is the thread’s parent.
Messages from users severed from you are removed from results but still counted in total.
Search reads the whole history of the channel or thread, so it can be slow on large conversations.

Permissions

You must be able to view the channel, or the thread’s parent channel.

Errors

`val`	When
`Channel name or thread_id is required`	You sent neither `channel` nor `thread_id`.
`Channel not found`	The channel doesn’t exist.
`Thread not found`	No thread has this ID.
`Thread does not belong to this channel`	`channel` is not the thread’s parent.
`You do not have permission to view this thread`	You can’t view the thread’s parent channel.
`Messages must be sent inside a thread in forum channels`	`channel` is a forum and you sent no `thread_id`.
`This channel does not support chat`	`channel` is a separator.
`Access denied to this channel`	You can’t view the channel.
`Unknown user '<name>' in filters.from`	A `from` username doesn’t exist.
`Unknown user '<name>' in filters.mentions`	A `mentions` username doesn’t exist.
`Unknown role '<name>' in filters.mentions_role`	A role name doesn’t exist.
`A query or at least one filter is required`	`query` is empty and there are no filters. `pinged: false` alone doesn’t count.

A validation message is returned when query is longer than 200 characters, filters has an unknown key or an invalid has value, before or after is negative, or offset is negative.