# Message Search

## Search messages

> Search messages according to the specified criteria.

```json
{"openapi":"3.0.1","info":{"title":"Agent API","version":"25.8.1"},"servers":[{"url":"youragentURL.symphony.com/agent"}],"paths":{"/v1/message/search":{"post":{"tags":["Messages"],"summary":"Search messages","description":"Search messages according to the specified criteria.","parameters":[{"name":"skip","in":"query","description":"No. of results to skip.","schema":{"type":"integer"}},{"name":"limit","in":"query","description":"Max no. of results to return. If no value is provided, 50 is the default.","schema":{"type":"integer"}},{"name":"scope","in":"query","description":"Describes where content should be searched for that query.\nIt can exclusively apply to Symphony content or to one Connector.\n","schema":{"type":"string"}},{"name":"sortDir","in":"query","description":"Messages sort direction : ASC or DESC (default to DESC)\n","schema":{"type":"string"}},{"name":"tier","in":"query","description":"Target search tier : hot, warm or all (default to hot)\n","schema":{"type":"string"}},{"name":"sessionToken","in":"header","description":"Session authentication token.","required":true,"schema":{"type":"string"}},{"name":"keyManagerToken","in":"header","description":"Key Manager authentication token.","schema":{"type":"string"}}],"requestBody":{"description":"The search query. See above for the query syntax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageSearchQuery"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V4MessageList"}}}},"204":{"description":"No Messages.","content":{}},"400":{"description":"Client error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"401":{"description":"Unauthorized: Session tokens invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"403":{"description":"Forbidden: Caller lacks necessary entitlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"500":{"description":"Server error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}}}}}},"components":{"schemas":{"MessageSearchQuery":{"type":"object","properties":{"text":{"type":"string","description":"Search for messages containing this text. Requires streamId to be specified."},"streamId":{"type":"string","description":"Search for messages sent to this stream"},"streamType":{"type":"string","description":"Search for messages sent to this type of streams. Accepted values are CHAT, IM, MIM, ROOM, POST.\n"},"author":{"type":"integer","description":"Search for messages sent by this user ID","format":"int64"},"hashtag":{"type":"string","description":"Search for messages containing this hashtag"},"cashtag":{"type":"string","description":"Search for messages containing this cashtag"},"mention":{"type":"integer","description":"Search for messages mentioning this user ID","format":"int64"},"signal":{"type":"string","description":"Search for messages matching this signal. Can only be combined with date filtering and paging parameters.\n"},"fromDate":{"type":"integer","description":"Search for messages sent on or after this timestamp","format":"int64"},"toDate":{"type":"integer","description":"Search for messages sent before this timestamp","format":"int64"}}},"V4MessageList":{"type":"array","items":{"$ref":"#/components/schemas/V4Message"}},"V4Message":{"type":"object","properties":{"messageId":{"type":"string","description":"Id of the message"},"parentMessageId":{"type":"string","description":"Id of the parent message, set when the message is a reply to another message or a forwarded message. Since Agent 20.14."},"timestamp":{"type":"integer","description":"Timestamp of the message in milliseconds since Jan 1 1970","format":"int64"},"message":{"type":"string","description":"Message content in MessageMLV2","format":"MessageMLV2"},"sharedMessage":{"$ref":"#/components/schemas/V4Message"},"data":{"type":"string","description":"Message data in EntityJSON","format":"JSON"},"attachments":{"type":"array","default":[],"description":"Message attachments","items":{"$ref":"#/components/schemas/V4AttachmentInfo"}},"user":{"$ref":"#/components/schemas/V4User"},"stream":{"$ref":"#/components/schemas/V4Stream"},"externalRecipients":{"type":"boolean","description":"Indicates if the message have external recipients. Only present on real time messaging."},"diagnostic":{"type":"string","description":"Details if event failed to parse for any reason.  The contents of this field may not be useful,\ndepending on the nature of the error. Only present when error occurs.\n"},"userAgent":{"type":"string","description":"User agent string for client that sent the message.  Allows callers to identify which client sent the\norigin message (e.g. API Agent, SFE Client, mobile, etc)\n"},"originalFormat":{"type":"string","description":"Indicates the format in which the message was originally sent.  This could have been either:\n- com.symphony.markdown - Markdown OR Message ML V1\n- com.symphony.messageml.v2 - Message ML V2\n"},"disclaimer":{"type":"string","description":"Message that may be sent along with a regular message if configured for the POD,\nusually the first message sent in a room that day.\n"},"sid":{"type":"string","description":"Unique session identifier from where the message was created.\n"},"replacing":{"type":"string","description":"Id of the message that the current message is replacing (present only if set)"},"replacedBy":{"type":"string","description":"Id of the message that the current message is being replaced with (present only if set)"},"initialTimestamp":{"type":"integer","description":"Timestamp of when the initial message has been created in milliseconds since \nJan 1 1970 (present only if set)\n","format":"int64"},"initialMessageId":{"type":"string","description":"Id the the initial message that has been updated (present only if set)"},"silent":{"type":"boolean","description":"When false the user/s will receive the message update as unread (true by default)"}},"description":"A representation of a message sent by a user of Symphony"},"V4AttachmentInfo":{"required":["id","name","size","images"],"type":"object","properties":{"id":{"type":"string","description":"The attachment ID."},"name":{"type":"string","description":"The file name."},"size":{"type":"integer","description":"Size in bytes.","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/V4ThumbnailInfo"}}}},"V4ThumbnailInfo":{"type":"object","properties":{"id":{"type":"string","description":"The thumbnail ID."},"dimension":{"type":"string","description":"The thumbnail pixel size."}}},"V4User":{"type":"object","properties":{"userId":{"type":"integer","description":"Id of user","format":"int64"},"firstName":{"type":"string","description":"First name of user"},"lastName":{"type":"string","description":"Last name of user"},"displayName":{"type":"string","description":"User display name"},"email":{"type":"string","description":"Email of user"},"username":{"type":"string","description":"Applicable only to internal users"}}},"V4Stream":{"type":"object","properties":{"streamId":{"type":"string","description":"Id of stream"},"streamType":{"type":"string","description":"Stream type, possible values are:\n  - IM\n  - MIM\n  - ROOM\n  - POST\n"},"roomName":{"type":"string","description":"Applicable only to rooms"},"members":{"type":"array","description":"Applicable only to IM Created","items":{"$ref":"#/components/schemas/V4User"}},"external":{"type":"boolean"},"crossPod":{"type":"boolean"},"recipientTenantIds":{"type":"array","description":"List of tenant identifiers (aka pod identifiers) involved in the conversation. It contains more than one\nitem if the conversation is external. Field is only present for real time messaging.\n","items":{"type":"integer","format":"int32"}}}},"V2Error":{"required":["code","message"],"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"object"}}}}}}
```

