# Working with files

For each server notification (request), the client should respond as follows:

{
    "type": 2,
    "id": 123456
}

Once the response is sent, the user’s message is marked as read by the bot and a check mark appears in the TrueConf client application.

# How to send a file?

File transfer is carried out in three stages:

  1. Creating a file upload task. The client initiates the upload process and receives the necessary identifiers.

  2. Upload a file to server storage. The file is uploaded to the server using an HTTP request (see the example below).

  3. Sending a message with an attached file. A message is created in the chat that includes the identifier of a previously uploaded file.

# How to download a file?

Downloading the file occurs in two stages:

  1. Getting file information. In response to the request, you will receive a download link.

  2. File Download. The file must be downloaded using a GET request.

# Client requests

# Create upload task

Request:

{
  "type": 1,
  "id": 5,
  "method": "uploadFile",
  "payload": {
    "fileSize": 1487
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sending party, required in every request for subsequent matching with the response. Read more here
method string Yes Command uploadFile
fileSize number Yes File size in bytes

Answer:

{
  "type": 2,
  "id": 5,
  "payload": {
    "uploadTaskId": "2e9537c4-e82c-467c-a149-3c1b41326def"
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier matching the number sent in the original request, used to link the request and response
uploadTaskId string Yes File upload task identifier

In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.

# Upload file to server

To upload a file to the storage, you need to make an HTTP request to the server. The parameters listed below are specified in the HTTP headers, not in the URL (query string):

POST /bridge/api/client/v1/files HTTP/1.1
Upload-Task-Id: 2e9537c4-e82c-467c-a149-3c1b41326def
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryQeFqWQPxCmHvCIyc
Content-Length: 2081

------WebKitFormBoundaryQeFqWQPxCmHvCIyc
Content-Disposition: form-data; name="file"; filename="some_image.png"
Content-Type: image/png

<file binary data>
------WebKitFormBoundaryQeFqWQPxCmHvCIyc
Content-Disposition: form-data; name="preview"; filename="d970f81f-d433-401c-8182-d33c59b96cd5"
Content-Type: image/webp

<preview binary data>
------WebKitFormBoundaryQeFqWQPxCmHvCIyc
Title Req. Description
Upload-Task-Id Yes The identifier for the file upload task, previously obtained from the uploadFile command
Content-Type No If set to sticker/webp, the image will be sent with a transparent background (if it exists)

The request body must be presented as a FormData object with the type multipart/form-data and must contain the required field file, which holds the file itself. If the file has a preview, it should be included in the form under the preview field, and the name under which the preview is placed must differ from the name of the file itself. Both the file and the preview are included in binary format.

Answer:

If the upload is successful, the HTTP server will respond with the code 200 OK:

HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST
Server: TrueConf Bridge
Content-Type: application/json
Content-Length: 57
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: height,mime,request_id,preview,cid

{
  "temporalFileId": "2e9537c4-e82c-467c-a149-3c1b41326def"
}

The response body contains the temporalFileId field, which is a temporary file identifier ready for sending in a message. After sending, this identifier loses any useful properties.

Error:

In case of an error, the HTTP server will respond with the code 400 Bad Request:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 62

{
  "error": 310,
  "error_description": "No upload task ID provided",
}

# Send file

Request:

{
  "type": 1,
  "id": 6,
  "method": "sendFile",
  "payload": {
    "chatId": "bea15543d971a83c8ba1f103104791762c6b4b8f",
    "content": {
      "temporalFileId": "32506b12-6a1a-4cd3-be24-373c7bcf9510"
    }
  }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender, required in each request for subsequent linking with the response. Read more here
method string Yes Command sendFile
chatId string Yes Chat identifier for sending the message
temporalFileId string Yes Temporary file identifier received in response to an HTTP request

Answer:

{
  "type": 2,
  "id": 6,
  "payload": {
    "chatId": "bea15543d971a83c8ba1f103104791762c6b4b8f",
    "timestamp": 1735134222098,
    "messageId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
    "fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier matching the number sent in the original request, used to correlate request and response
chatId string Yes Chat identifier
timestamp number Yes Message sending timestamp in UNIX timestamp format with millisecond precision
messageId string Yes Identifier of the sent message
fileId string Yes Permanent identifier of the sent file for retrieving information about it

In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.

# Get file information

To obtain detailed information about an incoming file in the chat, you need to use the payload.content.id value obtained from the incoming new message request.

Request:

{
  "method": "getFileInfo",
  "id": 9,
  "type": 1,
  "payload": {
    "fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incremented value assigned by the sender, required in each request to link with the response. Read more here
method string Yes The command getFileInfo
fileId string Yes File identifier from the incoming new message request

Answer:

{
    "type": 2,
    "id": 9,
    "payload": {
        "name": "AirHelp_Logo.webp",
        "size": 3446,
        "mimeType": "image/webp",
        "downloadUrl": "https://10.111.15.116/bridge/api/client/v1/files?file_id=e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5",
        "readyState": 2,
        "previews": [
            {
                "name": "preview-2278f47b821f72e4a44ab6b980180518.webp",
                "mimeType": "image/webp",
                "size": 1264,
                "downloadUrl": "https://10.111.15.116/bridge/api/client/v1/files/preview?file_id=e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
            }
        ],
        "infoHash": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
    }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier matching the number sent in the original request, used to link the request and response
name string Yes File name
size number Yes File size in bytes
mimeType string Yes MIME type of the file
downloadUrl string Yes URL for downloading the file
readyState FileReadyStateEnum Yes File state on the server
infoHash string Yes File identifier on the server
previews Array Yes Array of file previews, repeating the parameters described above

To download a file or its preview, you need to send an HTTP GET request to the address specified in downloadUrl.

In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.

# Subscribe to upload progress

If the file is in the UPLOADING status, you can subscribe to the upload process to be notified when the file becomes available.

Request:

{
  "method": "subscribeFileProgress",
  "id": 10,
  "type": 1,
  "payload": {
    "fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender, required in each request to link with the response. Read more here
method string Yes Command subscribeFileProgress
fileId string Yes File identifier on the server

Answer:

{
  "id": 10,
  "type": 2,
  "payload": {
    "result": true
  }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier matching the number sent in the original request, used to correlate the request and response
result boolean Yes Indicates whether the subscription to the upload was successful

In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.

# Get upload events

After subscribing to the upload, uploadingProgress events will start arriving via WebSocket:

{
  "id": 3,
  "type": 1,
  "method": "uploadingProgress",
  "payload": {
    "fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5",
    "progress": 123
  }
}
Parameter Type Required Description
type uint32 Yes Type of message (default is 1). Corresponds to MESSAGE_TYPE.REQUEST from the server
id uint32 Yes Identifier matching the number sent in the original request, used for linking the request and response
fileId string Yes File identifier on the server
progress number Yes Number of bytes uploaded to the server

When a message is received where the value of progress equals the value of the size field from the getFileInfo response, the file is considered fully uploaded and can be retrieved using a GET request. After this, no more events with updated progress will be sent. If the file was already uploaded earlier, only one final event equivalent to the last one will be sent.

# Unsubscribe from events

If necessary, you can unsubscribe from receiving file upload events on the server.

Request:

{
  "method": "unsubscribeFileProgress",
  "id": 10,
  "type": 1,
  "payload": {
    "fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
  }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender, required in each request to link it with the response. For more details, read here
method string Yes Command unsubscribeFileProgress
fileId string Yes File identifier on the server

Answer:

{
  "id": 10,
  "type": 2,
  "payload": {
    "result": true
  }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier matching the number sent in the original request, used to correlate the request and response
result boolean Yes Whether the unsubscription from file upload events was successful

In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.

# Server notifications

# New file in chat

In the TrueConf chat protocol, the file send event occurs immediately upon message creation, without waiting for the file to be uploaded to the server. After this, the file will upload for a while before becoming available for download.

Message from the server:

{
    "type": 1,
    "id": 7,
    "method": "sendMessage",
    "payload": {
        "chatId": "bea15543d971a83c8ba1f103104791762c6b4b8f",
        "messageId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
        "timestamp": 1735302531000,
        "author": {
            "id": "user@video.example.com",
            "type": 1
        },
        "isEdited": false,
        "box": {
            "id": 10,
            "position": ""
        },
        "type": 2,
        "content": {
            "name": "someimage.png",
            "mimeType": "image/png",
            "size": 2156,
            "fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
        }
    }
}

A notification about a message with a file contains fields corresponding to the Envelope and FileMessageContent objects. Detailed descriptions of these fields can be found in the section dedicated to message handling.

Response from client:

{
    "type": 2,
    "id": 123456
}
Field Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier of the message being responded to (see details)