Message Search

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

Search messages

post

Search messages according to the specified criteria.

Query parameters

skipintegerOptional

No. of results to skip.

limitintegerOptional

Max no. of results to return. If no value is provided, 50 is the default.

scopestringOptional

Describes where content should be searched for that query. It can exclusively apply to Symphony content or to one Connector.

sortDirstringOptional

Messages sort direction : ASC or DESC (default to DESC)

Header parameters

sessionTokenstringRequired

Session authentication token.

keyManagerTokenstringRequired

Key Manager authentication token.

Body

textstringOptional

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

streamIdstringOptional

Search for messages sent to this stream

streamTypestringOptional

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

authorinteger · int64Optional

Search for messages sent by this user ID

hashtagstringOptional

Search for messages containing this hashtag

cashtagstringOptional

Search for messages containing this cashtag

mentioninteger · int64Optional

Search for messages mentioning this user ID

signalstringOptional

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

fromDateinteger · int64Optional

Search for messages sent on or after this timestamp

toDateinteger · int64Optional

Search for messages sent before this timestamp

Responses

200

OK

application/json

204

No Messages.

400

Client error, see response body for further details.

application/json

401

Unauthorized: Session tokens invalid.

application/json

403

Forbidden: Caller lacks necessary entitlement.

application/json

500

Server error, see response body for further details.

application/json

post

HTTPcURLJavaScriptPython

POST /agent/v1/message/search HTTP/1.1
Host: youragentURL.symphony.com
sessionToken: text
keyManagerToken: text
Content-Type: application/json
Accept: */*
Content-Length: 150

{
  "text": "text",
  "streamId": "text",
  "streamType": "text",
  "author": 1,
  "hashtag": "text",
  "cashtag": "text",
  "mention": 1,
  "signal": "text",
  "fromDate": 1,
  "toDate": 1
}

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

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