Working with files
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.
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 that includes the identifier of the previously uploaded file.
How to download a file?
Downloading the file occurs in two stages:
Retrieving 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 its extension does not meet the restrictions set by the administrator, an error 310 will be returned.
Request:
{
"type": 1,
"id": 5,
"method": "uploadFile",
"payload": {
"fileSize": 1487,
"fileName": "example.png"
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | Command uploadFile |
| fileSize | number | Yes | File size in bytes |
| fileName | string | Yes | 5.5.3+ Filename |
Response:
{
"type": 2,
"id": 5,
"payload": {
"uploadTaskId": "2e9537c4-e82c-467c-a149-3c1b41326def"
}
}| Parameter | Type | Mandatory | 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 ID |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding 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 | Mandatory | Description |
|---|---|---|
| Upload-Task-Id | Yes | Upload task ID previously obtained from the uploadFile command. |
The request body must be submitted in 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 a file has a preview, it should be placed in the form in the preview field. If a file has a preview, it must be passed in the preview field, where it is also transmitted in binary form. The preview name must be different from the main file name.
Sending images with transparent backgrounds (stickers) in WebP format is supported. To achieve this, set the Content-Type to sticker/webp for the file field in multipart/form-data.
Response:
In the case of a successful upload, the HTTP server will respond with 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 field temporalFileId — a temporary identifier for the file ready to be sent in a message. Once sent, 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 | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | Command sendFile |
| chatId | string | Yes | Chat ID for sending a message |
| temporalFileId | string | Yes | Temporary file identifier received in response to the 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 | Mandatory | 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. |
| chatId | string | Yes | Chat ID |
| timestamp | number | Yes | Timestamp of message sent in UNIX timestamp format with millisecond precision |
| messageId | string | Yes | Message ID of the sent message |
| fileId | string | Yes | Permanent ID 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 corresponding 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 | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | The getFileInfo command |
| fileId | string | Yes | File ID from 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 | Mandatory | 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. |
| fileId | string | Yes | 5.5.4+ File ID on the server |
| name | string | Yes | Filename |
| size | number | Yes | File size in bytes |
| mimeType | string | Yes | MIME type of the file |
| downloadUrl | string | Yes | URL for file download |
| readyState | uint32 | Yes | File status on the server. Corresponds to the enumeration FileReadyStateEnum |
| previews | Array | Yes | Array of file previews, duplicating the parameters described above |
| 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 corresponding 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 learn when the file becomes available for download.
Request:
{
"method": "subscribeFileProgress",
"id": 10,
"type": 1,
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | The subscribeFileProgress command |
| fileId | string | Yes | File ID on the server |
Response:
{
"id": 10,
"type": 2,
"payload": {
"result": true
}
}| Parameter | Type | Mandatory | 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. |
| result | boolean | Yes | Was the subscription for the download successful? |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding 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 | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | The unsubscribeFileProgress command |
| fileId | string | Yes | File ID on the server |
Response:
{
"type": 2,
"id": 10,
"payload": {
"result": true
}
}| Parameter | Type | Mandatory | 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. |
| result | boolean | Yes | Was it successful to unsubscribe from receiving file upload events? |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.
Get file storage limits 5.5.3+
The server administrator can set restrictions 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 | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association 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 | Mandatory | 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. |
| maxSize | uint32 | Yes | Maximum file size in bytes (1 MB = 1000 KB). If the limit is disabled, null is passed. |
| extensions | uint32 | Yes | File transfer restriction by their extension. If the restriction is disabled, null is transmitted. |
| 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 corresponding 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 status of the upload, 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"
}
}
}The notification about a message with a file contains fields corresponding to the Envelope and FileMessageContent objects. You can find a detailed description of these fields in the section dedicated to working with messages.
Response from client:
{
"type": 2,
"id": 123456
}| Field | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Message ID being replied to (see more) |
File upload progress
After subscription, 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 | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST from the server. |
| id | uint32 | Yes | An identifier matching the number sent in the original request, used to link the request and response. |
| fileId | string | Yes | File ID on the server |
| Progress | number | Yes | The number of bytes uploaded to the server |
When a message is received where the progress value equals the size field value from the getFileInfo response, the file is considered fully uploaded and can be retrieved via a GET request. After this event, no more events with updated progress will be sent. If the file was previously uploaded, 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 extension of uploaded files. Notification of current limits is sent upon authorization, as well as whenever there are changes to the server settings.
Request:
{
"id": 2,
"type": 1,
"method": "getFileUploadLimits",
"payload": {
"maxSize": 2000000000,
"extensions": {
"mode": "block",
"list": [
"bas",
"bat",
"chm",
"cmd",
]
}
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST from the server. |
| id | uint32 | Yes | An identifier matching the number sent in the original request, used to link the request and response. |
| maxSize | uint32 | Yes | Maximum file size in bytes (1 MB = 1000 KB). If the limit is disabled, null is passed. |
| extensions | uint32 | Yes | File transfer restriction by their extension. If the restriction is disabled, null is transmitted. |
| mode | string | No | Operating mode: block — prohibited extensions (blacklist), allow — allowed extensions (whitelist) |
| list | Array | No | List of Extensions |
Response from client:
{
"type": 2,
"id": 123456
}| Field | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Message ID being replied to (see more) |