Mesibo Real-time APIs - File Transfer and Hosting

Overview

Just like text messages, mesibo's real-time file transfer API allows you to send and receive any arbitrary file - images, videos, documents, audio files, and more - in real-time.

By default, all media and files are stored on mesibo's secure file servers, making it easy to get started quickly. However, many organizations - particularly those in regulated industries such as healthcare (HIPAA compliance), financial services, legal, government, and dating applications - require complete control over where and how their sensitive data is stored.

mesibo gives you the flexibility to host all media and files on your own infrastructure, or using cloud services like Amazon S3, Google Cloud Storage, Microsoft Azure, etc. We also recommend using mesibo's file servers for initial development and testing and then move to host your own so that you have complete control over all the files. This is also important when various compliance requirements such as HIPAA, GDPR, SOC 2, etc. are applicable. You can also create your custom workflows such as image processing, watermarking, etc.

How It Works

When you configure a custom file server, mesibo no longer stores your files. Instead, mesibo facilitates the secure transfer between clients and your servers:

1. Upload: When a user sends a file, mesibo provides authentication parameters to help your server verify the request. Your server stores the file and returns the file URL to mesibo
2. Download: When a recipient needs the file, mesibo requests it from your server with optional authentication parameters

Important: When using custom file hosting, you have complete control over authentication, security policies, access control, and storage management. While mesibo provides strong time-based authentication to prevent replay attacks, it is up to your server to reliably use them for complete privacy and security of your users' data. For example, your server may choose to authenticate uploads but not downloads

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

Option 1: Custom File Server Configuration

You can configure a custom file server URL in User Access Control (UAC) where mesibo clients will upload files.

Upload Parameters

mesibo will upload the file to your URL using a POST request with the following form parameters:

Upload Signature Generation

The signature is generated as follows:

sig = sha256(uid + "-" + ts + "-" + access_token)

Example:

uid = 123
ts = 1770223138
access_token = "MIIdEf123456..."

sig = sha256("123-1770223138-MIIdEf123456...")

Server-Side Upload Verification

Your server should verify requests as follows:

1. Parse the request parameters to extract UID, timestamp, and signature

2. Verify the timestamp - Check that the time difference between the current time and the timestamp is within acceptable limits (e.g., ±5 minutes) to prevent replay attacks:

   content_copy

   if (abs(current_time - ts) > 300) {
       reject_request();
   }

3. Retrieve the user access token from your database using the UID

4. Generate the expected signature:

   content_copy

   expected_sig = sha256(uid + "-" + ts + "-" + access_token)

5. Compare signatures - Verify the provided signature matches the expected signature

6. Process the file upload if authentication succeeds

Upload Response Format

Your server should respond with JSON data containing the following fields:

Success Response Example:

{
  "result": true,
  "url": "https://example.com/files/user123/image-20250204.jpg"
}

Success Response with File Size Limit:

{
  "result": true,
  "url": "https://example.com/files/user123/image-20250204.jpg",
  "max_file_size": 52428800
}

In this example, the client will restrict all future uploads to 50MB (52428800 bytes).

Failure Response Example:

{
  "result": false
}

Note: When max_file_size is specified, mesibo clients will remember this value and prevent users from uploading files larger than this limit, improving user experience by catching size violations before upload attempts.

Download Authentication Parameters

When downloading any file, mesibo appends the following parameters to the file URL as a query string:

https://example.com/file.jpg?v=1&uid=<uid>&ts=<ts>&sig=<sig>

Download Signature Generation

The download signature is generated differently from the upload signature:

sig = sha256(url + "-" + uid + "-" + ts + "-" + access_token)

Where url is the complete file URL without query parameters.

Example:

url = "https://example.com/file.jpg"
uid = 123
ts = 1770223138
access_token = "MIIdEf123456..."

sig = sha256("https://example.com/file.jpg-123-1770223138-MIIdEf123456...")

Server-Side Download Verification

mesibo always appends authentication parameters to download requests. However, it is entirely up to your server whether to enforce download authentication or not. For example, you may choose to make files publicly accessible and ignore the authentication parameters.

If you choose to authenticate downloads, your server can verify requests as follows:

1. Extract the base URL (without query parameters)

2. Parse the query parameters to extract UID, timestamp, and signature

3. Verify the timestamp - Check that the time difference is within acceptable limits (e.g., ±5 minutes)

4. Retrieve the user access token from your database using the UID

5. Generate the expected signature:

   content_copy

   expected_sig = sha256(url + "-" + uid + "-" + ts + "-" + access_token)

6. Compare signatures - Verify the provided signature matches the expected signature

7. Serve the file if authentication succeeds

Option 2: File Transfer Handler (Android and iOS)

In case configuring a custom file server in UAC does not meet your requirements, you can handle upload and download entirely by yourself by implementing FileTransferHandler. This gives you complete programmatic control over the file transfer process, including the ability to:

In case, configuring a custom file server in UAC does not meet your requirements, you can 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. This gives you complete programmatic control over the file transfer process.

The following FileTransferHandler functions will be called by mesibo whenever the 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:

Setting File Transfer Results

Once the requested operation (upload or download) completes successfully, you need to call file.setResult to inform mesibo about the file transfer. If uploading, you need to inform mesibo API about the 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 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

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);

The response format MUST be the same as described in Option-1 above:

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

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.