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

    List messages

    Copy link

    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

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

    Parameters

    Copy link

    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
    RequiredTypeDescription

    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. It fetches messages that were sent prior to and after the specified message_ts and the default value for both prev_limit and next_limit is 15.

    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. It fetches messages that were sent prior to and after the specified message_id and the default value for both prev_limit and next_limit is 15.

    OptionalTypeDescription

    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)

    ?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

    Copy link

    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.

    {
        "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": {
                        "font_preference": "times new roman",
                        "font_color": "black"
                    }
                },
                "mention_type": "users",
                "mentioned_users": [
                    {
                        "user_id": "Jay",
                        "nickname": "Rooster",
                        "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png",
                        "metadata": {
                            "font_preference": "times new roman",
                            "font_color": "black"
                        }
                    },
                    ... # 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

    Copy link
    Property nameTypeDescription

    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.