> For the complete documentation index, see [llms.txt](https://support.suptask.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.suptask.com/integrations-automations-and-workflows/integration-guides/atlassian-confluence.md).

# Atlassian Confluence

Answer and manage tickets with content from your Confluence spaces

{% hint style="info" %}
Confluence is a knowledge base connector for Suptask AI. It is configured per Assistant, alongside the Assistant's other connectors and tools.
{% endhint %}

The Confluence connector lets a Suptask AI Assistant search your Confluence spaces and use that content to answer and deflect tickets directly in Slack. Depending on the scopes you grant, the Assistant can also write back to Confluence - adding comments, labels or new pages from a ticket.

You connect Confluence with an **Atlassian API token**. The token is created by a specific Confluence user, and the connector inherits that user's access. You also choose exactly which **scopes** the token carries, which decides whether the connector can only read your content or also change it.

***

### What you can use it for

* **Auto-answer requests** — a user submits a ticket and the Assistant answers from your Confluence documentation.
* **Support your agents** — an agent asks the Assistant on a ticket and gets an answer grounded in your internal pages.
* **Deflect repeat questions** — recurring questions that are already documented get answered without an agent stepping in.
* **Team-specific knowledge** — HR connects its own space, IT connects its own space, without either seeing the other's content.
* **Write back from a ticket** — with write scopes enabled, the Assistant can add a comment, label a page or draft new documentation based on a resolved ticket.

***

### How access works

Three layers decide what the connector can actually do. Each one narrows the layer above it.

1. **The Confluence user** - the token inherits the space and page permissions of the user who creates it. Suptask can reach what that user can reach, and nothing more.
2. **The token scopes** - you select which read and write scopes the token carries. A token without write scopes cannot change anything in Confluence, regardless of the user's permissions.
3. **The Assistant's tools** - inside Suptask you decide, per Assistant, which of the connector's tools it may use and whether it needs agent approval first.

{% hint style="warning" %}
Avoid creating the token with an account that has access to every space, such as a Confluence admin. The connector will be able to read the same content, including spaces you did not intend to expose to ticketing.
{% endhint %}

***

### Before you begin

You'll need:

* An **admin** role in Suptask.
* A **Confluence Cloud** site.
* A decision on **which Confluence user to connect** — this determines what Suptask can reach. See the section above.
* Access to that user's [Atlassian account security settings](https://id.atlassian.com/manage-profile/security/api-tokens).
* The **Inbox** and **Assistant** you want to connect Confluence to.

What you'll do:

* [ ] Choose or create the Confluence user for the integration
* [ ] Create an API token with scopes
* [ ] Select the read and write scopes you need
* [ ] Add the connector in Suptask
* [ ] Choose which tools your Assistant may use

{% hint style="info" %}
Keep the Connect Confluence window in Suptask open in a separate browser tab. You'll switch back to it at the end.
{% endhint %}

***

### Step 1: Choose the Confluence user

The connector acts as the user who creates the API token. Before creating it, decide whose access you want the Assistant to have.

For most setups, create a **dedicated Confluence user** for the integration and grant it access only to the spaces you want available to ticketing. This keeps the Assistant's reach predictable and independent of any one employee's permissions.

* **Space level** — give the user permission only to the spaces the Assistant should use.
* **Page level** — page restrictions in Confluence still apply. A restricted page stays hidden unless the connected user is included.
* **Per Inbox** — if different teams need different content, use a separate Confluence user and token per Inbox.

{% hint style="info" %}
Giving the dedicated user access to a space also gives access to the pages within it. This is usually the easiest way to expose a whole documentation area at once.
{% endhint %}

***

### Step 2: Create an API token with scopes

Sign in to Atlassian as the user you chose in Step 1.

1. Go to [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens) and open **Security → API tokens**.
2. Click **Create API token with scopes**.
3. Enter a **Name** you'll recognize later, for example `Suptask Prod`.
4. Choose an **Expiry** according to your security policy.
5. Select the app: **Confluence**.
6. Select the scopes you need — see Step 3.
7. Click **Create**, then copy the token.

{% hint style="warning" %}
Atlassian only shows the token once. Copy it and store it securely before leaving the page — if you lose it, you'll need to create a new one.
{% endhint %}

{% hint style="info" %}
Use Create API token with scopes, not Create API token. Only scoped tokens let you control what the connector may read and write.
{% endhint %}

Two Atlassian limits are worth knowing:

* An account can hold a maximum of **25 API tokens** at a time.
* A new token can take up to **a minute** to start working. If the first connection attempt fails, wait and try again.

***

### Step 3: Select the scopes

Scopes set the outer boundary of what the connector can do. Start with the read scopes, and add write scopes only if you want the Assistant to change content in Confluence.

#### Read scopes

The baseline for answering tickets from your documentation:

| Scope                                | What it allows                       |
| ------------------------------------ | ------------------------------------ |
| `search:confluence`                  | Search across Confluence content     |
| `read:confluence-content.all`        | Read all content the user can access |
| `read:confluence-content.summary`    | Read content summaries               |
| `read:confluence-content.permission` | Read content permissions             |
| `read:page:confluence`               | Read pages                           |
| `read:content:confluence`            | Read content                         |
| `read:content-details:confluence`    | Read content details                 |
| `read:content.metadata:confluence`   | Read content metadata                |
| `read:content.property:confluence`   | Read content properties              |
| `read:custom-content:confluence`     | Read custom content                  |
| `read:space:confluence`              | Read spaces                          |
| `read:space-details:confluence`      | Read space details                   |
| `read:confluence-space.summary`      | Read space summaries                 |
| `read:confluence-user`               | Read user profiles                   |
| `read:confluence-groups`             | Read groups                          |

Additional read scopes are available for permissions, restrictions, relations, databases, email addresses and space settings. Add them only if your workflows need them.

#### Write scopes

Add these only if the Assistant should create or update content in Confluence:

| Scope                               | What it allows                 |
| ----------------------------------- | ------------------------------ |
| `write:confluence-content`          | Create and update content      |
| `write:content:confluence`          | Create and update content      |
| `write:comment:confluence`          | Add comments to pages          |
| `write:blogpost:confluence`         | Create and update blog posts   |
| `write:attachment:confluence`       | Add attachments                |
| `write:confluence-file`             | Upload files                   |
| `write:label:confluence`            | Add labels                     |
| `write:inlinetask:confluence`       | Create and update inline tasks |
| `write:embed:confluence`            | Add embedded content           |
| `write:content.property:confluence` | Set content properties         |

{% hint style="info" %}
Start read-only. You can create a new token with write scopes later and update it in Suptask - existing scopes on a token can't be changed after it's created.
{% endhint %}

{% hint style="warning" %}
Scopes don't override Confluence permissions. A write scope only lets the connector change pages the connected user is already allowed to edit.
{% endhint %}

You can review the scopes on an existing token at any time from **Security → API tokens → View scopes**.

***

### Step 4: Add the connector in Suptask

Add Confluence to the Assistant that should use it.

1. In Suptask, navigate to **Intelligence** in the menu and select the Inbox.
2. Add the **Confluence** connector.
3. Enter your **Confluence site URL**, for example `https://yourcompany.atlassian.net`.
4. In the authentication field, enter:
   1. `[TOKEN]` — the API token from Step 2
5. For the Cloud tenant ID, use the provided link below the field to collect this value (format of an UUID).
6. **Save** to store the connector.
7. Open the **Assistant** you want to connect Confluence to.
8. Enable the Confluence permissions for the Assistant.

When it's done, the connector status changes to connected.

***

### Step 5: Choose which tools your Assistant may use

The scopes you selected set what's possible. Inside Suptask you then decide, per Assistant, which of the connector's **tools** it may actually use.

Each tool can be set to:

* **Auto** — the Assistant uses the tool on its own when it's relevant.
* **Ask** — the Assistant prepares the action and pauses for an agent to approve before it runs.
* **Off** — the Assistant can't use the tool at all.

A common setup is **Auto** for read-only tools such as searching pages, and **Ask** for anything that writes to Confluence, such as adding a comment or creating a page.

{% content-ref url="/pages/EMXzCysY1oz2JPFXI8gH" %}
[AI Assistants](/suptask-ai/ai-assistants.md)
{% endcontent-ref %}

***

### Example of how it can work

{% hint style="info" %}
Every Assistant can be customized to your needs. Below are examples of how the Confluence connector can work once connected.
{% endhint %}

**A) Automatic answering and deflection**

