Chat SDKs iOS v4

Chat SDKs iOS

Chat SDKs

iOS

Version 4

Migrating to Sendbird

Sendbird provides convenient APIs to ensure a smooth transition of your chat services to Sendbird. Follow these essential steps to migrate your data from an existing provider or in-house solution. This process involves mapping your current data types to those supported by Sendbird.

1. Register users
Begin by migrating your users to the Sendbird system. Utilize the user creation API to register each user from your current chat solution to your Sendbird application.

2. Create a channel
Sendbird requires you to manually create a channel to house your messages. Sendbird Chat provides three types of channels:

Note: This step is crucial as channels are not automatically created for your data migration.

3. Migrate messages
Once your channels are set up, use the migrate message API to transfer your existing messages to Sendbird.

Note: The migrate message API allows a maximum of 100 messages per migration request. If you are migrating a large volume of data, contact Sendbird support to adjust migration rate limits for your application.

Register users

Before creating a channel or migrating messages, you must register your users with Sendbird. This process involves mapping your existing user data to Sendbird's user data structure.

Note: If you have plans to migrate users who are deactivated, you have to make a separate API call to deactivate the user after migrating.

HTTP request

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

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_id	string	Specifies a user's unique ID. Maximum length is 80 characters. * Do not use PII (Personally Identifiable Information) such as user email address, legal name, or phone number as it could jeopardize data security and privacy.
nickname	string	Specifies the user's nickname. Maximum length is 80 characters.
profile_url	string	Specifies the URL of the user's profile image. If left empty, no profile image is set for the user. Maximum length is 2,048 characters. If the `profile_url` property is specified, the `profile_file` property is not required. * Your application's domain filter filters out the request if the value of this property matches the filter's domain set.
profile_file	binary	Specifies the file of the user's profile image. An acceptable image is limited to a JPG, JPEG, or PNG file of up to 5 MB. When passing a file, you should send a multipart request. If the `profile_file` property is specified, the `profile_url` property is not required.

Optional	Type	Description
issue_access_token	boolean	Determines whether to create an access token for the user. If set to `true`, an access token will be generated and returned in the `access_token` field. This token must be passed to the Sendbird server when a user tries to connect. This should be set to `true` in all real-world apps. (Default: `false`)
metadata	nested object	Specifies a `JSON` object to store up to five key-value items for additional user information such as their preference settings. The key must not have a comma (,), and the value must be a string. * If you're making a multipart request to upload the user's profile image, you need to call a separate user metadata API to add metadata to the user. * Do not use PII (Personally Identifiable Information) such as user email address, legal name, or phone number as it could jeopardize data security and privacy.
~~issue_session_token~~	boolean	*(Deprecated)* Determines whether to create a session token for the user. If set to `true`, an opaque string token is issued and provided upon creation, which should be passed whenever the user logs in. If set to `false`, a session token isn't required when the user logs in. (Default: `false`) * This property is deprecated and we encourage you to issue session tokens with the new `/users/{user_id}/token` endpoint for all Sendbird applications.
~~session_token_expires_at~~	long	*(Deprecated)* Specifies the time for the issued session token to expire in Unix milliseconds format. The length should be 13. If a value of this property is not specified and the `issue_session_token` property above is set to `true`, the value of this property is set to the sum of the current timestamp and `604800000` by default, meaning seven days starting from the current timestamp. * This property is deprecated and we encourage you to use the `expires_at` property instead for all Sendbird applications when issuing session tokens with the new `/users/{user_id}/token` endpoint.

Request body example

{
    "user_id": "Jacob",
    "nickname": "Asty",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
    "issue_access_token": true,
    "session_token_expires_at": 1542945056625,
    "metadata": {
        "font_preference": "times new roman",
        "font_color": "black"
    }
}

Responses

If successful, this action returns a user resource in the response body.

Status: 200 OK

