/ Platform API
Platform API
    Chat Platform API v3
    Chat Platform API
    Chat Platform API
    Version 3

    Search messages

    Copy link

    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

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

    Parameters

    Copy link

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

    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 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 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&query=lunch
    

    Response

    Copy link

    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":[
            {
                "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

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