Migrate messages

Migrate messages from another system into Sendbird's system.

Before starting your migration, ensure that you've followed the necessary instructions.

HTTP request

POST https://api-{application_id}.sendbird.com/v3/migration/{target_channel_url}

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
target_channel_url	string	Specifies the URL of the channel to migrate the messages.

Request body

The following tables list the properties of an HTTP request that this action supports for migrating a text message, file message, and admin message.

List of properties for text message

Properties

Required	Type	Description
messages[]	array of objects	Specifies an array of text messages to migrate into the channel.
(message).user_id	string	Specifies the ID of the user who sent the message. Note that this user should be registered to your Sendbird application in advance, or else an error occurs.
(message).message_type	string	Specifies the type of the message. The default value for a text message is `MESG`.
(message).message	string	Specifies the content of the message.
(message).timestamp	long	Specifies the time when the message was sent in Unix milliseconds format. You can sort the messages based on this timestamp.
update_read_ts	boolean	Determines whether to update the read receipt time for all channel members when `message.timestamp` of the latest migrated message is prior to their read receipt time. If set to `true`, the unread message count for all channel members are updated as well. (Default: `false`) * This property can be used only when the target channel for migration is a group channel.

Optional	Type	Description
(message).custom_type	string	Specifies a custom message type used for message grouping. The length is limited to 128 characters.
(message).mentioned_user_ids[]	array of strings	Specifies an array of IDs of the users to mention in the message.
(message).data	string	Specifies additional message information such as custom font size or font type in JSON or other formats.
(message).dedup_id	string	Specifies a unique ID for the message created by another system. In general, this property is used to prevent the same message data from getting inserted when migrating the messages of another system to Sendbird server. If specified, the server performs a duplicate check using the property value. * If you include an existing `dedup_id` value of a previously migrated message in a request, the migration fails with a `400202` error.
rewind_read_ts	boolean	Determines whether to update the read receipt time for all channel members when `message.timestamp` of the latest migrated message is later than their read receipt time. If set to `true`, the unread message count for all channel members are updated as well. (Default: `false`) * This property can be used only when the target channel for migration is a group channel.
sorted_metaarray	array of objects	An array of JSON objects consisting of key-values items to store additional message information which can be used for classification and filtering. When retrieving, items are sorted from the oldest to the newest. More details on what can be stored in this field are available here.

List of properties for file message

Properties

Required	Type	Description
messages[]	array of objects	Specifies a list of file messages to migrate into the channel.
(message).user_id	string	Specifies the ID of the user who sent the message. Note that this user should be registered to your Sendbird application in advance, or else an error occurs.
(message).message_type	string	Specifies the type of the message. The default value for a file message is `FILE`.
(message).url	string	Specifies the URL of the file which is hosted on the server of your own or other third-party companies.
(message).timestamp	long	Specifies the time when the message was sent in Unix milliseconds format. You can sort the messages based on this timestamp.
update_read_ts	boolean	Determines whether to update the read receipt time for all channel members when the `message.timestamp` of the latest message migrated is prior to their read receipt time. If set to `true`, the unread message count for all channel members are updated as well. (Default: `false`) * This property can be used only when the target channel for migration is a group channel.

Optional	Type	Description
(message).file_name	string	Specifies the name of the file.
(message).file_size	int	Specifies the size of the file.
(message).file_type	string	Specifies the media type of the file.
(message).thumbnails[]	array of strings or objects	Specifies an array of one or more URLs of the external thumbnail images that are generated from the image specified by the `message.url` property.
(message).require_auth	boolean	Determines whether the files and thumbnail images in a message are only accessible by users who are in the same channel. * For more information about how this property works, see the request body section of the send a message API.
(message).custom_type	string	Specifies a custom message type used for message grouping. The length is limited to 128 characters.
(message).custom_field	string	Specifies additional message information such as `JSON` formatted string.
(message).mentioned_user_ids[]	array of strings	Specifies an array of IDs of the users to mention in the message.
(message).dedup_id	string	Specifies a unique ID for the message created by another system. In general, this property is used to prevent the same message data from getting inserted when migrating the messages from another system to Sendbird server. If specified, the server performs a duplicate check using the property value. * If you include an existing `dedup_id` value of a previously migrated message in a request, the migration fails with a `400202` error.
rewind_read_ts	boolean	Determines whether to update the read receipt time for all channel members when the `message.timestamp` of the latest message migrated is later than their read receipt time. If set to `true`, the unread message count for all channel members are updated as well. (Default: `false`) * This property can be used only when the target channel for migration is a group channel.
sorted_metaarray	array of objects	An array of JSON objects consisting of key-values items to store additional message information which can be used for classification and filtering. When retrieving, items are sorted from the oldest to the newest. More details on what can be stored in this field are available here.