{
    "user_id": "Jacob",
    "nickname": "Asty",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
    "access_token": "07a0ccf6d3e801223e65b06b6066352e0512b43c",
    "is_online": false,
    "is_active": true,
    "is_created": true,
    "phone_number": "",
    "require_auth_for_profile_image": false,
    "session_tokens": [],
    "last_seen_at": -1,
    "discovery_keys": ["123-456-7890", "654-321-0987"],
    "preferred_languages": [],
    "has_ever_logged_in": false,
    "metadata": {
        "font_preference": "times new roman",
        "font_color": "black"
    }
}

Error

In the case of an error, an error object like below is returned. See the error codes section for more details.

Status: 400 Bad Request

{
  "message":"\\"user_id\\" violates unique constraint.",
  "code":400202,
  "error":true
}

Create channels

After you have migrated your users you will need to migrate your channels. Sendbird has three types of channels: open, group, and supergroup channels.

Note: If you have frozen channels or read-only channels, you need to freeze the channel after migrating.

Creating an open channel

The following is an API implementation to create an open channel.

HTTP request

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

Request body

The following table lists the properties of an HTTP request that this action supports.

Optional

Property name	Type	Description
name	string	Specifies the channel topic, or the name of the channel. The length is limited to 191 characters. (Default: `open channel`)
channel_url	string	Specifies the URL of the channel. Only numbers, letters, underscores, and hyphens are allowed. The allowed length is 4 to 100 characters, inclusive. If not specified, a URL is automatically generated.
cover_url	string	Specifies the URL of the channel's cover image. The length is limited to 2,048 characters.
cover_file	file	Uploads a file for the channel's cover image.
custom_type	string	Specifies the custom channel type which is used for channel grouping. The length is limited to 128 characters. * Custom types are also used within Sendbird's Advanced analytics to segment metrics as channel metrics can be grouped by channel custom type.
data	string	Specifies additional channel information such as a long description of the channel or `JSON` formatted string.
is_ephemeral	boolean	Determines whether to preserve messages in the channel to later retrieve the chat history. If set to `true`, messages in the channel aren't saved in the Sendbird database and chat history can't be retrieved. (Default: `false`)
is_dynamic_partitioned	boolean	Determines whether the channel to be created is an open channel based on a dynamic partitioning structure. The value of `true` indicates that the open channel can create several subchannels in order to accommodate a massive number of users. This property is set to `true` by default for Sendbird applications created after December 15, 2020.
operator_ids[]	array of strings	Specifies an array of user IDs to register as operators of the channel. The maximum number of operators allowed per channel is 100. Operators can delete any messages in the channel and receives all messages that have been throttled. * Operators can't view messages that have been moderated by the domain filter or profanity filter. Only the sender will be notified that the message has been blocked.
~~operators[]~~	array of strings	*(Deprecated)* Specifies the string IDs of the users registered as channel operators. Operators can delete any messages in the channel and even receive all messages that have been throttled.

Note: If you want to upload a profile picture by passing an image file instead of a URL, see Multipart requests.

Request body example

{
    "name": "Live streaming show on channel 5!",
    "channel_url": "monday_channel_5_at_10_pm",
    "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
    "data": "{event_trigger:100,500,1000,2000}",
    "operator_ids": ["Alek", "Leslie"],
    "custom_type": "Live"
}

Responses

If successful, this action returns an open channel resource in the response body.

Status: 200 OK

{
    "name": "Live streaming show on channel 5!",
    "channel_url": "monday_channel5_at_10_pm",
    "custom_type": "live",
    "is_ephemeral": false,
    "participant_count": 0,
    "max_length_message": 5000,
    "created_at": 1484787758,
    "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
    "data": "{event_trigger:100,500,1000,2000}",
    "operators": [
        {
            "user_id": "Alek",
            "nickname": "Alexander the Great",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
        },
        {
            "user_id": "Leslie",
            "nickname": "Crystal",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_27_512px.png"
        }
    ],
    "freeze": false
}

Error

In the case of an error, an error object like below is returned. See the error codes section for more details.

Status: 400 Bad Request

{
    "message": "Invalid value: \"channel_url. It takes only alphabets, numbers, hyphen and underscore.\".",
    "code": 400111,
    "error": true
}

Creating a group channel

The following is an API implementation to create a group channel.

HTTP request

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

Request body

The following table lists the properties of an HTTP request that this action supports.

