Интеграция
Dropbox и то пространство имён, в котором ваших файлов нет
Интеграция с Dropbox подшивает документы, собранные в Telegram, в командную структуру папок. Деталь, на которой спотыкаются реализации, — командное пространство: приложение, авторизованное в бизнес-аккаунте, по умолчанию пишет в личное пространство конкретного участника, и файлы оказываются там, куда никто не смотрит.
Dropbox — интеграция: доступ, лимиты и доступность
- Модель авторизации
- OAuth 2.0
- Пространство имён
- У бизнес-аккаунтов есть командное пространство и личные; вызов по умолчанию уходит в одно
- Доступность в Заливе
- Региональных ограничений нет; основная работа — командное пространство Business
- Поток данных
- 5 узлов, через воркер
As of 2025-10-01, Telegram Bot API 13.4
Зачем нужна эта интеграция
Dropbox Business до сих пор распространён среди компаний Залива, которые выбрали его раньше, чем созрели альтернативы, и для сбора документов он работает хорошо: синхронизация на компьютер означает, что файл появляется в папке на ноутбуке, и никому не нужно открывать браузер. Это заметно более низкий порог, чем у хранилища, живущего только в вебе.
Ломается обычно модель пространств имён. У аккаунта Dropbox Business есть командное пространство и личное пространство у каждого участника, и вызов API по умолчанию уходит в корень того участника, который авторизовался, а не в корень команды. Загрузка проходит успешно, API возвращает путь, и файл лежит там, где остальная команда его не видит. Ошибки при этом не возникает — именно поэтому диагностика обходится так дорого.
Лечится это явным разрешением командного пространства имён и заголовком корня пути в каждом запросе. Заголовок ровно один, и забыть его легко, а симптом — файлы, которые существуют и невидимы, — отправляет людей разбираться с правами доступа вместо адресации.
Как на самом деле движутся данные
OAuth 2.0 выдаёт refresh-токен, который хранится как секрет воркера, а короткоживущие токены доступа получаются уже из него. Для бизнес-аккаунта приложению выдаются командные разрешения, и каждый запрос несёт явный заголовок корня пути с командным пространством имён, вместо того чтобы полагаться на значение по умолчанию у авторизовавшегося участника.
Модель доступа: OAuth 2.0
Их лимиты и что они означают для вас
У аккаунта Dropbox Business есть командное пространство и личные пространства участников, а вызовы API по умолчанию уходят в корень участника.
Заголовок корня пути ставится явно в каждом запросе. Если его опустить, загрузки успешно проходят в пространство имён, которого больше никто не видит.
Загрузки больше 150 МБ обязаны идти через API сессии загрузки по частям.
Из Telegram-бота до этого доходит редко, потому что Telegram ограничивает скачивание ботом 20 МБ. Порог важен там, где файл собирается на сервере до подшивки.
Лимиты частоты применяются к приложению и к пользователю и возвращают значение retry-after.
Присланное значение соблюдается. Dropbox строже большинства хранилищ относится к длительному потоку запросов, поэтому пакетная подшивка идёт с выдержкой.
К файлам можно обращаться по пути или по устойчивому идентификатору файла.
Для всего, что боту потребуется найти снова, сохраняются идентификаторы. Пути меняются, когда сотрудники переставляют папки, а переставлять папки — это и есть смысл общих папок.
Как это ломается и что происходит потом
Файлы загружаются успешно, и никто не может их найти.
Не был указан заголовок корня пути, поэтому они ушли в личное пространство имён. Это определяющий баг интеграции с Dropbox, и выглядит он как проблема прав доступа — оттого его так долго и ищут.
Refresh-токен отзывается, когда авторизовавший приложение сотрудник увольняется.
Подшивка останавливается целиком. Приложение авторизуется от аккаунта, который должен пережить конкретных людей, а сбой поднимает тревогу, а не молотится в повторах об стену.
Два документа с одинаковым именем попадают в одну папку.
Dropbox либо переименует, либо перезапишет — в зависимости от запрошенного режима. Режим задаётся явно, потому что и молчаливое переименование, и молчаливая перезапись плохи, каждое по-своему.
На пакете подшивок упираемся в лимит частоты.
Очередь выдерживает паузу по значению retry-after. Долговечная копия означает, что задержка стоит времени, а не документов.
Доступность в ОАЭ и остальных странах Залива
Клиенты Dropbox Business
Тот случай, под который всё и рассчитано. Работа с командным пространством — основной объём интеграции, и именно она делает результат пригодным для всей команды.
Индивидуальные аккаунты Dropbox
Проще, вопроса пространств имён нет вовсе, и подходит скорее практикующему в одиночку, чем компании.
Размещение данных
Dropbox предлагает региональное размещение данных на части бизнес-тарифов. Проверьте, в каком регионе фактически лежит ваше командное пространство, а не исходите из предположений.
Работа через синхронизацию на компьютер
Настоящее преимущество этого варианта. Файл появляется в папке на ноутбуке, и никому не нужно открывать браузер, а это заметно снижает порог.
Когда эту интеграцию делать не нужно
- Ваша команда сидит на Workspace или Microsoft 365. Используйте то хранилище, которым организация уже управляет, а не добавляйте третье.
- Вам нужно управление документами с версиями по делам. Dropbox хранит и синхронизирует файлы; делами он не управляет.
- Документы клиентов обязаны оставаться в конкретной юрисдикции. Уточните регион вашего командного пространства до того, как выберете его.
- Структуру папок никто не согласовал. Последовательная подшивка в согласованную структуру — это и есть большая часть пользы.
На чём это работает
| Компонент | Версия | Зачем |
|---|---|---|
| Cloudflare Workers | current | Обновление токенов, разрешение пространства имён и загрузки с выдержкой. |
| Cloudflare R2 | current | Долговечная копия, которая пишется до загрузки в Dropbox. |
| Cloudflare D1 | current | Идентификаторы файлов, сопоставление папок и очередь подшивки. |
| Zod | 4.4 | Валидация ответов API, которые различаются у командных и личных вызовов. |
Вопросы, которые возникают при оценке
Почему никто не может найти загруженные ботом файлы?
Почти наверняка не был указан заголовок корня пути, и загрузки ушли в личное пространство имён авторизовавшегося участника, а не в командное. Ошибки при этом нет, поэтому всё выглядит как загадка с правами доступа, а не как то, чем является, — как проблема адресации.
Обращаться к файлам по пути или по идентификатору?
По идентификатору для всего, что боту понадобится найти снова. Пути меняются каждый раз, когда сотрудники переставляют содержимое общей папки, а переставлять содержимое — ровно то, для чего общие папки и существуют.
Что происходит, когда у двух файлов совпадает имя?
Dropbox переименует или перезапишет в зависимости от запрошенного режима, поэтому режим задаётся явно. Молчаливое переименование теряет связь с делом, молчаливая перезапись теряет документ. Ни то, ни другое не должно быть умолчанием, которое никто не выбирал.
Упираемся ли мы в порог загрузки по частям?
Из Telegram-бота редко, потому что Telegram ограничивает скачивание ботом 20 МБ. Порог важен только там, где файл собирается на сервере до подшивки, а это уже другой сценарий.
Что будет, когда авторизовавший приложение человек уволится?
Подшивка остановится — поэтому авторизация должна идти от аккаунта, который переживёт конкретных людей. Сбой поднимает тревогу, а не уходит в бесконечные повторы: отозванный токен никакими повторами не восстановить.
В чём реальное преимущество перед веб-хранилищем?
Синхронизация на компьютер. Файл появляется в папке на ноутбуке, и никому не нужно открывать браузер, а именно этот сниженный порог обычно и объясняет, почему в компании на Dropbox подшитым ботом материалом действительно пользуются.
Что почитать дальше
У организаций на Workspace аналогом, со своей собственной ловушкой владения, будет интеграция с Google Drive.
Если организация живёт в Microsoft 365, читайте про интеграцию с SharePoint.
Файлы сюда складывает бот сбора документов.
Права и паспорта подшиваются по той же схеме — её использует бот аренды автомобилей.