1. A **user submits a ticket** in Suptask.
2. The Assistant **searches Confluence** for relevant pages based on the request.
3. A suggested answer is **posted automatically** in the ticket, either directly to the requester or visible only to agents.
4. The user can close the ticket if the answer resolves their issue, or keep it open for an agent.

**B) Agent co-worker**

1. A ticket is **opened and handled by an agent**.
2. The agent mentions **`@Suptask`** in the ticket.
3. The Assistant returns the most relevant Confluence pages as context, so the agent can reply faster without leaving Slack.

**C) Keep documentation up to date**

1. A ticket is resolved with an answer that isn't documented yet.
2. The agent asks the Assistant to capture it in Confluence.
3. With write scopes enabled, the Assistant drafts a comment or a new page — set to **Ask** so the agent approves it before it's published.

***

### Use different Confluence content per Inbox

Each Inbox in Suptask has its own connector. This means different teams can connect different parts of Confluence:

* **HR Inbox** — connects to the HR space and policy pages.
* **IT Inbox** — connects to the IT space and troubleshooting documentation.
* **Finance Inbox** — connects to expense and invoicing documentation.

A ticket in the HR Inbox is then only answered from HR content, and a ticket in the IT Inbox only from IT content. To separate access fully, connect each Inbox with its own Confluence user and token.

***

### Troubleshooting

* **Authentication failed (401)** — the email and token don't match, or the token was revoked. Confirm `[EMAIL]` belongs to the user who created the token, then re-enter or create a new `[TOKEN]`.
* **The connection fails right after creating the token** — a new Atlassian token can take up to a minute to become active. Wait and try again.
* **Permission denied (403)** — the token is missing a required scope. Scopes can't be edited after creation, so create a new token with the scopes you need and update it in Suptask.
* **No results returned** — the connected Confluence user doesn't have access to the relevant space, or the pages are restricted. Check that user's space and page permissions in Confluence.
* **New pages aren't picked up** — make sure the new page sits in a space the connected user has access to, and that no page restriction excludes them.
* **The Assistant answers from the wrong content** — check which Confluence user is behind the token on that Inbox's connector, and reconnect if needed.
* **The Assistant can read but not change anything** — the token has no write scopes, or the write tools are set to **Off** on the Assistant.
* **The Assistant won't perform an action** — the tool is set to **Off**, or it's set to **Ask** and is waiting for an agent to approve.
* **It worked before and stopped** — the token has expired, was revoked, or the connected user was deactivated. Create a new token and update it in Suptask.

***

### Need help?

Reach out to [Suptask Support](https://support.suptask.com/getting-started/contact-support) and our team will help you connect Confluence.