If you are creating a 1-to-1 direct messaging channel, it is recommended that you set the value of is_distinct to true. If is_distinct is set to false, a new channel is created even for users with shared chat history and all previous conversations will be lost. On the other hand, if the is_distinct property is set to true, no new channel is created for users with shared chat history, and every 1-to-1 conversation between the same two users will continue in the existing channel.

Properties

Required	Type	Description
users	array of objects	Specifies an array of one or more user objects to invite to the channel. Up to 100 users can be invited at a time. Specify a value for either `user_ids` or `users`.

Optional	Type	Description
user_ids	array of strings	Specifies an array of one or more IDs of users to invite to the channel. Up to 100 users can be invited at a time. Specify a value for either `user_ids` or `users`.
name	string	Specifies the name of the channel, or the channel topic. The length is limited to 191 characters. (Default: `group channel`)
channel_url	string	Specifies the URL of the channel. Only numbers, letters, underscores, and hyphens are allowed. The allowed length is 4 to 100 characters, inclusive. If not specified, a URL is automatically generated.
cover_url	string	Specifies the URL of the channel's cover image. This should be no longer than 2,048 characters.
cover_file	file	Uploads an image file of your choice to be used as the channel's cover image. If you want to upload a picture by passing an image file instead of a URL, see Multipart requests.
custom_type	string	Specifies a custom channel type which is used for channel grouping. Maximum length is 128 characters. * Custom types are also used when viewing data with Sendbird's Advanced analytics, as data can be grouped by their custom type.
data	string	Additional channel information such as a long description of the channel or `JSON` formatted string. More detail on what can be stored in the data field is available here.
is_distinct	boolean	Determines whether to reuse an existing channel or create a new channel when attempting to create a channel with the same group of members. By default, a new channel is created even if one already exists for the same members. You can override this and force an existing channel to be returned by setting a value of `is_distinct` to `true`. You can also reuse channels if the new channel has the same members, and the same `custom_type`, or create an entirely new channel if there are the same members but had a different `custom_type`. (Default: `false`) * You can also use this property in conjunction with `custom_type` and `user_ids` to create distinct channels for a specified channel custom type and group of users. To enable this functionality, visit this page and contact us on Sendbird Dashboard.
is_public	boolean	Determines whether to allow users to join the channel without an invitation. By default, a user must be invited to join a group channel. It is possible to allow any user to join a group channel without an invite by setting `is_public` to `true`. Public group channels are similar to open channels but include extra features like typing indicators and are limited to 100 members. (Default: `false`)
is_super	boolean	Determines whether to allow the channel to accommodate 100 or more members. By default, a group channel has a member limit of 100. A Supergroup channel must be used in order to have more than 100 channel members. A Supergroup channel has a member limit of 2000. A group channel can be created as a Supergroup channel by setting `is_super` to `true`. The `is_distinct` property must be `false` in order to create a Supergroup. (Default: `false`)
is_ephemeral	boolean	Determines whether to preserve messages in the channel for the purpose of retrieving chat history. By default, all chat messages will be stored by Sendbird. This means that chat histories can easily be retrieved when using the SDK or API. If `is_ephemeral` is set to `true` then no chat history is stored. In this case, the chat history can't be retrieved in the future. This option may be helpful for exceptional data privacy requirements. (Default: `false`)
access_code	string	Specifies an access code that is only applicable to public group channels. If a value is specified for `access_code`, users will be required to enter this code when joining a group channel. This parameter can only be used when the channel operator creates a public group channel. If specified, the `is_access_code_required` property of the channel resource is automatically set to `true`. (Default: `false`)
inviter_id	string	Specifies the ID of a user who invites other users to the channel. The inviter isn't automatically registered to the channel as a member, so you should specify the ID of the inviter in the `user_ids` property if needed.
strict	boolean	Determines whether to receive a `400111` error and cease channel creation when there is at least one user that doesn't exist in the specified `user_ids` or `users` property. Channel creation by default won't fail if a user passed to `user_ids` or `users` doesn't exist in the Sendbird application. Setting `strict` to `true` causes a `400111` error during creation if any users passed to `user_ids` or `users` haven't already been successfully created. (Default: `false`)
invitation_status	object	Specifies one or more key-value pair items which set the invitation status of each user invited to the channel. The key should be a `user_id` and the value should be their joining status. Acceptable values are `joined`, `invited_by_friend`, and `invited_ by_non_friend`. (Default: `joined`)
hidden_status	object	Specifies one or more key-value pair items which set the channel's hidden status for each user. The key should be a `user_id` and the value should be their hidden status. Acceptable values are: - `unhidden` (default): the channel is shown when a user's channel list is retrieved. - `hidden_allow_auto_unhide`: if a new message is sent to a hidden channel, the channel automatically reappears to a user's channel list. - `hidden_prevent_auto_unhide`: even if a new message is sent to a hidden channel, the channel remains hidden.
operator_ids[]	array of strings	Specifies an array of one or more IDs of users to register as operators of the channel. You should also include these IDs in the `user_ids` property to invite them to the channel as members. They can delete any messages in the channel, and also view all messages without any filtering or throttling. A channel may have up to 100 operators.
block_sdk_user_channel_join	boolean	Determines whether to block users from joining the channel through the Chat SDK. If set to `true`, users can only join the channel using the Sendbird Platform API join a channel action. (Default: `false`)