List of properties for admin message

Properties

Required	Type	Description
messages[]	array of objects	Specifies a list of admin messages to migrate into the channel.
(message).message_type	string	Specifies the type of the message. The default value for an admin message is `ADMM`.
(message).message	string	Specifies the content of the message.
(message).timestamp	long	Specifies the time when the message was sent in Unix milliseconds format. You can sort the messages based on this timestamp.
update_read_ts	boolean	Determines whether to update the read receipt time for all channel members when the `message.timestamp` of the latest message migrated is prior to their read receipt time. If set to `true`, the unread message count for all channel members are updated as well. (Default: `false`) * This property can be used only when the target channel for migration is a group channel.

Optional	Type	Description
(message).custom_type	string	Specifies a custom message type used for message grouping. The length is limited to 128 characters.
(message).is_silent	boolean	Determines whether to send a message without updating some of the channel properties. If a message is sent in a channel, with this property set to `true`, the channel's `last_message` is updated only for the sender while its `unread_message_count` remains unchanged for all channel members. Also, the message doesn't send a push notification to message receivers. If the message is sent to a hidden channel, the channel still remains hidden. (Default: `false`) * Once the value of this property is set, it can't be reverted.
(message).mentioned_user_ids[]	array of strings	Specifies an array of IDs of the users to mention in the message.
(message).data	string	Specifies additional message information such as custom font size or font type in JSON or other formats.
(message).dedup_id	string	Specifies a unique ID for the message created by another system. In general, this property is used to prevent the same message data from getting inserted when migrating messages from another system to Sendbird server. If specified, the server performs a duplicate check using the property value. * If you include an existing `dedup_id` value of a previously migrated message in a request, the migration fails with a `400202` error.
rewind_read_ts	boolean	Determines whether to update the read receipt time for all channel members when the `message.timestamp` of the latest message migrated is later than their read receipt time. If set to `true`, the unread message count for all channel members are updated as well. (Default: `false`) * This property can be used only when the target channel for migration is a group channel.
sorted_metaarray	array of objects	An array of JSON objects consisting of key-values items to store additional message information which can be used for classification and filtering. When retrieving, items are sorted from the oldest to the newest. More details on what can be stored in this field are available here.

Request body example

{
    "messages": [
        {
            "message_type": "MESG",
            "user_id": "Danielle",
            "message": "Let's have some fun!",
            "sorted_metaarray": [
                {
                    "key": "design",
                    "value": ["A", "B", "C"]
                }
            ],
            "custom_type": "notification",
            "mentioned_user_ids": ["Ki-eun", "Blair", "Jeff"],
            "timestamp": 1543420803841
        },
        {
            "message_type": "FILE",
            "user_id": "Blair",
            "url": "https://sendbird.com/main/img/emoji/smile_0012.jpg",
            "file_name": "Grinning Face with Big Eyes",
            "file_size": 256,
            "sorted_metaarray": [
                {
                    "key": "design",
                    "value": ["A", "B", "C"]
                }
            ],
            "timestamp": 1543420803934
        },
        {
            "message_type": "ADMM",
            "message": "James entered the room.",
            "sorted_metaarray": [
                {
                    "key": "design",
                    "value": ["A", "B", "C"]
                }
            ],
            "custom_type": "admin_welcome",
            "data": "invited by Danielle",
            "timestamp": 1543420804308
        }
    ],
    "update_read_ts": false,        // The update_read_ts can be used only when
                                    // the target channel for migration is a group channel.
}

Response

If successful, this action returns an empty response body.

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

On this page

HTTP request Parameters Request body Response