Designing message objects in Sendbird Chat
Introduction
With Sendbird, sending and receiving messages is easy. (If you haven’t already, check out our docs to get started.) However, designing message objects and getting the look and feel you want can be a lot of work. In this guide, you can 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
To benefit from this guide, we recommend creating a free Sendbird account and setting up basic chat functionality before implementing what we cover in this guide. This will help you learn faster.
That being said, let’s get started!
Sending video files
First, let’s understand the details of sending video files. Sendbird’s file upload service allows any data files to be uploaded and stored in Sendbird. A message which contains file details has a Sendbird SDK message.type equal to FILE, henceforth known as FILE message. FILE messages can store URL links to both internal and external data.
Here’s what you need to know to upload and handle Android, iOS, or Javascript videos.
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 filesize 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 the 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
It’s important to understand that the time for sending and receiving FILE messages differs. The larger the video file, the longer it takes to send Sendbird FILE messages with the actual file data. However, 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 (this is for iOS, Android, and Javascript). Once the upload is finished, the progress indicator reads 1.0.
Also, consider the server-side processing time, such as for 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, Sendbird’s SDK Connection Manager will:
- Automatically keep watch over the file upload
- Watch for times when internet connectivity goes down 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 following 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 call sendbird.reconnect() manually. Once reconnected, consider offering the user the option to retry sending the FILE message. In most cases, Sendbird’s connection manager will infinitely try to reconnect. Therefore, listen for FILE message send failure in the sendFileMessage() callback.
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.
Oversized 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 25MB. 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.
Should the attempted file upload exceed the maximum allowed limit, Sendbird’s server sends an error. For instance:
Maximum file size for uploading is 25MB. Code = 400111.
The warning message triggers only after 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(). (this is for iOS, Android, and 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. There is a field called file.type in the sample FILE message object above. When delivering video to the user, the download and playback can be concurrent or the file can play after the download is complete. Use the following Sendbird samples to learn how to implement the handling of FILE messages within videos:
Sending GIFs
Now let’s talk about 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:
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 the 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 to generate thumbnail images, which can support 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, in which the provided values determine the pixels of the maximum dimensions. The onSent() callback subsequently returns a list of thumbnail objects containing the generated thumbnail image file URL.
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 the thumbnail won’t be resized, if the original image is smaller than the specified dimensions. getUrl() returns the location of the generated thumbnail file within the Sendbird server.
iOS
The sendFileMessage() method requires passing 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 containing 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 the thumbnail isn’t resized, if the original image is smaller than the specified dimensions. The URL returns the location of the generated thumbnail file within the Sendbird server.
JavaScript
The sendFileMessage() method requires passing an array of items containing the maximum values of width and height of a thumbnail image. The callback function subsequently returns a list of thumbnail items containing the URL of the generated thumbnail image file. This doesn’t include 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 the thumbnail isn’t resized if the original image is smaller than the specified dimensions. The URL returns the location of the generated thumbnail file within the Sendbird server.
Image upload timeout considerations
Image and video files will upload without issue with a consistent network connection. But it’s worth considering the following points:
Image upload and Sendbird message rate limits
Consider the use case of adding multiple images in the form of an album. A fundamental limitation of implementing such a feature with Sendbird is that sending any message is limited to 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 – JavaScript*, iOS, Android
*Note: JavaScript function deprecated in v4 documentation.
Also, consider implementing a retry functionality for failed uploads. A failed upload will provide an error in the FILE message completion/callback handler.
Fetching and displaying thumbnail images
A Sendbird FILE message does not contain any image data. Instead, it includes URLs that reference images stored in Sendbird or your 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! This guide has provided you with information on the practice of designing and using message objects. You are on to creating an engaging and fun chat experience for your users!
Happy in-app chat coding! ✌️
