# 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
If the file size or extension does not meet the restrictions set by the administrator, a error 310 will be returned.
Request:
{
"type": 1,
"id": 5,
"method": "uploadFile",
"payload": {
"fileSize": 1487,
"fileName": "example.png"
}
}
| 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, mandatory in each request to be linked with the response. More details here |
| method | string | Yes | Command uploadFile |
| fileSize | number | Yes | File size in bytes |
| fileName | string | Yes | File name |
Response:
{
"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 the event 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 file upload task ID previously obtained from the uploadFile command |
The request body must be sent in the multipart/form-data format and must include the required field file, where the file is transmitted in binary form. The file name specified in multipart/form-data is ignored: the server uses the value of the fileName parameter from the uploadFile request.
If the file has a preview, it must be placed in the form in the preview field. If the file has a preview, it should be passed in the preview field, where it is also transmitted in binary form. The preview name must differ from the main file name.
Sending images with a transparent background (stickers) in WebP format is supported. To do this, you need to specify Content-Type: sticker/webp for the file field in multipart/form-data.
Response:
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",
"caption": {
"text": "Here is your <i>file</i>!",
"parseMode": "html"
}
}
}
}
| 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, mandatory in each request for subsequent binding with the response. See 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 |
| text | string | No | 5.5.2+ Message text |
| parseMode | string | No | 5.5.2+ Formatting mode (see here) |
Response:
{
"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 the event 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": 1,
"type": 1,
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Parameter | Type | Req. | Description |
|---|---|---|---|
| type | uint32 | Yes | Type of message (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. Incremental value assigned by the sender, required in each request to associate with the response. Read more here |
| method | string | Yes | Command getFileInfo |
| fileId | string | Yes | File identifier from the incoming new message request |
Response:
{
"id": 2,
"type": 2,
"payload": {
"fileId": "dd11ab35591d6c93216c9818187417c093686219",
"name": "image_2025.11.01_17-15-15.webp",
"size": 146362,
"mimeType": "image/webp",
"downloadUrl": "https://video.example.com/bridge/api/client/v1/files/dd11ab35591d6c93216c9818187417c093686219",
"readyState": 2,
"previews": [
{
"name": "preview-44f047a3ef51d19e06ce560d6c78a06b.webp",
"size": 1200,
"mimeType": "image/webp",
"downloadUrl": "https://video.example.com/bridge/api/client/v1/files/dd11ab35591d6c93216c9818187417c093686219/preview/"
}
]
}
}
| Parameter | Type | Req. | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default 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 |
| fileId | string | Yes | 5.5.4+ File identifier on the server |
| name | string | Yes | File name |
| size | number | Yes | File size in bytes |
| mimeType | string | Yes | MIME type of the file |
| downloadUrl | string | Yes | URL to download the file |
| readyState | uint32 | Yes | File state on the server. Corresponds to FileReadyStateEnum |
| previews | Array | Yes | Array of file previews, repeating the above parameters |
| infoHash | string | Yes | Removed in 5.5.4 Use the fileId parameter |
To download a file or its preview, you need to send an HTTP GET request to the address specified in downloadUrl.
In the event 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 file upload events
If the file is in the UPLOADING state, you can subscribe to upload events to receive progress notifications and find out when the file becomes available for download.
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 |
Response:
{
"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 the event 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.
# Unsubscribe from file upload events
Stops receiving uploadingProgress events sent by the server after subscribing to upload progress.
Request:
{
"type": 1,
"id": 10,
"method": "unsubscribeFileProgress",
"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 |
Response:
{
"type": 2,
"id": 10,
"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 the event 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 storage limitations
5.5.3+ The server administrator can set limits on file sending based on size and extension. You can request the current file storage limitations using the following query.
Request:
{
"type": 1,
"id": 1,
"method": "getFileUploadLimits",
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | uint32 | Yes |
Message type (default is 1). Corresponds to
MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. Incremental value assigned by the sender, required in each request for subsequent binding with the response. Read more here |
| method | string | Yes | Command getFileUploadLimits |
Response:
{
"id": 1,
"type": 2,
"payload": {
"maxSize": 2000000000,
"extensions": {
"mode": "block",
"list": [
"bas",
"bat",
"chm",
"cmd"
]
}
}
}
| 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 link the request and response |
| maxSize | uint32 | Yes | Allowed file size in bytes (1 MB = 1000 B). If the limit is disabled, null is passed |
| extensions | uint32 | Yes | File transfer restriction by extension. If the restriction is disabled, null is passed |
| mode | string | No | Operating mode: block — prohibited extensions (blacklist), allow — allowed extensions (whitelist) |
| list | Array | No | List of extensions |
In the event 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 event of sending a file occurs immediately upon message creation, even before the file is actually uploaded to the server. After a short period, the file will be uploaded, and only then will it be available for download.
- To track the progress of a file upload, use the subscribeFileProgress request.
- To obtain the current upload status, use the getFileInfo request.
Notification 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": 202,
"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) |
# File upload progress
After subscribing, the server will start sending uploadingProgress events with information about the current upload status.
Notification from the server:
{
"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.
# File Storage Limitations
5.5.3+ The server administrator can set restrictions on the size and extensions of uploaded files. Notifications about current limits are sent upon authorization, as well as each time the server settings are changed.
Request:
{
"id": 2,
"type": 1,
"method": "getFileUploadLimits",
"payload": {
"maxSize": 2000000000,
"extensions": {
"mode": "block",
"list": [
"bas",
"bat",
"chm",
"cmd",
]
}
}
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | uint32 | Yes |
Message type (default is 1). Corresponds to
MESSAGE_TYPE.REQUEST from the server
|
| id | uint32 | Yes | An identifier that matches the number sent in the original request, used to link the request and response |
| maxSize | uint32 | Yes | Allowed file size in bytes (1 MB = 1000 KB). If the limit is disabled, null is passed |
| extensions | uint32 | Yes | File transfer limitation by extension. If the limit is disabled, null is passed |
| mode | string | No | Operating mode: block — forbidden extensions (blacklist), allow — allowed extensions (whitelist) |
| list | Array | No | List of extensions |
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) |