# 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](https://rest-api.symphony.com/main/messages/update-message-v4) 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](https://rest-api.symphony.com/main/messages/messages-v4) endpoint.