Integration

SharePoint, where finding the drive is half the integration

A SharePoint integration files documents collected in Telegram into a document library through Microsoft Graph. The work that surprises people is addressing: reaching a specific library means resolving a site, then a drive, then a folder, and none of those are addressable by the URL staff use.

SharePoint integration: auth, limits and availability

Auth model: OAuth 2.0
Addressing: Site, then drive, then folder — none addressable by path alone
GCC availability: Microsoft 365 tenants; conditional access common in regulated GCC orgs
Data flow: 5 hops, worker-mediated

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

Why this integration exists

Organisations on Microsoft 365 keep documents in SharePoint whether or not anyone calls it that — a Teams channel's Files tab is a SharePoint document library, and most staff have never seen the underlying structure. So a bot filing documents into "the Contracts channel" is really writing to a drive inside a site inside a tenant, addressed by identifiers nobody in the business has seen.

That addressing is the bulk of the integration work, and it is unglamorous. The URL a person copies from their browser is not an API address. Reaching the right library means resolving the site from its hostname and path, listing its drives, selecting the right one, then resolving the folder — and caching all of it, because doing that chain per upload is both slow and a fast route to throttling.

The second surprise is permissions. SharePoint inherits permissions down a hierarchy and allows breaks in that inheritance at any level, which means a folder can be more restricted than its library without anything indicating so from above. An integration with tenant-wide application permissions will happily write into a folder your own staff cannot open, and nobody notices until someone goes looking for a document that is technically filed correctly.

How the data actually moves

Site, drive and folder identifiers are resolved once and cached. Resolving them per upload is slow and is a reliable way to get throttled.

Microsoft Graph with application permissions and admin consent, scoped as narrowly as the tenant allows. Application permissions are tenant-wide by default, which means the integration can reach more than it should; where the tenant supports it, access is restricted to specific sites so the bot cannot write outside the libraries it was given.

Auth model: OAuth 2.0

Their limits, and what they mean for you

Reaching a document library requires resolving a site, then a drive, then a folder, none addressable by the browser URL.

The resolution chain is performed once at setup and cached. It is most of the integration work and none of it is visible in the finished product.

Graph throttles per application and per resource, returning 429 with Retry-After.

The header is honoured rather than replaced with a local backoff. SharePoint throttles more readily than most stores under batch writes.

Uploads above 4 MB require an upload session rather than a simple PUT.

Reached routinely by scanned documents. A simple upload works in testing with phone photographs and fails on the first real scan.

Permission inheritance can be broken at site, library, folder or item level.

A folder can be more restricted than its library with no indication from above. An integration with tenant-wide permissions writes into places staff cannot read.

How it fails, and what happens when it does

Files are filed into a folder nobody in the business can open.

Broken permission inheritance. Target folders are verified against the group that needs them at setup rather than assumed to inherit.

Admin consent is revoked during a tenant policy review.

Every operation fails at once. Surfaced immediately rather than retried, since no amount of retrying restores a withdrawn permission.

A large scan fails with a simple upload.

Upload sessions are used above the threshold. This appears the moment a real client sends a scanned contract rather than a phone photograph.

Cached drive ids become stale after a site is restructured.

Resolution failures trigger a re-resolve rather than a hard failure, with an alert. SharePoint sites get reorganised by people who have no idea a bot depends on them.

Availability in the UAE and the wider GCC

Microsoft 365 tenants

The intended case. Admin consent is required and is a scheduling dependency rather than a developer task.

Tenants with conditional access

Widespread in regulated GCC organisations, and it can refuse an application token outright even when consent was granted. Establish the policy before scoping, not during the build.

Data residency

Microsoft offers regional tenant hosting including the UAE, which is a genuine advantage where a regulator requires local residency.

Retention and compliance policies

Configured in Microsoft Purview rather than by the bot. The bot files; retention belongs to your compliance administrators.

When not to use this integration

Your IT function will not grant admin consent. There is no viable integration without it and it is worth establishing first.
Conditional access blocks application permissions. Common in regulated organisations and a hard stop.
Staff actually keep documents somewhere else. File where people look, not where the org chart says they should.
You need matter management rather than storage. SharePoint holds files; it does not manage cases without substantial configuration.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Graph auth, cached resolution and upload sessions.
Cloudflare R2	current	Durable copy written before the Graph upload.
Cloudflare KV	current	Site, drive and folder id cache with re-resolve on failure.
Cloudflare D1	current	Filing state per matter and the upload queue.

Questions that come up during scoping

Why can we not just give the bot a SharePoint URL?

Because the URL staff copy from their browser is not an API address. Reaching a library means resolving a site, then a drive, then a folder by identifiers nobody in the business has seen. That chain is most of the integration work and is invisible in the result.

Why are filed documents sometimes invisible to staff?

Broken permission inheritance. A folder can be more restricted than its library with nothing indicating so from above, and an integration with tenant-wide permissions writes there happily. Target folders are verified against the group that needs them at setup.

Why do uploads work in testing and fail with real documents?

The 4 MB threshold. Phone photographs sit below it and simple uploads succeed; a scanned contract sits above it and needs an upload session. It is a reliable way to pass every test and fail on the first real client.

Do we need our IT department?

Yes, for admin consent and possibly for conditional access policy. It is a scheduling dependency rather than a developer task, and starting the conversation early saves more time than any technical choice on the project.

Is SharePoint better for data residency than Google Drive?

Potentially, since Microsoft offers regional tenant hosting including the UAE. Where a regulator requires local residency of client documents, that is a real and sometimes deciding advantage.

What happens if someone restructures the site?

Cached identifiers go stale, so a resolution failure triggers a re-resolve with an alert rather than a hard stop. SharePoint sites are reorganised by people with no idea an integration depends on them, and it should degrade rather than break.