Вложения

Раздел «Вложения» — загрузка файлов, которые потом прикрепляются к сообщению через attachmentIds (см. «Отправить сообщение»). Как и загрузка аватара (см. «Аватар»), загрузка идёт в два шага через предподписанный URL — сам файл никогда не проходит через это API напрямую, только метаданные. Для больших файлов есть отдельный multipart-режим с загрузкой по частям.

Все запросы этого раздела требуют заголовок Authorization: Bearer <accessToken>.

Объект AttachmentResponse

Поле	Тип	Описание
id	string	Идентификатор вложения.
uploaderId	string	Кто загрузил файл.
fileName	string	Имя файла.
contentType	string	MIME-тип файла.
sizeBytes	integer (int64)	Размер файла в байтах.
status	AttachmentStatus	Текущий статус загрузки.
isMultipart	boolean	Была ли загрузка выполнена в multipart-режиме.
createdAt	string	Когда загрузка была инициирована (ISO8601).
updatedAt	string	Когда статус вложения обновлялся в последний раз (ISO8601).

AttachmentStatus

Значение	Описание
ATTACHMENT_STATUS_UNSPECIFIED	Значение по умолчанию, не используется в реальных ответах.
PENDING	Загрузка инициирована, файл ещё не подтверждён.
UPLOADED	Файл успешно загружен и подтверждён.
FAILED	Загрузка завершилась ошибкой.
DELETED	Вложение удалено.

Объект ошибки

При любой ошибке вместо 200 OK возвращается default-ответ:

Поле	Тип	Описание
code	integer	Числовой код ошибки (google.rpc.Code).
message	string	Человекочитаемое описание ошибки.
details	array	Дополнительные структурированные детали ошибки (google.protobuf.Any); в большинстве случаев пуст.

---

Обычная загрузка

Подходит для файлов, которые целиком помещаются в один HTTP-запрос загрузки.

Запросить загрузку

POST/v1/attachments/upload

Тело запроса

Поле	Тип	Описание
fileName	string	Имя файла.
contentType	string	MIME-тип файла.
sizeBytes	integer (int64)	Размер файла в байтах.

Ответ 200 OK

Поле	Тип	Описание
attachmentId	string	Идентификатор загрузки — передаётся дальше в «Подтвердить загрузку».
uploadUrl	string	Предподписанный URL, на который нужно загрузить файл напрямую.
expiresAt	string	Время, до которого действителен uploadUrl.

Ответ default (ошибка)

Стандартный объект ошибки.

Подтвердить загрузку

POST/v1/attachments/{attachmentId}/confirm

Подтверждает, что файл по uploadUrl загружен, и переводит вложение в статус UPLOADED.

Параметры пути

Поле	Тип	Описание
attachmentId	string	Идентификатор загрузки.

Ответ 200 OK

Объект AttachmentResponse со статусом UPLOADED.

Ответ default (ошибка)

Стандартный объект ошибки — например, если файл по uploadUrl ещё не загружен.

---

Multipart-загрузка

Для больших файлов — тело файла режется клиентом на части и загружается по отдельным предподписанным URL на каждую часть.

Инициировать multipart-загрузку

POST/v1/attachments/multipart

Тело запроса

Поле	Тип	Описание
fileName	string	Имя файла.
contentType	string	MIME-тип файла.
sizeBytes	integer (int64)	Полный размер файла в байтах.
partCount	integer	Число частей, на которые клиент разобьёт файл.

Ответ 200 OK

Поле	Тип	Описание
attachmentId	string	Идентификатор загрузки.
multipartUploadId	string	Идентификатор multipart-сессии.
partUrls	array	Предподписанные URL для каждой части: объекты { partNumber, url }.

Ответ default (ошибка)

Стандартный объект ошибки.

Получить URL для частей

GET/v1/attachments/{attachmentId}/multipart/part-urls

Позволяет перезапросить предподписанные URL для конкретных частей — например, если срок действия ранее выданных истёк до завершения загрузки.

Параметры пути

Поле	Тип	Описание
attachmentId	string	Идентификатор multipart-загрузки.

Query-параметры

Поле	Тип	Описание
partNumbers?	array<integer>	Номера частей, для которых нужны URL.

Ответ 200 OK

Поле	Тип	Описание
partUrls	array	Объекты { partNumber, url } для запрошенных частей.

Ответ default (ошибка)

Стандартный объект ошибки.

Завершить multipart-загрузку

POST/v1/attachments/{attachmentId}/multipart/complete

Подтверждает, что все части загружены, и склеивает их в один файл.

Параметры пути

Поле	Тип	Описание
attachmentId	string	Идентификатор multipart-загрузки.

Тело запроса

Поле	Тип	Описание
parts	array	Список загруженных частей: объекты { partNumber, etag }, где etag — значение заголовка ETag, возвращённое при загрузке этой части по её предподписанному URL.

Ответ 200 OK

Объект AttachmentResponse со статусом UPLOADED.

Ответ default (ошибка)

Стандартный объект ошибки — например, если часть из списка parts не была фактически загружена.

Отменить multipart-загрузку

POST/v1/attachments/{attachmentId}/multipart/abort

Отменяет незавершённую multipart-загрузку.

Параметры пути

Поле	Тип	Описание
attachmentId	string	Идентификатор multipart-загрузки.

Ответ 200 OK

Пустой объект {}.

Ответ default (ошибка)

Стандартный объект ошибки.

---

Работа с готовым вложением

Получить метаданные вложения

GET/v1/attachments/{attachmentId}

Параметры пути

Поле	Тип	Описание
attachmentId	string	Идентификатор вложения.

Ответ 200 OK

Объект AttachmentResponse.

Ответ default (ошибка)

Стандартный объект ошибки.

Получить ссылку на скачивание

GET/v1/attachments/{attachmentId}/download-url

Параметры пути

Поле	Тип	Описание
attachmentId	string	Идентификатор вложения.

Ответ 200 OK

Поле	Тип	Описание
downloadUrl	string	URL для скачивания файла.

Ответ default (ошибка)

Стандартный объект ошибки.

Удалить вложение

POST/v1/attachments/{attachmentId}:delete

Параметры пути

Поле	Тип	Описание
attachmentId	string	Идентификатор вложения.

Ответ 200 OK

Пустой объект {}.

Ответ default (ошибка)

Стандартный объект ошибки.