# Работа c файлами
На каждый уведомление (запрос) сервера клиент должен ответить так:
{
"type": 2,
"id": 123456
}
После отправки ответа сообщение от пользователя будет считаться прочитанным ботом и будет отмечено соответствующей галочкой в клиентском приложении TrueConf.
# Как отправить файл?
Отправка файла осуществляется в три этапа:
Создание задачи на загрузку файла. Клиент инициирует процесс загрузки и получает необходимые идентификаторы.
Передача файла в файловое хранилище сервера. Файл загружается на сервер с помощью HTTP-запроса (см. пример ниже).
Отправка сообщения с прикреплённым файлом. В чате создаётся сообщение, в котором указывается идентификатор ранее загруженного файла.
# Как скачать файл?
Скачивание файла происходит в два этапа:
Получение информации о файле. В ответе на запрос вы получите ссылку для скачивания.
Загрузка файла. Файл необходимо скачать с помощью GET-запроса.
# Запросы клиента
# Создать задачу загрузки
Запрос:
{
"type": 1,
"id": 5,
"method": "uploadFile",
"payload": {
"fileSize": 1487
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда uploadFile |
| fileSize | number | Да | Размер файла в байтах |
Ответ:
{
"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 |
| Content-Type | Нет | Если установлен sticker/webp, изображение будет отправлено с прозрачным фоном (если он есть) |
Тело запроса должно быть представлено в виде объекта FormData с типом multipart/form-data и содержать обязательное поле file, содержащее сам файл.
Если у файла есть превью, то оно должно быть помещено в форму в поле preview, название под которым помещается превью должно отличаться от названия самого файла.
И файл и превью помещаются в бинарном виде.
Ответ:
В случае успешной загрузки, 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"
}
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда sendFile |
| chatId | string | Да | Идентификатор чата для отправки сообщения |
| temporalFileId | string | Да | Временный идентификатор файла, полученный в ответе на HTTP-запрос |
Ответ:
{
"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": 9,
"type": 1,
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда getFileInfo |
| fileId | string | Да | Идентификатор файла из входящего запроса о новом сообщении |
Ответ:
{
"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"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| name | string | Да | Имя файла |
| size | number | Да | Размер файла в байтах |
| mimeType | string | Да | MIME-тип файла |
| downloadUrl | string | Да | URL для скачивания файла |
| readyState | FileReadyStateEnum | Да | Состояние файла на сервере |
| infoHash | string | Да | Идентификатор файла на сервере |
| previews | Array | Да | Массив превью файла, повторяющий вышеописанные параметры |
Для скачивания файла или его превью необходимо отправить 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, отправляемых сервером после подписки на прогресс загрузки.
Запрос:
{
"method": "unsubscribeFileProgress",
"id": 10,
"type": 1,
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 1). Соответствует
MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда unsubscribeFileProgress |
| fileId | string | Да | Идентификатор файла на сервере |
Ответ:
{
"id": 10,
"type": 2,
"payload": {
"result": true
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 2). Соответствует
MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| result | boolean | Да | Получилось ли отписаться от получения событий о загрузке файла |
В случае возникновения ошибки возвращается сообщение, содержащее параметр 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": 2,
"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 больше не поступают. Если файл уже был загружен ранее, будет отправлено только одно финальное событие, эквивалентное последнему.