### Request Example

```bash
curl -X POST https://acme.symphony.com/agent/v1/message/search \
    -H "sessionToken: SESSION_TOKEN" \
    -H "keyManagerToken: KEYMANAGER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "hashtag":"newWorld" }'
```

> #### 📘 Optional attributes returned
>
> Note that some attributes are returned in the payload only under specific conditions:
>
> * `sharedMessage` only when the message represented by this class is a wall post sharing another message;
> * `initialMessageId`, `initialTimestamp`, and `replacing` only when the corresponding message is sent as an update to another message thanks to [Update Message](/main/messages/update-message-v4.md) endpoint. Note that the first two attributes relate to the original (and therefore first) message sent, whereas the `replacing` attribute relates to the message that has been updated by this message;
> * `replacedBy` only when this message has been updated by a new message. It contains the id of the replacing message.
> * `parentMessageId` only when this message is a reply or a forward of another message which id is returned in this attribute.

### Search Query Arguments

The `query` parameter supports the following combination of arguments. When multiple arguments are supported, the search results are the union of all query arguments. Only a certain combination of arguments is supported.

* At least one argument in the list is required.
* Arguments names and values are case-insensitive.
* The same argument cannot be used multiple times.
* Search terms cannot contain the following reserved characters: colon `:`, parentheses `( )` and whitespaces (except when applying multi-word text search. See the `text` argument in the table below).
* `fromDate`, `toDate`, `mention`, and `author` are integers. All other arguments are strings.

