Table of Contents

Designing message objects in Sendbird Chat

Designing message objects in Sendbird Chat

Jason Allshorn
Solutions Engineer
Tutorial Type: Basic Reading Time: 10 mins Building Time: 20 mins
ChatAndroidiOSJSSDK

Introduction

With Sendbird, sending and receiving messages is easy. Designing your own message objects to get the look and feel you want, however, can be a lot of work. Fortunately, we have a lot of experience helping customers get the results they’re looking for. In this guide, read about just a few of the numerous ways you can use Sendbird’s Message objects to their full potential.

We’ll cover how to:

  • Send video files
  • Send GIFs
  • Create thumbnails

Let’s get started!

Sending video files

Sendbird’s file-upload service allows for any data files to be uploaded and stored in Sendbird. FILE messages can store URL links to both internal and external data. Here’s what you need to know to upload and handle videos for Android, iOS, or Javascript.

File upload size limitations

If you upload a file directly to Sendbird, there’s a size limit per file, depending on your Sendbird plan. If you upload a file that exceeds the limit, you’ll see an error such as:
Maximum file size for uploading is 25Mb. Code = 400111.

Note that if you send the file message with an external URL — such as YouTube or Vimeo — there’s no size limit in Sendbird.

To see what your plan allows, visit your Sendbird dashboard. If you need a higher size limit, contact the Sendbird sales team.

Thumbnails

If your application uses Sendbird Premium thumbnail-generation tool, you have the option of generating thumbnails for your videos. Automatically generated thumbnails are small, static images taken from uploaded videos only. Thumbnails will not be created from externally linked videos.

Moderation

At the moment Sendbird’s moderation tools do not apply to video files.

User experience considerations

Async nature of Sendbird’s FILE messages
The larger the video file, the longer it takes to send Sendbird FILE messages with the actual file data. But when a FILE message is received, it’s received at the same speed as a regular user message, because a received FILE message contains a URL link to the file — not the actual file data.

UX implementation considerations for large files
For large file uploads, consider providing a progress indicator in your UI. Sendbird has progress handlers that increment from 0.0 to 1.0 as the multipart upload progresses (iOS, Android, Javascript). Once the upload is finished, the progress indicator reads 1.0.

Also consider the server-side processing time, such as thumbnail generation. You can hide the file-upload indicator and display an activity spinner while waiting for the FILE message callback. Once Sendbird’s server-side operations are complete, the file message callback will return a successful message object or an error message.

Here’s the suggested order of operations in Swift:

Loss of internet connection
Once sendFileMessage() has been called, the Sendbird’s SDK Connection Manager will:

  • Automatically keep watch over the file upload
  • Watch for times when the internet goes off [b]for short periods
  • Automatically continue to send the file when the internet returns
  • Reset the connection manager every time the internet comes back

As long as the total disconnection is not longer than 45 seconds, the Sendbird SDK will continue to try to send the video file data. This cycle will continue infinitely, except for the iOS SDK, which will time out and stop the upload after five minutes from when the first part of the file was successfully sent.

If the Connection Manager’s event handler fires onReconnectFailed(), all attempts to upload the file will stop and the sendFileMessage callback will return the error message:

File upload timeout error

From within the onReconnectFailed() handler, consider indicating to the user that the connection has been lost and either automatically try calling sendbird.reconnect() or offer the user the option to manually call sendbird.reconnect(). Once reconnected, consider offering the user the option to retry sending the FILE message.

Should the user lock the screen or move the app into the background once a file upload has begun, the file upload process will continue as long as there is an internet connection.

Oversize video files
Think about the user experience if a user attempts to send a file message larger than the file size limit set in your Sendbird plan. By default, that maximum file size is 5MB. If your maximum file size is predetermined, consider calculating the file size before the user attempts to send the file. Warn the user if the video file is oversized.

Sendbird’s server sends an error should the attempted file upload exceed the maximum allowed limit, for instance:

Maximum file size for uploading is 25MB. Code = 400111.

The warning message triggers only once uploading is finished. For iOS, consider setting the SBDOptions.setFileTransferTime(300). Doing this will prevent the device from timing out a large upload.

Should the user wish to cancel the upload at any time, they can do so using the cancelUploadingFileMessage(). (iOS, Android, JavaScript)
Uploading video files using a Sendbird FILE message
See the following directions for each operating system:

Video FILE message object
GIF file message example object (including the optional static thumbnails):

Handling video files in messages
Consider how you will inform the user that they have a message which contains a video file. In the sample FILE message object above, there is a field file.type. When delivering video to the user, it’s possible to allow for downloading and playing at the same time or require the file to fully download before it plays. Use the following Sendbird samples to learn how to implement the handling of file messages within videos:

