List messages

You can retrieve a list of past messages of a specific channel with this API.

By default, this action returns a list of messages in the order they were created. Replies in threaded messages are also listed in the chronological order of their creation like other messages, not grouped with their parent messages.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Note: The include_parent_message_info, include_thread_info, and include_reply_type parameters are related to Sendbird's message threading feature. To learn more, see the message threading page.

Parameters

Required	Type	Description
channel_type	string	Specifies the type of the channel. Acceptable values are `open_channels` and `group_channels`.
channel_url	string	Specifies the URL of the channel.
message_ts	long	Specifies the timestamp to be the reference point of the query in Unix milliseconds. Either this or the `message_id` parameter below should be specified in your query URL to retrieve a list.
message_id	long	Specifies the unique ID of the message to be the reference point of the query. Either this or the `message_ts` parameter above should be specified in your query URL to retrieve a list.

Optional	Type	Description
prev_limit	int	Specifies the number of previously sent messages to retrieve before `message_ts`. For example, if `message_ts=1484202848298`, then `prev_limit=50` returns 50 messages sent by 1484202848297 (message_ts - 1). Acceptable values range from `0` to `200`. (Default: `15`)
next_limit	int	Specifies the number of sent messages to retrieve after `message_ts`. For example, if `message_ts=1484202848298`, then `next_limit=50` returns 50 messages sent from 1484202848299 (message_ts + 1). Acceptable values range from `0` to `200`. (Default: `15`)
include	boolean	Determines whether to include messages sent exactly on the specified `message_ts` in the results. (Default: `true`)
reverse	boolean	Determines whether to sort the results in reverse chronological order. If set to `true`, messages appear in reverse chronological order where the newest comes first and the oldest last. (Default: `false`)
sender_id	string	Restricts the search scope to only retrieve messages sent by the user with the specified ID.
sender_ids	string	Restricts the search scope to only retrieve messages sent by one or more users with the specified IDs listed in a comma-separated string.
operator_filter	string	Restricts the search scope to only retrieve messages sent by operators or non-operator users of the channel. Acceptable values are `all`, `operator`, and `nonoperator`. (Default: `all`)
message_type	string	Specifies a message type to retrieve. Acceptable values are `MESG`, `FILE`, and `ADMM`. If not specified, all messages are retrieved.
custom_types	string	Specifies a comma-separated string of one or more custom message types to retrieve. The value set to this parameter can serve as a filter as follows: - A string of specific custom types: Messages with the corresponding custom types are returned. - Empty like `&custom_types=&...`: Messages whose `custom_type` property is empty or has a value of null are returned. - *An asterisk (`\`)** (default): All messages are returned regardless of their `custom_type`.
including_removed	boolean	Determines whether to include messages removed from the channel in the results. (Default: `false`)
include_parent_message_info	boolean	Determines whether to include information of the parent message in the results. (Default: `false`)
include_thread_info	boolean	Determines whether to include thread information in the results. (Default: `false`)
include_reply_type	string	Specifies the type of message to include in the results. - `NONE` (default): All messages that are not replies. These messages may or may not have replies in its thread. - `ALL:` All messages including threaded and non-threaded parent messages as well as its replies. - `ONLY_REPLY_TO_CHANNEL:` Messages that are not threaded. Only the parent messages and replies that were sent to the channel are included.
include_reactions	boolean	Determines whether to include reactions added to messages in the channel in the results. (Default: `false`)
include_poll_details	boolean	Determines whether to include all properties of a poll resource with a full list of options in the results. If set to `false`, a selection of poll resource properties consisting of `id`, `title`, `close_at`, `created_at`, `updated_at`, `status`, and `message_id` are returned. (Default: `false`) * To use this property, the polls feature should be turned on in Settings > Chat > Features on Sendbird Dashboard.
with_sorted_meta_array	boolean	Determines whether to include the `sorted_metaarray` property in the response. (Default: `false`)
show_subchannel_messages_only	boolean	Determines whether to retrieve messages from a subchannel where the user specified in the `user_id` parameter is currently in. The `show_subchannel_messages_only` parameter takes effect only when the `channel_type` parameter is set to `open_channels`, the subchannel's `subchannel_messages_lifetime` property hasn't expired, and the value of the `max_recent_messages_count` property is specified with the maximum number of messages to be retrieved. If set to `false`, messages from all subchannels are retrieved. This should be specified in conjunction with `user_id` below. (Default: `false`)
user_id	string	Specifies the unique ID of a user to restrict the scope to the user's subchannel. Messages in the user's subchannel are retrieved. This parameter should be specified in conjunction with the `show_subchannel_messages_only` parameter above.
~~custom_type~~	string	*(Deprecated)* Specifies the custom message type to filter the messages with the corresponding custom type. If not specified, all messages are retrieved.
~~with_meta_array~~	boolean	*(Deprecated)* Determines whether to include the `metaarray` property in the response. (Default: `false`)
~~include_replies~~	boolean	*(Deprecated)* Determines whether to include replies as messages in the results. If set to `true`, all messages including replies, ones without replies, and ones with a thread of replies are returned in the results in chronological order. (Default: `false`)
~~include_parent_message_text~~	boolean	*(Deprecated)* Determines whether to include the text of parent messages as the `parent_message_text` property in the results. This property can be used to simultaneously display the content of parent messages and their thread of replies. (Default: `false`)

Query string example

?message_ts=1484208113351&prev_limit=10&next_limit=10&operator_filter=nonoperator&custom_types=vote,poll&include_parent_message_info=true&include_thread_info=true&include_reply_type=ALL&include_poll_details=true

Note : To access an encrypted file in a file message, you can use an HTTP GET request containing an Api-Token header specified with either your master API token or secondary API token regardless of the require_auth parameter. The URL of the encrypted file you want to retrieve should be specified in the request.

Response

If successful, this action returns a list of message resources that match the specified parameters in the response body.

Note: Sendbird Chat SDK supports the generation of a URL link preview within a message if the given URL has Open Graph (OG) tags, which are included as an og_tag property in your response as well. This feature is turned on by default for Sendbird applications. To enable this functionality, visit this page.

Status: 200 OK

{
    "messages": [
        {
            "message_id": 273778828,
            "type": "MESG",
            "custom_type": "vote",
            "channel_url": "sendbird_group_channel_6037267_600ddc81a5e23049c804193370d47217fa2ed5f9",
            "user": {
                "user_id": "Aaron",
                "nickname": "Raptor",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_53_512px.png",
                "metadata": {
                    "location": "St. Louis",
                    "marriage": "N"
                }
            },
            "mention_type": "users",
            "mentioned_users": [
                {
                    "user_id": "Jay",
                    "nickname": "Rooster",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png",
                    "metadata": {
                        "location": "New York",
                        "marriage": "Y"
                    }
                },
                ... # More mentioned users
            ],
            "is_removed": false,
            "message": "Hey, what do you think of our front page? I created three new designs, can you check them out? www.sendbird.com",
            "translations": {},
            "data": "",
            "sorted_metaarray": [
                {
                    "key": "design",
                    "value": ["A", "B", "C"]
                }
            ],
            "og_tag": {
                "og:url": "www.sendbird.com",
                "og:title": "Sendbird - A Complete Chat Platform, Messaging and Chat SDK and API",
                "og:description": "Sendbird's chat, voice and video APIs and SDKs connect users through immersive, modern communication solutions that drive better user experiences and engagement.",
                "og:image": {
                    "url": "https://6cro14eml0v2yuvyx3v5j11j-wpengine.netdna-ssl.com/wp-content/uploads/sendbird_thumbnail.png",
                    "secure_url": "https://6cro14eml0v2yuvyx3v5j11j-wpengine.netdna-ssl.com/wp-content/uploads/sendbird_thumbnail.png",
                    "width": 640,
                    "height": 480
                }
            },
            "poll": {                   // When include_poll_details is set to false,
                "id": 2510,             // only a selection of poll resource properties is shown.
                "title": "Front page design",
                "status": "open",
                "allow_user_suggestion": true,
                "data": "",
                "allow_multiple_votes": true,
                "created_at": 1544421551,
                "updated_at": 0,
                "created_by": "Aaron",
                "voter_count": 0,
                "close_at": 1625810317,
                "options": [
                    {
                        "text": "A",
                        "created_at": 1544421551,
                        "updated_at": 0,
                        "created_by": "Aaron",
                        "vote_count": 0,
                        "poll_id": 2510,
                        "id": 3872
                    },
                    {
                        "text": "B",
                        "created_at": 1544421551,
                        "updated_at": 0,
                        "created_by": "Aaron",
                        "vote_count": 0,
                        "poll_id": 2510,
                        "id": 3873
                    },
                    {
                        "text": "C",
                        "created_at": 1544421551,
                        "updated_at": 0,
                        "created_by": "Aaron",
                        "vote_count": 0,
                        "poll_id": 2510,
                        "id": 3874
                    }
                ]
            },
            "message_events": {
                "send_push_notification": "none",
                "update_unread_count": false,
                "update_mention_count": false,
                "update_last_message": false
            },
            "created_at": 1544421761159,
            "updated_at": 0,
            "file": {}
        },
        ... # More messages
    ]
}

List of response properties

Property name	Type	Description
messages[]	array of objects	An array of messages that match the specified optional parameters.

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

Try API requests