# Работа c файлами
На каждый уведомление (запрос) сервера клиент должен ответить так:
{
"type": 2,
"id": 123456
}
После отправки ответа сообщение от пользователя будет считаться прочитанным ботом и будет отмечено соответствующей галочкой в клиентском приложении TrueConf.
# Как отправить файл?
Отправка файла осуществляется в три этапа:
Создание задачи на загрузку файла. Клиент инициирует процесс загрузки и получает необходимые идентификаторы.
Передача файла в файловое хранилище сервера. Файл загружается на сервер с помощью HTTP-запроса (см. пример ниже).
Отправка сообщения с прикреплённым файлом. В чате создаётся сообщение, в котором указывается идентификатор ранее загруженного файла.
# Как скачать файл?
Скачивание файла происходит в два этапа:
Получение информации о файле. В ответе на запрос вы получите ссылку для скачивания.
Загрузка файла. Файл необходимо скачать с помощью GET-запроса.
# Запросы клиента
# Создать задачу загрузки
Если размер файла или его расширение не соответствуют ограничениям, установленным администратором, будет возвращена ошибка 310.
Запрос:
{
"type": 1,
"id": 5,
"method": "uploadFile",
"payload": {
"fileSize": 1487,
"fileName": "example.png"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда uploadFile |
| fileSize | number | Да | Размер файла в байтах |
| fileName | string | Да | Имя файла |
Ответ:
{
"type": 2,
"id": 5,
"payload": {
"uploadTaskId": "2e9537c4-e82c-467c-a149-3c1b41326def"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| uploadTaskId | string | Да | Идентификатор задачи на загрузку файла |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Загрузить файл на сервер
Для загрузки файла в хранилище необходимо выполнить HTTP-запрос к серверу. Перечисленные ниже параметры указываются в HTTP-заголовках, а не передаются в 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
| Заголовок | Обяз. | Описание |
|---|---|---|
| Upload-Task-Id | Да | Идентификатор задачи на загрузку файла, полученный ранее из команды uploadFile |
Тело запроса должно быть передано в формате multipart/form-data и содержать обязательное поле file, в котором файл передаётся в бинарном виде. Имя файла, указанное в multipart/form-data, игнорируется: сервер использует значение параметра fileName запроса uploadFile.
Если у файла есть превью, то оно должно быть помещено в форму в поле preview,Если у файла есть превью, его нужно передать в поле preview, в котором оно также передаётся в бинарном виде. Имя превью должно отличаться от имени основного файла.
Поддерживается отправка изображений с прозрачным фоном (стикеров) в формате WebP. Для этого для поля file в multipart/form-data нужно указать Content-Type: sticker/webp.
Ответ:
В случае успешной загрузки, HTTP-сервер ответит кодом 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"
}
В теле ответа содержится поле temporalFileId – временный идентификатор файла, готового для отправки в сообщении.
После отправки этот идентификатор теряет какие-либо полезные свойства.
Ошибка:
В случае ошибки, HTTP-сервер ответит кодом 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",
}
# Отправить файл
Запрос:
{
"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"
}
}
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда sendFile |
| chatId | string | Да | Идентификатор чата для отправки сообщения |
| temporalFileId | string | Да | Временный идентификатор файла, полученный в ответе на HTTP-запрос |
| text | string | Нет | 5.5.2+ Текст сообщения |
| parseMode | string | Нет | 5.5.2+ Режим форматирования (см. тут) |
Ответ:
{
"type": 2,
"id": 6,
"payload": {
"chatId": "bea15543d971a83c8ba1f103104791762c6b4b8f",
"timestamp": 1735134222098,
"messageId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| chatId | string | Да | Идентификатор чата |
| timestamp | number | Да | Временная метка отправки сообщения в формате UNIX timestamp с точностью до миллисекунд |
| messageId | string | Да | Идентификатор отправленного сообщения |
| fileId | string | Да | Постоянный идентификатор отправленного файла для получения информации о нем |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Получить информацию о файле
Для получения расширенной информации о входящем файле в чате необходимо использовать значение payload.content.id, полученное из входящего запроса о новом сообщении.
Запрос:
{
"method": "getFileInfo",
"id": 1,
"type": 1,
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда getFileInfo |
| fileId | string | Да | Идентификатор файла из входящего запроса о новом сообщении |
Ответ:
{
"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/"
}
]
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| fileId | string | Да | 5.5.4+ Идентификатор файла на сервере |
| name | string | Да | Имя файла |
| size | number | Да | Размер файла в байтах |
| mimeType | string | Да | MIME-тип файла |
| downloadUrl | string | Да | URL для скачивания файла |
| readyState | uint32 | Да | Состояние файла на сервере. Соответствует перечислению FileReadyStateEnum |
| previews | Array | Да | Массив превью файла, повторяющий вышеописанные параметры |
| infoHash | string | Да | Удалено в 5.5.4 Используйте параметр fileId |
Для скачивания файла или его превью необходимо отправить HTTP GET-запрос на адрес, указанный в downloadUrl.
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Подписаться на события загрузки файла
Если файл находится в состоянии UPLOADING, можно подписаться на события загрузки, чтобы получать уведомления о прогрессе и узнать, когда файл станет доступен для скачивания.
Запрос:
{
"method": "subscribeFileProgress",
"id": 10,
"type": 1,
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 1). Соответствует
MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда subscribeFileProgress |
| fileId | string | Да | Идентификатор файла на сервере |
Ответ:
{
"id": 10,
"type": 2,
"payload": {
"result": true
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 2). Соответствует
MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| result | boolean | Да | Получилось ли подписаться на загрузку |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Отписаться от событий загрузки файла
Прекращает получение событий uploadingProgress, отправляемых сервером после подписки на прогресс загрузки.
Запрос:
{
"type": 1,
"id": 10,
"method": "unsubscribeFileProgress",
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 1). Соответствует
MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда unsubscribeFileProgress |
| fileId | string | Да | Идентификатор файла на сервере |
Ответ:
{
"type": 2,
"id": 10,
"payload": {
"result": true
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 2). Соответствует
MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| result | boolean | Да | Получилось ли отписаться от получения событий о загрузке файла |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Получить ограничения файлового хранилища
5.5.3+ Администратор сервера может задать ограничения на отправку файла по размеру и расширению. Вы можете запросить актуальные ограничения файлового хранилища с помощью следующего запроса.
Запрос:
{
"type": 1,
"id": 1,
"method": "getFileUploadLimits",
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 1). Соответствует
MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда getFileUploadLimits |
Ответ:
{
"id": 1,
"type": 2,
"payload": {
"maxSize": 2000000000,
"extensions": {
"mode": "block",
"list": [
"bas",
"bat",
"chm",
"cmd"
]
}
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 2). Соответствует
MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| maxSize | uint32 | Да | Допустимый размер файла в байтах (1 МБ = 1000 Б). Если ограничение отключено, то передается null |
| extensions | uint32 | Да | Ограничение передачи файлов по их расширению. Если ограничение отключено, то передается null |
| mode | string | Нет | Режим работы: block — запрещенные расширения (черный список), allow — разрешенные расширения (белый список) |
| list | Array | Нет | Список расширений |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Уведомления сервера
# Новый файл в чате
В протоколе чата TrueConf событие об отправке файла приходит сразу при создании сообщения, ещё до фактической загрузки файла на сервер. Через некоторое время файл будет загружен, и только после этого станет доступен для скачивания.
- Чтобы отслеживать прогресс загрузки файла, используйте запрос subscribeFileProgress.
- Для получения текущего статуса загрузки используйте запрос getFileInfo.
Уведомление от сервера:
{
"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"
}
}
}
Уведомление о сообщении с файлом содержит поля, соответствующие объектам Envelope и FileMessageContent. Подробное описание этих полей вы найдёте в разделе посвящённом работе с сообщениями.
Ответ от клиента:
{
"type": 2,
"id": 123456
}
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор сообщения, на которое дается ответ (см. подробнее) |
# Прогресс загрузки файла
После подписки сервер начнёт отправлять события uploadingProgress с информацией о текущем состоянии загрузки.
Уведомление от сервера:
{
"id": 3,
"type": 1,
"method": "uploadingProgress",
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5",
"progress": 123
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 1). Соответствует
MESSAGE_TYPE.REQUEST от сервера
|
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| fileId | string | Да | Идентификатор файла на сервере |
| progress | number | Да | Количество байт, загруженных на сервер |
Когда придёт сообщение, в котором значение progress будет равно значению поля size из ответа getFileInfo, файл считается полностью загруженным и может быть получен с помощью GET-запроса. После этого события с обновлённым progress больше не поступают. Если файл уже был загружен ранее, будет отправлено только одно финальное событие, эквивалентное последнему.
# Ограничения файлового хранилища
5.5.3+ Администратор сервера может установить ограничения на размер и расширение загружаемых файлов. Уведомление об актуальных лимитах отправляется при авторизации, а также при каждом изменении настроек на сервере.
Запрос:
{
"id": 2,
"type": 1,
"method": "getFileUploadLimits",
"payload": {
"maxSize": 2000000000,
"extensions": {
"mode": "block",
"list": [
"bas",
"bat",
"chm",
"cmd",
]
}
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 1). Соответствует
MESSAGE_TYPE.REQUEST от сервера
|
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| maxSize | uint32 | Да | Допустимый размер файла в байтах (1 МБ = 1000 Б). Если ограничение отключено, то передается null |
| extensions | uint32 | Да | Ограничение передачи файлов по их расширению. Если ограничение отключено, то передается null |
| mode | string | Нет | Режим работы: block — запрещенные расширения (черный список), allow — разрешенные расширения (белый список) |
| list | Array | Нет | Список расширений |
Ответ от клиента:
{
"type": 2,
"id": 123456
}
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор сообщения, на которое дается ответ (см. подробнее) |