Chat iOS v4
Chat iOS
Chat
iOS
Home
/
Chat
/
iOS
/
Open channel
This is the new Docs for Chat SDK v4 beta for iOS. To see the previous Docs, click here.

Open channel: Advanced

This page explains the advanced features for open channels.


Send an admin message

You can send an admin message to an open channel on the Sendbird Dashboard or through Chat Platform API. To send the admin message through your dashboard, go to Chat > Open channels, select an open channel from the list, find a message box at the bottom of the page, click the Admin message tab, and then write your message. An admin message is limited to 1,000 characters.


Add extra data to a message

You have the option to create further actions in a channel by using extra data in a message. You can add one or more key-values items to a message which you can save, update, or remove, when necessary. Based on those items, you can design and implement several different actions such as measuring user engagement within a chosen time limit through polls or counting how many times a message has been copied by participants.

Note: For the quality of performance, every Sendbird application has its own limits to how many key-values items you can add to a single message, as well as the maximum number of values an item can have. If you would like more information on these limits, contact our sales team.

// When a message has been successfully sent to a channel,
// create a map of keys.
openChannel.createMessageMetaArrayKeys(message: MESSAGE, keys: ["referees", "games"]) { message, error in
    guard error == nil else {
        return // Handle error.
    }
}

// Then add values to those keys.
let valuesToAdd = [
    "referees": ["John", "Brandon", "Harry", "Jay"],
    "games": ["soccer", "baseball", "basketball"]
]

openChannel.addMessageMetaArrayValues(message: MESSAGE, keyValues: valuesToAdd) { message, error in
    guard error == nil else {
        return // Handle error.
    }
}

// You can remove the existing values of specific items
// by specifying their keys.
let valuesToRemove = [
    "referees": ["Brandon", "Jay"]
]

openChannel.removeMessageMetaArrayValues(message: MESSAGE, keyValues: valuesToRemove) { message, error in
    guard error == nil else {
        return // Handle error.
    }
}

// Delete items by specifying their keys.
openChannel.deleteMessageMetaArrayKeys(message: MESSAGE, keys: ["referees", "games"]) { message, error in
    guard error == nil else {
        return // Handle error.
    }
}

To get the key-values items of a message, read message.metaArrays.


Display Open Graph tags in a message

The Chat SDK supports the URL link preview when a message text contains the URL of a web page.

Note: This feature is turned on by default for Sendbird applications. If this isn't available for your Sendbird application, visit this page and contact us on the Sendbird Dashboard.

OGMetaData

If a BaseMessage object includes a valid URL of a website, the object can contain OGMetaData, a class that holds OG metadata information such as title, URL, description, and default image of an OG object.

Note: Some websites don’t provide the OG metadata. In that case, even though the OG protocol states them as requirements, all of the four properties can be null.

List of properties

Property nameDescription

title

The title of the OG object as it should appear within the graph. The value can be null.

url

The canonical URL of the object that can be used as its permanent ID in the graph. The value can be null.

desc

The description of the object. The value can be null.

defaultImage

An OGImage instance that contains information about the image that the Open Graph points to. OGImage also holds its own properties such as type, URL, and size. However, the value can be null.

OGImage

A OGImage instance, the image contained in a OGMetaData object, holds image-related data for the OGImage object. OGImage can also have its own optional structured properties of URL, secure URL, type, width, height, and alt.

Note: Except for width and height, other fields such as URL, secure URL, type, and alt can be null. If the target website doesn’t provide width and height data, the value of those two fields are set to 0.

List of properties

Property nameDescription

url

The URL of an image object within the Open Graph. The value can be null.

secureUrl

An alternative URL to use if the webpage requires HTTPS. The value can be null.

type

A media type or MIME type of this image. The value can be null.

width

The number of pixels horizontal. When the value is unavailable, this method returns 0.

height

The number of pixels vertical. When the value is unavailable, this method returns 0.

alt

