How to connect Confluence

ChatbotIQ reads Confluence Cloud through the Atlassian API rather than crawling it in a browser. That matters for two reasons:

• SSO is not a blocker. Atlassian API tokens bypass SAML, so wikis with anonymous access turned off work fine. This is the recommended way to index Confluence.
• Syncs stay cheap. Confluence reports a version number per page, so a repeat sync only re-reads pages someone actually edited.

If you previously added your wiki as a website source, switch it to a Confluence source. You will get cleaner content, page hierarchy in search, and much faster refreshes.

Before you start

You need:

• A Confluence Cloud site (your-site.atlassian.net). Self-hosted Data Center is not supported yet.
• An Atlassian account that can see the spaces you want to index.
• Admin or owner role in your ChatbotIQ workspace.

Create a service account first

Read this before creating a token. It is the difference between a safe setup and one that quietly leaks internal pages.

An Atlassian API token inherits every permission of the account that created it. If you create a token on your own admin account, ChatbotIQ can read every page you can see, including HR, legal, and restricted spaces. If that bot is public-facing, those pages can end up in answers.

So:

1. Create a dedicated Atlassian account for ChatbotIQ (for example [email protected]).
2. Grant it view access to only the spaces you intend to index.
3. Create the API token on that account, not on your own.

Step 1: Create a scoped API token

Atlassian supports scoped tokens, which grant only the permissions you list instead of everything the account can do. Use one.

1. Go to Atlassian API tokens.

2. Choose Create API token with scopes.

3. Select your Confluence site.

4. Select exactly these three scopes, and nothing else:

   Scope	Why it is needed
   read:space:confluence	List your spaces so you can pick which to index
   read:page:confluence	List the pages in those spaces
   read:content-details:confluence	Read page content

5. Set an expiry date and write it down. You will need it in Step 2.

6. Copy the token. Atlassian shows it once.

Every Atlassian token expires. The maximum lifetime is 365 days, and there is no way to create a permanent one. When the token expires, syncing stops. Tell ChatbotIQ the expiry date in the next step and we will remind you before that happens.

Step 2: Connect the site

1. In ChatbotIQ, open Knowledge Base and click Add source.
2. Choose Confluence.
3. Fill in:
   • Confluence site: https://your-site.atlassian.net (or just the site name)
   • Atlassian account email: the service account’s email
   • API token: the token from Step 1
   • Token expiry date: from Step 1
4. Click Connect.

ChatbotIQ verifies the credentials immediately. If they are wrong or the scopes are insufficient, you will see an error here rather than an empty sync later.

Your token is encrypted before it is stored, and no ChatbotIQ screen or API response ever shows it again. You will only see the last four characters.

Step 3: Choose spaces and sync

After connecting, you will see every space the token can read.

Select only the spaces you want your bot to answer from. This list is the main control against indexing more than you meant to. ChatbotIQ reads nothing outside it, and the restriction is enforced on the server, not just in the interface.

Give the source a name, then click Start sync.

The first sync reads every page in the selected spaces. Large wikis take a while; you can close the wizard and the sync continues in the background.

What gets indexed

For each page ChatbotIQ stores the title, the content, and its place in the wiki:

• Page hierarchy becomes a breadcrumb (Operations > Runbooks > Deployment Runbook), which improves how well the bot matches questions to pages.
• Real page URLs, so answers cite a clickable link to the wiki page.
• Last edited date from Confluence, not the sync time.

Tables, code blocks, and lists are preserved. Attachments and images are not indexed yet.

Keeping content up to date

Run a sync whenever you want to pick up changes. Repeat syncs are cheap: ChatbotIQ compares each page’s Confluence version number and only re-reads pages that changed. A sync of an unchanged wiki uses no indexing credits.

Pages that are deleted, archived, or moved out of a selected space are removed from your bot’s answers on the next sync.

Troubleshooting

“Confluence rejected the credentials” The token has expired or been revoked. Create a new one and reconnect. Remember the 365-day maximum.

“The token is missing a required scope” The token is missing one of the three scopes in Step 1. Scoped tokens cannot be edited after creation, so create a new one.

“This token cannot see any spaces” The service account has not been granted access to any space. Add it to the spaces you want indexed in Confluence’s space permissions.

A space is missing from the list The service account cannot see it. Grant it view permission on that space in Confluence.

Some pages are missing after a sync Confluence page restrictions apply to the service account too. A page restricted from that account is invisible to ChatbotIQ, which is usually what you want.

“Only Confluence Cloud sites are supported” You entered something other than a *.atlassian.net address. Self-hosted Confluence Data Center is not supported yet.

Related

• Source types
• Build a Knowledge Bot for Confluence
• Keep content up to date