Message Search

Searches for messages in the context of a specified user, given an argument-based query.

Search messages

Search messages according to the specified criteria.

POSTyouragentURL.symphony.com/agent/v1/message/search

Query parameters

Header parameters

Body

The search query. See above for the query syntax.

textstring

Search for messages containing this text. Requires streamId to be specified.

streamIdstring

Search for messages sent to this stream

streamTypestring

Search for messages sent to this type of streams. Accepted values are CHAT, IM, MIM, ROOM, POST.

authorinteger (int64)

Search for messages sent by this user ID

hashtagstring

Search for messages containing this hashtag

cashtagstring

Search for messages containing this cashtag

mentioninteger (int64)

Search for messages mentioning this user ID

signalstring

Search for messages matching this signal. Can only be combined with date filtering and paging parameters.

fromDateinteger (int64)

Search for messages sent on or after this timestamp

toDateinteger (int64)

Search for messages sent before this timestamp

Response

Body

messageIdstring

Id of the message

parentMessageIdstring

Id of the parent message, set when the message is a reply to another message or a forwarded message. Since Agent 20.14.

timestampinteger (int64)

Timestamp of the message in milliseconds since Jan 1 1970

messagestring (MessageMLV2)

Message content in MessageMLV2

sharedMessageV4Message (object)

A representation of a message sent by a user of Symphony

datastring (JSON)

Message data in EntityJSON

attachmentsarray of V4AttachmentInfo (object)

Message attachments

userV4User (object)

streamV4Stream (object)

externalRecipientsboolean

Indicates if the message have external recipients. Only present on real time messaging.

diagnosticstring

Details if event failed to parse for any reason. The contents of this field may not be useful, depending on the nature of the error. Only present when error occurs.

userAgentstring

User agent string for client that sent the message. Allows callers to identify which client sent the origin message (e.g. API Agent, SFE Client, mobile, etc)

originalFormatstring

Indicates the format in which the message was originally sent. This could have been either:

com.symphony.markdown - Markdown OR Message ML V1
com.symphony.messageml.v2 - Message ML V2

disclaimerstring

Message that may be sent along with a regular message if configured for the POD, usually the first message sent in a room that day.

sidstring

Unique session identifier from where the message was created.

replacingstring

Id of the message that the current message is replacing (present only if set)

replacedBystring

Id of the message that the current message is being replaced with (present only if set)

initialTimestampinteger (int64)

Timestamp of when the initial message has been created in milliseconds since Jan 1 1970 (present only if set)

initialMessageIdstring

Id the the initial message that has been updated (present only if set)

silentboolean

When false the user/s will receive the message update as unread (true by default)

Request

const response = await fetch('youragentURL.symphony.com/agent/v1/message/search', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

[
  {
    "messageId": "text",
    "parentMessageId": "text",
    "message": "text",
    "data": "text",
    "attachments": [
      {
        "id": "text",
        "name": "text",
        "images": [
          {
            "id": "text",
            "dimension": "text"
          }
        ]
      }
    ],
    "user": {
      "firstName": "text",
      "lastName": "text",
      "displayName": "text",
      "email": "text",
      "username": "text"
    },
    "stream": {
      "streamId": "text",
      "streamType": "text",
      "roomName": "text",
      "members": [
        {
          "firstName": "text",
          "lastName": "text",
          "displayName": "text",
          "email": "text",
          "username": "text"
        }
      ],
      "external": false,
      "crossPod": false
    },
    "externalRecipients": false,
    "diagnostic": "text",
    "userAgent": "text",
    "originalFormat": "text",
    "disclaimer": "text",
    "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
    "replacing": "text",
    "replacedBy": "text",
    "initialMessageId": "text",
    "silent": false
  }
]

Request Example

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 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.

Argument Usage Comment

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

hashtag

Searches for a specific hashtag across messages to or in a specific streamType

Can be used in conjunction with cashtag or mention.
Can be used in conjunction to author or text only for a specific streamType

cashtag

Searches for a specific cashtag across all messages or in a specific streamType

Can be used in conjunction with hashtag or mention.
Can be used in conjunction to author or text only for a specific streamType

mention

Searches for a specific user mention, by user id, across all messages or in a specific streamType

Can be used in conjunction with hashtag or cashtag.
Can be used in conjunction to author or text only for a specific streamType

author

Searches for a specific message author, by user id, across all messages or for a specific streamType

(1.52 and later) You can now search for an author in conjunction with a specific streamType

text

Searches for plain text field in a specific message, not including any hashtag, cashtag or user mention.

Requires a streamId to be provided.
Searching for text across all messages or a specific streamType is not supported.
Multi-word search is allowed. Syntax: "text":"Hello World"

streamType

Searches for messages in a specific stream type, either: • CHAT (1-1 instant messages and multi-party instant messages), • IM (1-1 instant message), • MIM (multi-party instant message), • ROOM, or • POST (user profile wall posts).

Can be used in conjunction with author, hashtag, cashtag or mention

streamId

Searches for messages in a specific stream. See Conversation ID for streamId format.

Can be used in conjunction with hashtag, cashtag, mention, text or author

signal

Search for messages matching this signal.

Can only be combined with date filtering and paging parameters.

Date selector

The queryparameter 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 MessageML Message ID Message Format - MessageML PresentationML Message Format - ExtensionML Colors Symphony Elements

🚧
The messages returned by this endpoint follow the permissions required by the Messages endpoint.

Last updated 4 months ago

const response = await fetch('youragentURL.symphony.com/agent/v1/message/search', { method: 'POST', headers: { "Content-Type": "application/json" }, body: JSON.stringify({}), }); const data = await response.json();

[ { "messageId": "text", "parentMessageId": "text", "message": "text", "data": "text", "attachments": [ { "id": "text", "name": "text", "images": [ { "id": "text", "dimension": "text" } ] } ], "user": { "firstName": "text", "lastName": "text", "displayName": "text", "email": "text", "username": "text" }, "stream": { "streamId": "text", "streamType": "text", "roomName": "text", "members": [ { "firstName": "text", "lastName": "text", "displayName": "text", "email": "text", "username": "text" } ], "external": false, "crossPod": false }, "externalRecipients": false, "diagnostic": "text", "userAgent": "text", "originalFormat": "text", "disclaimer": "text", "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b", "replacing": "text", "replacedBy": "text", "initialMessageId": "text", "silent": false } ]