Integration

Dropbox, and the namespace your files are not in

A Dropbox integration files documents collected in Telegram into a team folder structure. The detail that catches implementations is the team space: an app authenticated to a business account defaults to a member's personal namespace, so files land somewhere nobody is looking.

Dropbox integration: auth, limits and availability

Auth model: OAuth 2.0
Namespace: Business accounts have a team space plus per-member spaces; calls default to one
GCC availability: No regional restriction; Business team-space handling is the integration work
Data flow: 5 hops, worker-mediated

As of 2025-10-01, Telegram Bot API 13.4

Why this integration exists

Dropbox Business remains common among GCC firms who standardised on it before the alternatives matured, and for document collection it works well — desktop sync means files appear in a folder on a laptop without anyone opening a browser, which is a meaningfully lower barrier than a web-only store.

The namespace model is the part that goes wrong. A Dropbox Business account has a team space alongside each member's personal space, and an API call defaults to the authenticating member's root rather than the team's. The upload succeeds, the API returns a path, and the file is in a place the rest of the team cannot see. Nothing errors, which is what makes it expensive to diagnose.

The fix is to resolve the team namespace explicitly and set the path root header on every request. It is one header and it is easy to omit, and the symptom — files that exist and are invisible — sends people looking at permissions rather than at namespaces.

How the data actually moves

The team namespace is resolved once and asserted on every request, so files cannot silently land in a member's personal space.

OAuth 2.0 producing a refresh token held as a Worker secret, with short-lived access tokens obtained from it. For a business account the app is granted team scopes and every request carries an explicit path root header identifying the team namespace, rather than relying on the authenticating member's default.

Auth model: OAuth 2.0

Their limits, and what they mean for you

A Dropbox Business account has a team space and per-member personal spaces, and API calls default to the member root.

The path root header is set explicitly on every request. Omitting it produces uploads that succeed into a namespace nobody else can see.

Uploads above 150 MB must use the chunked upload session API.

Rarely reached from a Telegram bot, since Telegram caps bot downloads at 20 MB. It matters for anything that assembles files server-side before filing them.

Rate limits are applied per app and per user, returning a retry-after value.

The supplied value is honoured. Dropbox is stricter than most stores about sustained request rates, so batch filing is paced.

Files can be addressed by path or by a stable file id.

Ids are stored for anything the bot needs to find again. Paths change when staff reorganise, and reorganising is what shared folders are for.

How it fails, and what happens when it does

Files upload successfully and nobody can find them.

The path root header was missing, so they went to a personal namespace. It is the defining Dropbox integration bug and it looks like a permissions problem, which is why it takes so long to spot.

A refresh token is revoked when the authorising member leaves.

All filing stops. The app is authorised by an account intended to outlast individuals, and the failure alerts rather than retrying into a wall.

Two documents with the same name are filed into one folder.

Dropbox will rename rather than overwrite depending on the mode requested. The mode is set explicitly, since silent renaming and silent overwriting are both bad in different ways.

Rate limits are hit during a batch of filings.

The queue paces against the retry-after value. The durable copy means the delay costs time rather than documents.

Availability in the UAE and the wider GCC

Dropbox Business customers

The intended case. Team space handling is the main integration work and is what makes it usable across a team.

Individual Dropbox accounts

Simpler, with no namespace question, and appropriate for a sole practitioner rather than a firm.

Data residency

Dropbox offers regional data residency on some business plans. Confirm which region your team space sits in rather than assuming.

Desktop-sync workflows

The genuine advantage here. Files appear in a folder on a laptop without anyone opening a browser, which lowers the barrier considerably.

When not to use this integration

Your team is on Workspace or Microsoft 365. Use the store your organisation already administers rather than adding a third.
You need document management with versioned matters. Dropbox stores and syncs files; it does not manage cases.
Client documents must stay in a specific jurisdiction. Confirm your team space region before selecting it.
Nobody has agreed a folder structure. Consistent filing into an agreed structure is most of the value.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Token refresh, namespace resolution and paced uploads.
Cloudflare R2	current	Durable copy written before the Dropbox upload.
Cloudflare D1	current	File ids, folder mapping and the filing queue.
Zod	4.4	Validation of API responses, which differ between team and personal calls.

Questions that come up during scoping

Why can nobody find the files the bot uploaded?

The path root header was almost certainly missing, so uploads went into the authenticating member's personal namespace rather than the team space. Nothing errors, which is why it presents as a permissions mystery rather than as the addressing problem it is.

Should files be addressed by path or by id?

By id for anything the bot needs to find again. Paths change whenever staff reorganise a shared folder, and reorganising is precisely what shared folders are for.

What happens when two files have the same name?

Dropbox renames or overwrites depending on the mode requested, so the mode is set explicitly. Silent renaming loses the relationship to the matter; silent overwriting loses a document. Neither should be a default nobody chose.

Do we hit the chunked upload threshold?

Rarely from a Telegram bot, since Telegram caps bot downloads at 20 MB. It matters only where files are assembled server-side before filing, which is a different flow.

What happens when the person who authorised the app leaves?

Filing stops, which is why authorisation should come from an account intended to outlast individuals. The failure alerts rather than retrying into a wall, since no amount of retrying restores a revoked token.

What is the real advantage over a web-only store?

Desktop sync. Files appear in a folder on a laptop without anyone opening a browser, and that lower barrier is often why a firm on Dropbox actually uses what the bot files.