The description of what is in the image, not a caption of the image. The alt attribute is designed to provide a fuller context of the OGImage object and help users better understand it when they can’t load or see the image. The value can be null.

How it works

If a user sends a message with a web page URL and the linked web page possesses Open Graph (OG) tags, or OG metadata, Sendbird server parses the message content, extracts the URL in the message, gets the OG metadata from it, and creates an OG metadata object for the message. Then message recipients will get the parsed message with its OG metadata through the didReceiveMessage: method in the channel event delegate of the SDK. On the other hand, the message sender will do the same through didUpdateMessage:.

Displaying an OG metadata object is available for two subtypes of BaseMessage: UserMessage and AdminMessage. If the content of either a UserMessage or AdminMessage object includes a web page URL containing OG metadata, the didReceiveMessage: method returns OGMetaData and OGImage objects.

If Sendbird server doesn’t have cache memory of the OG metadata of the given URL, BaseMessage.ogMetaData can be null due to the time it takes to fetch the OG metadata from a remote web page. In the meantime, the message text containing the URL will be delivered first to message recipients’ client app through the channel(_:didReceive:) method. When the server completes fetching, the didUpdateMessage: method will be called and the message with its OGMetaData object will be delivered to the recipients’ client app. However, if Sendbird server has already cached the OG metadata of the URL, BaseMessage.ogMetaData returns the message and its OGMetaData object instantly and the didUpdateMessage: method won’t be called.

// Send a user message containing the URL of a web page.
var params = UserMessageCreateParams()
params.message = "sendbird.com"


openChannel.sendUserMessage(params: params) { userMessage, error in
    guard error == nil else {
        return // Handle error.
    }
}

// ViewController.swift
// Receive a user message containing OG metadata of the web page
// through a channel event delegate.
func channel(_ channel: BaseChannel, didReceive message: BaseMessage) {
    if message.ogMetaData != nil {
        // You can create and customize the URL link preview
        // by using the Open Graph metadata of the message.
        let url = message.ogMetaData.url
        let width = message.ogMetaData.width
    } else {
        // If the message.ogMetaData is nil,
        // wait until the didUpdate method receives a callback from the Sendbird server.
    }
}

func channel(_ channel: BaseChannel, didUpdate message: BaseMessage) {
    if message.ogMetaData != nil {
        // You can create and customize the URL link preview
        // by using the Open Graph metadata of the message.
        let url = message.ogMetaData.url
        let width = message.ogMetaData.width
    }
}

Categorize channels by custom type

When creating an open channel, you can additionally specify a custom channel type to subclassify open channels. This custom type takes on the form of String, and can be useful in searching or filtering open channels.

The data and customType properties of a channel object allow you to append information to your channels. While both properties can be used flexibly, common use cases for customType include labeling open channels as School or Work to categorize them.

let params = OpenChannelCreateParams()
params.name = CHANNEL_NAME
params.coverURL = COVER_URL
params.data = DATA
params.customType = CUSTOM_TYPE
params.addOperators(OPERATOR_USERS)

OpenChannel.createChannel(params: params) { (openChannel, error) in
    guard error == nil else {
        return // Handle error.
    }
})

To get a channel's custom type, read openChannel.customType.


Categorize messages by custom type

When sending a message, you can additionally specify a custom message type to subclassify messages. This custom type takes on the form of String, and can be useful in searching or filtering messages.

The data and customType properties of a message object allow you to append information to your messages. While both properties can be used flexibly, common use cases for customType include labeling messages as Contract or Notes to categorize them.

To embed a custom type into your message, assign a value to customType under the UserMessageCreateParams or FileMessageCreateParams object. Then, pass the specified object as an argument to the parameter in the sendUserMessageWithParams:completionHandler: or sendFileMessageWithParams:completionHandler: method.

var params = UserMessageCreateParams()
params.message = MESSAGE
params.customType = CUSTOM_TYPE

