Home
/
Chat
/
Platform API
/
Messages

Message search is a feature that retrieves a list of messages that contain a search query from group channels joined by a specific user. You can search for either an exact match or a partial match and even filter the results by message properties such as target_user_ids, message_ts_from, or message_ts_to.

This message search is one of Sendbird's premium features. Contact our sales team for further assistance.

Resource representation

The properties of search results are much the same as those of a list of messages, except for the total_count.

Property nameTypeDescription

total_count

int

The total number of messages that contain the search term and match with all the parameters specified.

Actions

  • All API endpoints are relative to the base URL allocated to the application. In this page, the /search/messages endpoint refers to https://api-{application_id}.sendbird.com/v3/search/messages.
ActionHTTP request

Search messages

GET /search/messages
Retrieves a list of messages containing a specific search term.


Search messages

Retrieves a list of messages that contain a search term.

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

HTTP request

Light Color Skin
Copy
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 user_id or channel_url parameter should be specified per query request.

user_id

string

Specifies the ID of the target user to restrict the search scope to the messages in the channel of which the target user is currently a member. 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 user_id or channel_url parameter should be specified per query request.

query

string

Search for messages by the specified query term that matches their content. Urlencoding the value is recommended (for example, ?query=urlencoded_term)

* If the specified query term includes special characters or punctuations, it will return 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 the user_id.

limit

int

Specifies the number of messages to return per page. Acceptable values are 1 to 99, inclusive.

exact_match

boolean

Determines whether to search for messages that exactly match the search term. If set to false, it will return partial matches that contain the search term. (Default: false)

message_ts_from

long

Restrict the search scope to the messages sent after the specified value, in Unix milliseconds format. This includes the messages sent exactly on the timestamp.

message_ts_to

long

Restrict the search scope to the messages sent before the specified value in Unix milliseconds format. This includes the messages sent exactly on the timestamp.

after

string

Marks the starting point of the search results to retrieve in the result set. The after can’t be specified in conjunction with the before.

before

string

Marks the end point of the search results to retrieve in the result set. The before can’t be specified in conjunction with the after.

reverse

boolean

Determines whether to sort the results in reverse order. If set to true, they are sorted in ascending order. If false, they are sorted in descending order. (Default: false)

target_user_ids

array

Specifies the list of user IDs to restrict the search scope to messages that are sent by the specified IDs. Up to 5 user_ids are allowed per request.

Query string example
Light Color Skin
Copy
?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.

Status: 200 OK
Light Color Skin
Copy
{
    "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": {
                "name": "Saturday soccer members",
                "channel_url": "sendbird_group_channel_1234",
                "Channel_type":"group",
                "custom_type": "sports",
                "cover_url": "https://sendbird.com/main/img/cover/cover_05.jpg",
                "is_distinct": false,
                "is_public": true,
                "is_super": false,
                "is_ephemeral": false,
                "is_access_code_required": false,
                "is_discoverable": true,
                "member_count": 4,
                "joined_member_count": 4,
                "members":[
                    {
                        "user_id": "Jeff",
                        "nickname": "Oldies but goodies",
                        "profile_url": "",
                        "is_active": true,
                        "is_online": false,
                        "state": "joined",
                        "last_seen_at": 0,
                        "metadata": {}
                    },
                    ... # More members
                ],
                "max_length_message": -1,
                "last_message": null,
                "unread_message_count": 0,
                "unread_mention_count": 0,
                "data": "",
                "created_at": 1576641833,
                "freeze": false
            }
        },
        ... # More results
    ],
    "start_cursor": "CHMOQ~~",
    "end_cursor": "CHMOQ0l~~",
    "has_prev": false,
    "has_next": true,
    "next": "CHMOQ0laS1NDE~~"
}
Property nameTypeDescription

results[]

list

A list of messages that match with 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 for the token parameter to retrieve the next page in the result set.

ON THIS PAGE