Sending GIFs

Sendbird’s file upload service allows for any data files to be uploaded and stored in Sendbird. Sendbird’s FILE messages store URL links to both internal and external data.

File upload size limitations

If you upload a file directly to Sendbird, there is a size limit per file, depending on your Sendbird plan. If you upload a file that exceeds the limit, you’ll see an error such as:

The maximum file size for uploading is 25MG. Code = 400111.

Note that if you send the file message with its URL, there’s no size limit in Sendbird.

To see what your plan allows, visit your Sendbird dashboard. If you need a higher size limit, contact the Sendbird sales team.

Thumbnails

If your application is using the Sendbird premium thumbnail-generation tool, you have the option of generating thumbnails for your files. Automatically generated thumbnails are small, static images of the GIFs.

Moderation

Sendbird’s image moderation feature works with GIF files. However, as can be seen, when using Google’s Vision API try-it tool, the time it takes for a GIF image to be processed is significantly longer than a regular image.

Uploading a GIF file using a Sendbird FILE message

GIF FILE message object
GIF file message example object, including optional static thumbnails:

Handling GIFs in messages

Here are some resources for the various operating systems.

iOS

Android

JavaScript

A swift example of sending a GIF FILE message:

An Android example, taken from Sendbird’s Android basic sample:

Creating thumbnails

For Premium members, Sendbird supports generation of thumbnails for videos and pictures of the file type image/^ or video/*.  When sending an image file, you can determine whether or not to create thumbnails of the image to render in your UI. You can specify up to three dimensions in which to generate thumbnail images, which can be convenient for supporting various display densities.

Here are some specifics about creating thumbnails for each operating system.

Android
The sendFileMessage() method requires that you pass a list of FileMessage.ThumbnailSize objects. Each object can be created with the ThumbnailSize constructor, where the provided values determine the pixels of the maximum dimensions. The onSent() callback subsequently returns a list of thumbnail objects that each contain the URL of the generated thumbnail image file.

Here’s a Java overview:

A thumbnail image is generated to fit evenly within the bounds of (maxWidth, maxHeight), which are provided through the ThumbnailSize constructor. Please note that if the original image is smaller than the specified dimensions, the thumbnail won’t be resized. getUrl() returns the location of the generated thumbnail file within the Sendbird server.

iOS

The sendFileMessage() method requires that you pass an NSArray of SBDThumbnailSize objects as a parameter. Each object can be created with the SBDThumbnailSize makeWithMaxCGSize or SBDThumbnailSize makeWithMaxWidth:maxHeight: constructors, where the provided values determine the pixels of a thumbnail’s maximum dimensions. The completionHandler: … : callback subsequently returns an NSArray of SBDThumbnail objects that each contain the URL of the generated thumbnail image file.

Swift overview:


Objective-C:

A thumbnail image is generated to fit evenly within the bounds of (maxWidth, 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 the Sendbird server.

JavaScript

The sendFileMessage() method requires that you pass an array of items which each contain the maximum values of width and height of a thumbnail image. The callback function subsequently returns a list of thumbnail items that each contain the URL of the generated thumbnail image file. This doesn’t contain ES6 syntax to ensure support for more browsers.

A thumbnail image is generated to fit evenly within the bounds of provided (maxWidth, maxHeight). 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 the Sendbird server.

Image upload timeout considerations
With a consistent network connection, image and video files will upload without issue. But it’s worth considering the following.

Image upload and Sendbird message rate limits
Consider the use case of adding multiple images in the form of an album. A key limitation of implementing such a feature with Sendbird is that sending any kind of message is limited to no more than five messages per second and one file per message. If you’re uploading multiple images, be careful not to exceed this limit.

Further implementation considerations
Consider using Sendbird’s file upload with progress handlers:

SendFileMessagesWithProgressHandler

And consider implementing a retry functionality for failed uploads.

Fetching and displaying thumbnail images
A Sendbird file message does not contain any image data. Instead, it contains URLs that reference images stored either in Sendbird or your own image-storage facility. If thumbnails are deployed, each thumbnail version will also have its own URL. Consider optimizations such as fetching the smallest thumbnail and then caching it with services such as Glide (in Android), NSCache (in iOS), and the Cache API Service Worker (in JavaScript).

Conclusion

Congratulations! Hopefully, completing this tutorial has immersed you in the practice of designing and using message objects. You are on to creating a really engaging chat experience for your users!

Happy coding!