Integration

Confluence, and the content that macros hide from you

A Confluence integration reads spaces and pages into a Telegram bot, usually as an AI assistant corpus. The extraction problem is macros: a page's stored source contains macro placeholders rather than the content they display, so naive extraction silently loses whatever they render.

Confluence integration: auth, limits and availability

Auth model: Basic auth
Storage format: Confluence storage format — macros appear as placeholders, not rendered output
GCC availability: Cloud is the supported case; Data Center has a different API surface
Data flow: 5 hops, worker-mediated

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

Why this integration exists

Confluence is where established engineering and operations teams keep their documentation, and a corpus drawn from it tends to be higher quality than one drawn from a shared drive — pages have owners, structure and, usually, some review. For an assistant answering internal questions, it is often the best material available in the organisation.

The extraction detail that matters is format. Confluence stores pages in its own storage format, an XML-ish representation containing macros as placeholders. A page that displays a table of environment variables may store a macro reference and nothing else, so extracting the storage format gives you a document that is missing exactly the specific, factual content an assistant is most useful for.

The alternative is the rendered view, which resolves macros and produces the content people actually see — at the cost of an extra call per page and more HTML to clean. For an assistant corpus the rendered view is nearly always right, because the whole value is answering from what is actually written rather than from what happens to be stored inline.

How the data actually moves

The rendered view is requested rather than the storage format, so macro-generated content reaches the index instead of a placeholder.

An API token paired with an account email over HTTP basic authentication for Confluence Cloud, held as a Worker secret. The token inherits that account's space permissions, so a token belonging to a restricted account produces a corpus with holes that look like missing documentation rather than missing access.

Auth model: HTTP basic

Their limits, and what they mean for you

Pages are stored in Confluence storage format, where macros appear as placeholders rather than their output.

The rendered view is requested instead. Extracting storage format loses exactly the tabular, factual content an assistant is most often asked about.

API access inherits the authenticating account's space permissions.

A restricted account produces a corpus with invisible holes. The ingestion report lists the spaces actually seen so the gap is a permissions action rather than a mystery.

Rate limits are applied per account and vary by Confluence Cloud plan.

Full ingestion is paced and incremental. Requesting a rendered view per page doubles the request count against the storage format, which matters at scale.

Archived pages remain retrievable through the API.

Ingesting them produces an assistant that answers from documentation somebody deliberately retired. Archived content is excluded explicitly rather than by hoping it is unreachable.

How it fails, and what happens when it does

The assistant answers without the table that was on the page.

Storage format was extracted rather than the rendered view. It is the defining Confluence extraction bug and it degrades answers rather than breaking them, which is why it survives so long.

The assistant answers from a page nobody has updated in three years.

Archived and stale pages are excluded, and each chunk carries its page's last-modified date so an answer from old material can be flagged as such.

A whole space is missing from the corpus.

A permissions gap on the integration account. The ingestion report names what was reachable, which converts it into a specific request rather than a general complaint.

Ingestion runs long and trips the rate limit.

Incremental sync on last-modified timestamps, paced against the limit. A full re-ingest is a deliberate operation rather than the nightly default.

Availability in the UAE and the wider GCC

Confluence Cloud

The intended case, with a stable REST API and token authentication.

Confluence Data Center

Self-hosted, with a different API surface and network reachability to arrange. Possible and a separate scoping conversation.

Data residency

Atlassian offers regional data residency on some plans. Embedding the content elsewhere is a separate movement of data worth being explicit about.

Spaces with mixed sensitivity

A single integration account either sees a space or does not. Where an assistant must answer differently by audience, that is a design question rather than a permissions one.

When not to use this integration

Your Confluence is largely abandoned. An assistant answering from stale pages is worse than one that says it does not know.
Documentation lives elsewhere in practice. Integrate with where people actually write rather than where the wiki was meant to be.
Different audiences must get different answers from the same space. A single integration account cannot express that.
You are on Data Center with no route in from a Worker. That is a network conversation before it is an integration.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Paced ingestion, rendered-view extraction and chunking.
Cloudflare Vectorize	current	Vector index with page source and last-modified date.
Cloudflare D1	current	Sync cursors, space inventory and ingestion reports.
Zod	4.4	Validation of API responses across page and space endpoints.

Questions that come up during scoping

Why does the assistant miss tables that are clearly on the page?

Because storage format was extracted rather than the rendered view. Macros appear as placeholders in storage format, so exactly the tabular, factual content people ask about is what goes missing. It degrades answers rather than breaking anything, which is why it survives so long undetected.

Why is a whole space missing from the corpus?

The integration account cannot see it. API access inherits that account's space permissions, and the ingestion report names what was reachable so this becomes a specific permissions request rather than a vague complaint about the assistant.

Should archived pages be included?

No, and they remain retrievable through the API, so excluding them is a deliberate step. An assistant answering from documentation somebody explicitly retired is worse than one with a smaller corpus.

How do we handle documentation that is simply old?

Each chunk carries its page's last-modified date, so an answer drawn from old material can be flagged as such. It does not fix stale documentation and it stops the assistant presenting it with unearned confidence.

How does this compare to Notion as a corpus?

Notion's block tree gives cleaner chunk boundaries; Confluence pages tend to have clearer ownership and review. The better corpus is whichever your team actually keeps current, which is a question about your organisation rather than about the tools.

How long does ingestion take?

Longer than the storage format would, because the rendered view is an extra call per page. Incremental sync on last-modified timestamps keeps the ongoing cost proportional to what changed rather than to the size of the wiki.