<table><thead><tr><th width="149">Argument</th><th>Usage</th><th>Comment</th></tr></thead><tbody><tr><td><code>hashtag</code></td><td>Searches for a specific hashtag across messages to or in a specific <code>streamType</code></td><td><ul><li>Can be used in conjunction with <code>cashtag</code> or <code>mention</code>.</li><li>Can be used in conjunction to <code>author</code> or <code>text</code> only for a specific <code>streamType</code></li></ul></td></tr><tr><td><code>cashtag</code></td><td>Searches for a specific cashtag across all messages or in a specific <code>streamType</code></td><td><ul><li>Can be used in conjunction with <code>hashtag</code> or <code>mention</code>.</li><li>Can be used in conjunction to <code>author</code> or <code>text</code> only for a specific <code>streamType</code></li></ul></td></tr><tr><td><code>mention</code></td><td>Searches for a specific user mention, by user id, across all messages or in a specific <code>streamType</code></td><td><ul><li>Can be used in conjunction with <code>hashtag</code> or <code>cashtag</code>.</li><li>Can be used in conjunction to <code>author</code> or <code>text</code> only for a specific <code>streamType</code></li></ul></td></tr><tr><td><code>author</code></td><td>Searches for a specific message author, by user id, across all messages or for a specific <code>streamType</code></td><td>(<em>1.52 and later</em>) You can now search for an <code>author</code> in conjunction with a specific <code>streamType</code></td></tr><tr><td><code>text</code></td><td>Searches for plain text field in a specific message, not including any hashtag, cashtag or user mention.</td><td><ul><li>Requires a <code>streamId</code> to be provided.</li><li>Searching for text across all messages or a specific <code>streamType</code> is not supported.</li><li>Multi-word search is allowed.<br>Syntax: <code>"text":"Hello World"</code></li></ul></td></tr><tr><td><code>streamType</code></td><td>Searches for messages in a specific stream type, either:<br>• <code>CHAT</code> (1-1 instant messages and multi-party instant messages),<br>• <code>IM</code> (1-1 instant message),<br>• <code>MIM</code> (multi-party instant message),<br>• <code>ROOM</code>, or<br>• <code>POST</code> (user profile wall posts).</td><td>Can be used in conjunction with <code>author</code>, <code>hashtag</code>, <code>cashtag</code> or <code>mention</code></td></tr><tr><td><code>streamId</code></td><td>Searches for messages in a specific stream. See <a href="doc:room-id">Conversation ID</a> for streamId format.</td><td>Can be used in conjunction with <code>hashtag</code>, <code>cashtag</code>, <code>mention</code>, <code>text</code> or <code>author</code></td></tr><tr><td><code>signal</code></td><td>Search for messages matching this signal.</td><td>Can only be combined with date filtering and paging parameters.</td></tr></tbody></table>

### Date selector

The `query`parameter can optionally support the following date selectors:

* `fromDate`: selects messages sent after `fromDate`. Supported for all query parameters above.
* `toDate`: selects messages sent before `toDate`. Supported for all query parameters above.\
  The date selector parameter is inclusive: a message sent at exactly the same time as the query `fromDate` will be included in the results.

> #### 📘 See also
>
> [Message](https://docs.developers.symphony.com/building-bots-on-symphony/messages)\
> [MessageML](https://docs.developers.symphony.com/building-bots-on-symphony/messages/overview-of-messageml)\
> [Message ID](https://docs.developers.symphony.com/bots/messages#message-identifiers)\
> [Message Format - MessageML](https://docs.developers.symphony.com/building-bots-on-symphony/messages/overview-of-messageml/message-format-messageml)\
> [PresentationML](https://docs.developers.symphony.com/building-bots-on-symphony/messages/overview-of-presentationml)\
> [Message Format - ExtensionML](https://docs.developers.symphony.com/building-extension-applications-on-symphony/overview-of-extension-api/extension-api-services/entity-service/message-format-extensionml)\
> [Colors](https://docs.developers.symphony.com/developer-tools/developer-tools/ui-style-guide/colors)\
> [Symphony Elements](https://docs.developers.symphony.com/building-bots-on-symphony/symphony-elements)

> #### 🚧
>
> The messages returned by this endpoint follow the permissions required by the [Messages](/main/messages/messages-v4.md) endpoint.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rest-api.symphony.com/main/messages/message-search-post.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.