Search messages

This action retrieves a list of messages containing a specific search term. You can set the search scope to either a specific group channel or a specific user. When the search scope is set to a user, the search targets up to 100 group channels joined by the user.

Note: Punctuations and special characters are ignored while indexing, so unless they're being used for advanced search functionalities, they should be removed or replaced in the search term for best results.

HTTP request

GET https://api-{application_id}.sendbird.com/v3/search/messages

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the channel URL to restrict the search scope to a specific group channel. * Only either the `user_id` or `channel_url` parameter should be specified per query request.
user_id	string	Restricts the search scope to only retrieve messages from one or more channels where the specified users are members. The search targets up to 100 private and public group channels joined by the user. URL encoding the value is recommended. * Only either the `user_id` or `channel_url` parameter should be specified per query request.
query	string	Searches for messages that contain content that matches the specified search term. If you want the search messages that exactly match a group of keywords, set `exact_match` to `true`. * Special characters and punctuations aren't indexed, so including them in the query may return unexpected search results.

Optional	Type	Description
custom_type	string	Specifies the custom channel type to restrict the search scope. This `custom_type` should be specified in conjunction with `user_id`.
limit	int	Specifies the number of messages to return per page. Acceptable values are `1` to `99`, inclusive. (Default: `20`)
exact_match	boolean	Determines whether to search for messages that contain an exact match for the entire search term. If set to `false`, matches that contain parts of the search term are returned. (Default: `false`)
advanced_query	boolean	Determines whether to apply advanced search functionalities to the `query` parameter. When `advanced_query` is set to `true`, you can use functionalities like wildcard, fuzzy search, logical operators, and synonym search in the `query` parameter. To learn more about these functionalities, see the advanced search section. (Default: `false`) * Both `advanced_query` and `exact_match` can't be set to `true` at the same time.
synonym	boolean	Determines whether to search for messages containing synonyms of the search term. (Default: `false`) * If you wish to enable `synonym` for message search, a file of synonyms must be provided before enabling the message search feature. For more information, visit this page and contact us on Sendbird Dashboard.
sort_field	string	Specifies the primary field to sort the results. Acceptable values are the following. - `score` (default): Results are sorted by a score that is derived from relevance. - `ts`: Results appear in the order of their created timestamps, with the latest message appearing first.
message_ts_from	long	Restricts the search scope to the messages sent after the specified value in Unix milliseconds format. This includes messages sent exactly on the timestamp.
message_ts_to	long	Restricts the search scope to the messages sent before the specified value in Unix milliseconds format. This includes messages sent exactly on the timestamp.
after	string	Marks the starting point of the search results to retrieve in the result set. The `after` parameter can't be specified in conjunction with `before`.
before	string	Marks the end point of the search results to retrieve in the result set. The `before` parameter can't be specified in conjunction with `after`.
reverse	boolean	Determines whether to sort the results in reverse order. If set to `true`, either messages with the lowest score appear first (when `sort_field` is set to `score`) or messages with the oldest created timestamp appear first (when `sort_field` is set to `ts`). (Default: `false`)
token	string	Specifies a page token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.
target_user_ids	array of strings	Specifies an array of user IDs to restrict the search scope to messages that are sent by the specified IDs. Up to five user IDs are allowed per request.
with_channel_in_response	boolean	Determines whether to show detailed information about the target channel in the response. (Default: `false`)

Query string example

?channel_url=group_channel_25108471_a1bc35f5f0d237207bc1rd343562c878fc2fd426&query=lunch

Response

If successful, this action returns a list of messages that contain the search term in the response body like the following.

Status: 200 OK

{
    "total_count": 16,
    "results":[
        {
            "message_id": 9967398,
            "type":"MESG",
            "custom_type": "",
            "channel_url": "sendbird_group_channel_1234",
            "channel_type": "group",
            "user": {
                "user_id": "Katherine",
                "nickname": "Carrie",
                "profile_url": "",
                "metadata": {}
            },
            "mention_type": "users",
            "mentioned_users": [],
            "is_removed": false,
            "message": "Do you want to grab lunch tomorrow?",
            "translations": {},
            "data": "",
            "created_at": 1576641834093,
            "updated_at": 0,
            "file": {},
        },
        ... # More results
    ],
    "start_cursor": "CHMOQ~~",
    "end_cursor": "CHMOQ0l~~",
    "has_prev": false,
    "has_next": true,
    "next": "CHMOQ0laS1NDE~~"
}

List of response properties

Property name	Type	Description
results[]	array of objects	An array of messages that match the specified parameters.
start_cursor	string	The starting index of the current results.
end_cursor	string	The ending index of the current results.
has_prev	boolean	Indicates whether there is a previous page of results.
has_next	boolean	Indicates whether there is a next page of results.
next	string	The value that can be used in the `token` parameter to retrieve the next page in the result set.

In the case of an error, an error object is returned. A detailed list of error codes is available here.

On this page

HTTP request Parameters Response