Mesibo Real-time APIs - File Transfer and Hosting

As described in previous sections, mesibo allows you to send and receive rich messages with any arbitrary file (image, audio, video, doc, etc) in real-time.

By default, all media and files you send are stored on the mesibo file server. However many mesibo users, especially those having sensitive data (financial institutes, healthcare, dating, etc.) prefer to store files on their servers. We also recommend that you should use the mesibo server only for initial development and use your own servers for deployment.

mesibo offers you the flexibility to store all media and files on your servers including private servers or cloud services like Amazon Web Services, Google Cloud Storage, Microsoft Azure, etc. When you choose to store files on your servers, mesibo does not know how and where you store your files. Hence you must assist mesibo in uploading and downloading files to your server.

There are two ways you can program mesibo to send files to your servers:

Option 1: Setup Upload URL

You can set up an upload URL and a random authentication token by calling setUploadUrl. Mesibo will use this URL to upload the files instead of uploading to the mesibo file server.

void setUploadUrl(Strng url, String authToken);

setUploadUrl takes the following parameters:

For example,

Mesibo.setUploadUrl("https://your-server.com", authenticationToken); 

Mesibo will upload the file to this URL along with the following form parameters:

Your server should respond with JSON data having the result and the url, for example,

{"result": true, "url": "https://example.com/file.jpg" }

Option 2: Setup File Transfer Handler (Android and iOS)

In case, setting up an upload URL does not meet your requirements, you can customize the POST data or handle upload and download entirely by yourself by implementing upload and download handler functions in FileTransferHandler, which is called by mesibo real-time API whenever it needs to upload or download files from your servers.

The following FileTransferHandler functions will be called by mesibo whenever API needs to store or download files.

• The function Mesibo_onStartFileTransfer is called when mesibo wants your app to start a file transfer.
• The function Mesibo_onStopFileTransfer is called when mesibo wants your app to stop a file transfer.

Mesibo_onStartFileTransfer

Mesibo will call this function with MesiboFileTransfer in your file transfer handler whenever it needs to upload or download files.

boolean Mesibo_onStartFileTransfer(MesiboFileTransfer file) {
    if(file.upload) {

	// Upload a file to your server
	your_upload_function();

	return true;
    }

    // Download a file from your server
    your_download_function();

    return true;
}

Your file handler function should return true if the transfer started successfully. You can delay the transfer by returning false, for example, when multiple downloads are already in progress. Mesibo will try again later when messages are read again. Mesibo API sets various properties in the MesiboFileTransfer object which you can use in the upload or download process. You can also use these properties to decide if the transfer is to be started immediately or later based on priority, origin (real-time or database), message age, etc.

If mesibo needs to upload a file, it will pass the file path which you need to upload. Once the upload is complete, you need to let mesibo know about the URL where that file can be accessed from.

If mesibo needs to download a file, it will pass the file URL to download and the file path where you need to save it.

The following are MesiboFileTransfer properties and functions:

Seting File Transfer Results

Once the requested operation (upload or download) completes successfully, you need to call file.setResult to know mesibo about the file transfer. If uploading, you need to inform mesibo API about file URL.

file.setResult(true, "https://your-server.com/file-123.jpg");

For download, you do not need to pass the URL.

file.setResult(true);

If upload or download fails, inform mesibo of the result false

file.setResult(false);

Note that, since you are handling file transfer yourself, there is no fixed response format (like Option-1 above) and it is up to you how you communicate with your server and how your server responds. All you need to ensure is that you inform mesibo about the result using file.setResult as shown above.

Notify File Transfer Progress to Mesibo API and App

As the file is uploading or downloading, you can update mesibo with the progress by calling setProgress. In turn, mesibo will invoke the listener Mesibo_onMessageUpdate which can be used in your UI to show progress, for example, to display a spinner or a progress bar to show that the file is uploading.

file.setProgress(30);

Delegating file transfer to mesibo

This is similar to Option-1 discussed above but you can customize the POST bundle and then ask mesibo API to initiate the file transfer instead of handling it yourself.

file.start(url, post);

Since this is the same as Option-1 but with a different request payload, the response format MUST be the same as described in Option-1 above.

Deferring the File Transfer

If your app is unable to transfer the file when Mesibo_onStartFileTransfer was called, your app can return false to defer the transfer. In that case, mesibo will initiate the transfer later when required.

You can also call cancel with the retry parameter false if you do not want mesibo to retry the file download during the app life cycle.

file.cancel(false);

Mesibo_onStopFileTransfer

Mesibo will call this function with MesiboFileTransfer in your file transfer handler if the file transfer needs to be aborted.

Generally, this function is called when some user action takes place (for example, to stop transfer), and hence it is highly recommended that you abort the file transfer when this function is called. If not, the user may find the functionality broken.

Sample File Transfer Handlers

You can download the sample file handler for Android and iOS from GitHub and modify it to suit your app.

• For Android,

  • In Javaopen_in_new

• For iOS,

  • In Swiftopen_in_new
  • In Objective-Copen_in_new

isFileTransferEnabled

Returns true if FileTransferHandler is implemented by the application

boolean Mesibo.isFileTransferEnabled();

isFileTransferEnabled does not take any parameters.