# Working with files
# File Transfer
File transfer is carried out in three stages:
Creating a File Upload Task. The client initiates the upload creation and receives the necessary identifiers.
Uploading a file to the server's file storage. The file is uploaded to the server using an HTTP request (see the example below).
Sending a message with an attached file. A message is created in the chat specifying the identifier of a previously uploaded file.
# Creating a file 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.
# Uploading a file to the file storage
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 file upload task identifier previously obtained from the uploadFile command |
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",
}
# Sending a file in a message
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.
# Retrieving file information and downloading the file
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.
# Subscription to file upload progress on the server
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.
# Receiving file 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 receiving upload event notifications
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.