# 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:
Creating a file upload task. The client initiates the upload process and receives the necessary identifiers.
Upload a file to server 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 that includes the identifier of a previously uploaded file.
# How to download a file?
Downloading the file occurs in two stages:
Getting file information. In response to the request, you will receive a download link.
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) |