Request body example

{
    "name": "Saturday soccer members",
    "channel_url": "private_chat_room_424",
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "custom_type": "sports",
    "is_distinct": true,
    "user_ids": ["James", "Jay", "Jeff", "Young"],
    "operator_ids": ["Jeff"]
}

Responses

If successful, this action returns a group channel resource in the response body.

Note : The role property in each user resource under the member property indicates whether the user is a channel operator or a channel member.

Status: 200 OK

{
    "name": "Saturday soccer members",
    "channel_url": "private_chat_room_424",
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "custom_type": "sports",
    "unread_message_count": 0,
    "data": "",
    "is_distinct": true,
    "is_public": false,
    "is_super": false,
    "is_ephemeral": false,
    "is_access_code_required": false,
    "member_count": 4,
    "joined_member_count": 1,
    "unread_mention_count": 0,
    "created_by": {
        "user_id": "Jeff",
        "nickname": "OldBoy",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
        "require_auth_for_profile_image": false
    },
    "members": [
        {
            "user_id": "James",
            "nickname": "Knight",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_08_512px.png",
            "is_active": true,
            "is_online": false,
            "last_seen_at": 1530237133254,
            "state": "invited",
            "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "font_preference": "times new roman",
                "font_color": "black"
            }
        },
        {
            "user_id": "Jay",
            "nickname": "Rooster",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
            "is_active": true,
            "is_online": false,
            "last_seen_at": 1530232836311,
            "state": "joined",
            "role": "",         // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "font_preference": "times new roman",
                "font_color": "black"
            }
        },
        {
            "user_id": "Jeff",
            "nickname": "OldBoy",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
            "is_active": true,
            "is_online": true,
            "last_seen_at": 0,
            "state": "",
            "role": "operator",     // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "font_preference": "times new roman",
                "font_color": "gray"
            }
        },
        {
            "user_id": "Young",
            "nickname": "Sportsman",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_23_512px.png",
            "is_active": true,
            "is_online": true,
            "last_seen_at": 0,
            "state": "invited",
            "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "font_preference": "times new roman",
                "font_color": "black"
            }
        },
    ],
    "operators": [
        {
            "user_id": "Jeff",
            "nickname": "OldBoy",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
            "is_active": true,
            "is_online": true,
            "last_seen_at": 0,
            "state": "",
            "metadata": {}
        }
    ],
    "last_message": null,
    "message_survival_seconds": -1,
    "max_length_message": 5000,
    "created_at": 1543468122,
    "freeze": false,
    "channel": {
        ...  # This key has been deprecated and only exists for backward compatibility.
    }
}

Transfer messages

The final stage of migration is to migrate your messages to Sendbird. Sendbird has three message types: User Message, File Message, and Admin Message. Each request can migrate 100 messages to a given channel.

See the Migrate messages page for API details.

On this page

Creating an open channel Creating a group channel

Transfer messages

Sample app