Zapnoty — Файлы — обмен вложениями

Файлы — обмен вложениями

Фото, видео и документы в тикетах и диалогах с агентами. Загрузка, отправка вложений, поиск по описанию, квота хранилища.

Как это устроено

Клиент присылает боту фото или документ — файл попадает в хранилище и прикрепляется к сообщению тикета или диалога с агентом. В обратную сторону так же: оператор и агент прикладывают файлы к ответу, человек получает их в том же мессенджере, где написал. Всё загруженное собирается в разделе «Файлы» кабинета — с поиском, описанием и повторным использованием: один и тот же прайс не нужно загружать дважды.

Что можно загружать

Изображения 10 MB

jpeg, png, webp, gif

Видео 50 MB

mp4, mov, webm

Документы 20 MB

pdf, docx, xlsx, pptx, txt, csv, json, xml, zip

Тип определяется по содержимому файла, а не по расширению: переименованный исполняемый файл не пройдёт. Всё, чего нет в списке, отклоняется. Один клиент может прислать не больше 25 файлов и 50 МБ в сутки — это защищает ваше место от наполнения извне.

Место

Квота общая на аккаунт, а не на проект, и зависит от тарифа: 100 МБ на бесплатном, 300 МБ на «Лайте», 700 МБ на «Базовом», 1,5 ГБ на «Стандарте» и больше на старших тарифах. Одинаковые файлы занимают место один раз. Важное можно отметить звёздочкой — автоочистка его не тронет.

Эндпоинты

POST /v1/agent/media — загрузить файл (multipart)

GET /v1/agent/media/{id} — скачать: 302 на временную ссылку

GET /v1/agent/files — найти файл по имени или описанию

POST /v1/agent/say — отправить сообщение с вложениями

POST /v1/helpdesk/tickets/{id}/reply — ответ в тикет с вложениями

1. Загрузка файла

Файл загружается отдельным запросом и получает идентификатор. Отправка сообщения — второй шаг: так агент может подготовить вложение заранее, а при ошибке загрузки не теряется текст.

POST /v1/agent/media

Authorization: Bearer agtk_...

Content-Type: multipart/form-data

file=@report.pdf

{

"id": "med_7hQ2mzT1kR",

"kind": "file",

"mime": "application/pdf",

"name": "report.pdf",

"size_bytes": 284133,

"uploaded_by": "agent",

"created_at": "2026-08-15T09:12:44Z"

}

2. Отправка с вложением

В поле attachments перечисляются идентификаторы файлов — до 10 на сообщение. Файлы должны принадлежать тому же проекту, что и ключ.

POST /v1/agent/say

Authorization: Bearer agtk_...

{

"text": "Отчёт за июль готов",

"attachments": ["med_7hQ2mzT1kR"]

}

3. Поиск готового файла

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

GET /v1/agent/files?query=договор

Authorization: Bearer agtk_...

{

"files": [

{

"id": "med_3nB8xwQ5tE",

"kind": "file",

"name": "contract-template.docx",

"description": "Шаблон договора на услуги",

"size_bytes": 48211

}

]

}

GET /v1/agent/media/med_3nB8xwQ5tE

Authorization: Bearer agtk_...

302 Found

Location: https://s3.twcstorage.ru/...

Ссылка временная и живёт 10 минут. Постоянных публичных адресов у файлов нет — хранилище закрыто, и каждый запрос проверяет права.

4. Ответ в тикет с файлом

POST /v1/helpdesk/tickets/{id}/reply

Authorization: Bearer zn_live_...

{

"text": "Инструкция во вложении",

"attachments": ["med_7hQ2mzT1kR"]

}

5. Файл в рассылке

Вложение любого сообщения задаётся либо ссылкой (url), либо файлом хранилища (media_id) — но не обоими сразу. Для файла хранилища адрес выписывается в момент отправки, поэтому вложение не протухает в отложенной или повторяющейся рассылке, сколько бы она ни ждала своего часа.

POST /v1/broadcast

Authorization: Bearer zn_live_...

{

"text": "Прайс на сентябрь во вложении",

"media": { "media_type": "file", "media_id": "med_3nB8xwQ5tE" },

"tags_any": ["clients"]

}