openChannel.sendUserMessage(params: params) { userMessage, error in
    guard error == nil else {
        return // Handle error.
    }
}

To get a message's custom type, read message.customType.


Search channels by name, URL, or custom type

You can search for specific open channels by adding keywords to a OpenChannelListQuery instance. There are two types of keywords: Name and URL. The code sample below shows the query instance which returns a list of open channels that partially match the specified Name keyword in the names of the channels.

let listQuery = OpenChannel.createOpenChannelListQuery()
listQuery.channelNameFilter = "Sendbird"

listQuery.loadNextPage { openChannels, error in
    guard error == nil else {
        return // Handle error.
    }

    // Through the openChannels parameter of the callback method,
    // which the Sendbird server has passed a result list to,
    // a list of open channels whose name partially matches
    // with the filter value is returned.
}

The following shows the query instance which returns a list of open channels that partially match the specified URL keyword in the URLs of the channels.

let listQuery = OpenChannel.createOpenChannelListQuery()
listQuery.channelURLFilter = "seminar"

listQuery.loadNextPage { openChannels, error in
    guard error == nil else {
        return // Handle error.
    }

    // Through the openChannels parameter of the callback method,
    // which the Sendbird server has passed a result list to,
    // a list of open channels whose URL partially matches
    // with the filter value is returned.
}

Using setCustomTypeFilter: like the following, you can also search for open channels with a specific custom type.

let listQuery = OpenChannel.createOpenChannelListQuery()
listQuery.customTypeFilter = "movie"

listQuery.loadNextPage { openChannels, error in
    guard error == nil else {
        return // Handle error.
    }

    // Through the openChannels parameter of the callback method,
    // which Sendbird server has passed a result list to,
    // a list of open channels whose custom type matches
    // with the filter value is returned.
}

Generate thumbnails of a file message

When sending an image file, you can determine whether to create thumbnails of the image to fetch and render into your UI. You can specify up to 3 different dimensions to generate thumbnail images in for supporting various display densities.

