Chat / Platform API
Current version: v3
    Chat Platform API v3
    Chat Platform API
    Chat
    Platform API
    Home
    /
    Chat
    /
    Platform API

    Search a message

    Retrieves a list of messages containing a specific search term.

    Note: Message search is limited to up to 100 public and private group channels joined by a specified user.


    HTTP request

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

    Parameters

    The following table lists the parameters that this action supports.

    Parameters
    RequiredTypeDescription

    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. Urlencoding the value is recommended (for example, ?user_id=urlencoded_id).

    * 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. When exact_match is set to true, this only retrieves messages that exactly match the search term. Urlencoding the value is recommended (for example, ?query=urlencoded_term)

    * If the specified search term includes special characters or punctuations, the search returns an error.

    OptionalTypeDescription

    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 search term. If set to false, it returns partial matches that contain the search term. (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 wildcard, fuzzy search, logical operators, and synonym search in the query string. (Default: false)

    * See advanced search for more information.

    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. Contact support by logging into the Sendbird Dashboard for more information.

    sort_field

    string

    Specifies the primary field to sort the results. Acceptable values are the following:
    - score (default): results appear in the order of their scores as determined by the score parameter, with the highest scoring message appearing first.
    - ts: results appear in the order of their created timestamps, with the latest message appearing first.

    score

    boolean

    Determines whether to include a score indicating how relevant each result is to the search term in the search results. The score parameter is effective only when the value of sort_field is score. When sort_field has other values such as ts, the search results aren't given a score. (Default: false)

    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)

    ?channel_url=group_channel_25108471_a1bc35f5f0d237207bc1rd343562c878fc2fd426&user=jeff&query=lunch
    

    Response

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

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

    List of response properties

    Property nameTypeDescription

    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.