Работа c файлами

На каждый уведомление (запрос) сервера клиент должен ответить так:

{
    "type": 2,
    "id": 123456
}

После отправки ответа сообщение от пользователя будет считаться прочитанным ботом и будет отмечено соответствующей галочкой в клиентском приложении TrueConf.

Как отправить файл?

Отправка файла осуществляется в три этапа:

1. Создание задачи на загрузку файла. Клиент инициирует процесс загрузки и получает необходимые идентификаторы.

2. Передача файла в файловое хранилище сервера. Файл загружается на сервер с помощью HTTP-запроса (см. пример ниже).

3. Отправка сообщения с прикреплённым файлом. В чате создаётся сообщение, в котором указывается идентификатор ранее загруженного файла.

Как скачать файл?

Скачивание файла происходит в два этапа:

1. Получение информации о файле. В ответе на запрос вы получите ссылку для скачивания.

2. Загрузка файла. Файл необходимо скачать с помощью 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	Да	5.5.3+ Имя файла

Ответ:

{
  "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	Да	Removed in 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	Да	Идентификатор сообщения, на которое дается ответ (см. подробнее)