Note: Files whose media type is image/* or video/* are supported. The Chat SDK doesn't support creating thumbnails when sending a file message with a file URL.

The sendFileMessage(params:completionHandler:) method requires passing a FileMessageCreateParams object as an argument to a parameter. The params contains Array of ThumbnailSize objects which specify the maximum values of width and height of each thumbnail image with make(maxSize:) or make(maxWidth:maxHeight:) constructors. The completionHandler: callback subsequently returns the Array of Thumbnail objects that each contain the URL of the generated thumbnail image file.

var thumbnailSizes = [ThumbnailSize]()

// Create and add a ThumbnailSize object.
// 3 thumbnail images are allowed.
thumbnailSizes.append(ThumbnailSize.make(maxSize: CGSize(width: 100.0, height: 100.0)))
thumbnailSizes.append(ThumbnailSize.make(maxWidth: 200.0, maxHeight: 200.0))

var params = FileMessageCreateParams(file: FILE)

params.fileName = FILE_NAME
params.fileSize = FILE_SIZE
params.mimeType = MIME_TYPE
params.thumbnailSizes = thumbnailSizes  // Set a ThumbnailSize object to a FileMessageCreateParams object.

openChannel.sendFileMessage(params: params) { fileMessage, error in
    guard error == nil else {
        // Handle error.
    }

    let first = fileMessage?.thumbnails?[0]
    let second = fileMessage?.thumbnails?[1]

    let maxSizeFirst = first?.maxSize   // 100
    let maxSizeSecond = second?.maxSize // 200

    let urlFirst = first?.url
    let urlSecond = second?.url
}

A thumbnail image is generated evenly to fit within the bounds of maxWidth and maxHeight, which are provided through the constructor. Note that if the original image is smaller than the specified dimensions, the thumbnail isn't resized. The url returns the location of the generated thumbnail file within Sendbird server.


Share an encrypted file with other participants

This file encryption feature prevents users without access from opening and reading encrypted files that have been shared within a group of users. When this feature is turned on, all types of sent files and thumbnail images will be first uploaded to Sendbird server, and then encrypted by AES256.

In an open channel, encrypted files and thumbnail images will be decrypted and accessed securely only by the participants. Anyone outside of the channel and application will not have access to those files and thumbnail images. The following explains how this data security works and what to do at the SDK level to apply it to your client apps.

The Sendbird system enables secure encryption and decryption of files by generating and distributing an opaque and unique encryption key for each user. An encryption key is managed internally by the system, and is valid for three days. It is generated every time the user logs in to Sendbird server through the Chat SDK, which then gets delivered to the Chat SDK from the server.

When the Chat SDK requests an encrypted file by its URL, the auth parameter should be added to the URL to access the file, which is specified with an encryption key of the user such as ?auth=RW5jb2RlIHaXMgdGV4eA==. With the specified key in auth, Sendbird server first decrypts the file, then checks if the user is participating in the open channel, and finally, allows the user to access and open the file in the channel.

This can be easily done by retrieving the fileMessage.url property, which returns the unique file URL containing the auth parameter with an encryption key of the current user.


Spam flood protection

This feature allows you to customize the number of messages a participant can send in an open channel per second. By doing so, all excess messages from a participant will be deleted and only the number of messages allowed to be sent per participant per second will be delivered. This feature protects your app from some participants spamming others in the channel with the same messages.

Note: Our default system setting is 5 messages per second. This limit can be manually adjusted only from our side. Contact our sales team for more information.


Smart throttling

You can use this feature to customize the number of messages displayed in an open channel per second. By doing so, you can adjust the pace of the conversation in a chat so that the participants can read the messages more clearly. In fact, each participant's channel will display the messages they have sent and those that other participants have sent up to this limit in chronological order.

Note: Our default system setting is five messages per second. This limit can be manually adjusted only from our side. Contact our sales team for more information.


Message auto-translation

It is possible for text messages to be sent in different languages through the Sendbird's auto-translation feature. When sending a text message, set Array of language codes to a UserMessageCreateParams object and then pass the object as an argument to a parameter in the sendUserMessage(params:completionHandler:) method to request translated messages in the corresponding languages.

Note: Message auto-translation is powered by Google Cloud Translation API recognition engine. Find language codes supported by the engine in the Miscellaneous page or visit the Language Support page in Google Cloud Translation.

var params = UserMessageCreateParams()
params.targetLanguages = ["es", "ko"]   // Spanish and Korean

openChannel.sendUserMessage(params: params) { userMessage, error in
    guard error == nil else {
        // Handle error.
    }
}

You can retrieve translations of a text message using the userMessage.translations property which has a Array object containing the language codes and translations.

func channel(_ channel: BaseChannel, didReceive message: BaseMessage) {
    if let message = message as? UserMessage {
        let esTranslatedMessage = message.translations["es"]    // Spanish

        // Show translations in UI.
    }
}

Message on-demand translation

Using the translateUserMessage(_:targetLanguages:completionHandler:) method, you can also translate an already sent text message into other languages for your specific needs.

Note: Message on-demand translation is powered by Google Cloud Translation API recognition engine. Find language codes supported by the engine in the Miscellaneous page or visit the Language Support page in Google Cloud Translation.

let targetLanguages = ["es", "de"]

// The USER_MESSAGE argument below indicates a UserMessage object
// which represents an already sent or received text message.
openChannel.translateUserMessage(USER_MESSAGE, targetLanguages: targetLanguages) { userMessage, error in
    guard error == nil else {
        // Handle error.
    }

    let translations = (userMessage as! UserMessage).translations
    let esTranslatedMessage = translations["es"]    // Spanish
    let deTranslatedMessage = translations["de"]    // German

    // Show translations in UI.
}

Based on this method, you can implement features such as real-time or instant translation to your app. You can also implement to only translate a selected message into preferred languages.