> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Circle Integration (Beta)

> Connect BuildBetter with Circle to capture insights from your community discussions

Connect BuildBetter with Circle to import community posts and discussions, extracting insights from member feedback and conversations.

## Features

* **Space Selection**: Choose exactly which Circle spaces to sync instead of importing everything
* **Post Import**: Automatically sync published posts as conversations in BuildBetter
* **Comment Threads**: Import full comment threads for complete context
* **Per-Space Incremental Sync**: Each space tracks its own sync progress for efficient updates
* **Comment Refresh Window**: Recheck recently imported posts for new comments on a configurable schedule
* **Member Data**: Capture author information including profiles and activity stats
* **Engagement Metrics**: Preserve likes, comments counts, and engagement data

## How It Works

BuildBetter connects to Circle via API token and imports community posts with their comment threads. Each post becomes a conversation, enabling AI-powered analysis to identify trends, feature requests, and community sentiment.

**Import Type**: One-way (Circle to BuildBetter)
**Sync Frequency**: Hourly automatic sync

## Setup Guide

### Prerequisites

1. **Circle Requirements:**
   * Circle community on Business or Enterprise plan
   * Admin access for API token generation

2. **BuildBetter Requirements:**
   * Active BuildBetter account
   * Admin privileges for integration setup

### Quick Setup

1. **Get Your Circle API Token**
   * Log in to your Circle community as an Admin
   * Navigate to **Settings > API**
   * Generate a new Admin API token
   * Copy and save the token securely

2. **Connect in BuildBetter**
   * Go to **Settings > Integrations** in BuildBetter
   * Find Circle in the Social section and click **Connect**
   * Paste your Circle API token
   * Click **Connect** to verify

3. **Select Spaces to Sync**
   * After connecting, BuildBetter fetches your available spaces
   * Select the spaces you want to import (or leave all selected)
   * Deselect spaces you want to exclude from sync

4. **Configure Import Settings**
   * **Import History**: Choose how far back to import
     * None (new posts only), 4 hours (default), 7 days, 30 days, 90 days, 180 days, 365 days, or all
   * **Comment Refresh Window** (optional): How far back to re-check imported posts for new comments
     * None (default), 7 days, 14 days, 30 days — see [Comment Refresh Window](#comment-refresh-window) below
   * Click **Save** to start your first sync

## What Gets Imported

### Post Data

| Circle Field    | BuildBetter Field  | Notes                             |
| --------------- | ------------------ | --------------------------------- |
| Post name       | Conversation title |                                   |
| Content         | Message body       | HTML and Tiptap formats supported |
| URL             | External link      | Link back to Circle post          |
| Status          | Metadata           | Post status (published, etc.)     |
| Topics          | Tags               | Preserved for filtering           |
| Created/Updated | Timestamps         |                                   |

### Comments

Comments are imported as conversation messages:

* Full comment content
* Author information
* Timestamps
* Nested replies (parent-child relationships)
* Engagement metrics

### People

Community members are automatically created or matched:

* Name and email (for matching)
* Headline and bio
* Avatar
* Activity stats (posts, comments, likes)
* Gamification data (levels, points)
* Member tags and custom profile fields

### Metadata

Each imported post includes:

* Space ID and name
* Topics/tags
* Engagement metrics (likes count, comments count)
* Post status
* Source identifier (circle)

## Space Selection

### Why Select Spaces?

Not all community spaces may contain relevant product feedback. Space selection lets you:

* Focus on spaces with customer discussions
* Exclude internal or off-topic spaces
* Reduce noise in your insights

### Managing Spaces

1. Go to your Circle integration settings
2. Click **Configure Spaces**
3. Check/uncheck spaces to include or exclude
4. Save your changes

<Note>
  Each space maintains its own sync progress. Adding a new space will import its history based on your backfill setting.
</Note>

## Sync Behavior

### Per-Space Incremental Sync

* Each space tracks when it was last synced
* Only new and updated posts are fetched after initial import
* Adding a space starts a fresh sync for that space only

### Automatic Sync

* Runs hourly to capture new posts and comments
* Smart cutoff logic prevents duplicate imports
* Early termination when reaching already-imported posts

### Backfill Options

| Setting           | Behavior                                |
| ----------------- | --------------------------------------- |
| None              | Only sync new posts going forward       |
| 4 hours (default) | Import posts from last 4 hours          |
| 7d - 365d         | Import posts from specified time window |
| All               | Import entire community history         |

### Comment Refresh Window

Circle posts often pick up comments long after the post itself is published. The **comment refresh window** controls how far back the integration rechecks already-imported posts for new comments.

| Setting        | Behavior                                                                     |
| -------------- | ---------------------------------------------------------------------------- |
| None (default) | Don't re-check imported posts — comments only flow in via new-post sync      |
| 7d, 14d, 30d   | Refresh comments on posts created within the selected window on each sync    |
| Custom         | Any supported window (e.g. `90d`) — match it to how active your community is |

<Tip>
  A wider window catches more late-arriving comments but uses more Circle API calls. Start with 7d or 14d for active communities and widen only if you're missing comments on older posts.
</Tip>

Smarter fetching keeps refreshes efficient:

* **Comment count check** — comments are only re-fetched when Circle reports a different comment count, avoiding unnecessary work
* **Older posts skipped** — posts outside the refresh window are never re-fetched
* **Failure isolation** — if a single post's comments fail temporarily, sync continues for the rest of the space and retries on the next pass

## Use Cases

### Community Feedback Analysis

* Identify common questions and pain points
* Track feature requests from community members
* Monitor sentiment across discussions

### Product Development

* Extract product ideas from community discussions
* Understand how members use your product
* Gather feedback on new features

### Customer Success

* Spot members who may need help
* Identify power users and advocates
* Track community engagement trends

## Troubleshooting

### Connection Issues

**"Invalid API Token" Error**

* Verify you have an Admin API token (not a regular member token)
* Ensure your Circle plan includes API access (Business or Enterprise)
* Try generating a new token

**"Needs Reauthorization" Status**

* Your API token may have been revoked or expired
* Generate a new token in Circle and reconnect

### Spaces Not Loading

* Check that your Circle account has Admin access
* Verify the API token has permission to list spaces
* Try disconnecting and reconnecting

### Posts Not Syncing

* Confirm the space is selected in your settings
* Check that posts are published (drafts aren't imported)
* Verify your backfill date covers the expected time range
* Allow up to 1 hour for the next automatic sync

### Missing Comments on Imported Posts

If a post imported without its comments, the next sync (or the comment refresh window) recovers them automatically. Temporary comment fetch failures no longer block or weaken the rest of the sync — they retry on the following pass.

## Reliability

Circle ingestion has gone through several rounds of hardening:

* **Comment import fixes** — posts no longer import without comments due to transient failures, refreshes don't run unnecessarily when counts haven't changed, and a single failing post can't block sync for the rest of the space
* **Circle API URL fixes** — corrected API URL handling so requests succeed more consistently across endpoints
* **Member lookup behavior** — member resolution is more reliable, with better fallbacks when a member record is incomplete
* **Cursor and retry safety** — billing-limited or interrupted imports resume from the correct point on the next sync, without skipping records or advancing progress prematurely
* **Orphaned spaces** — spaces that disappear from Circle (deleted, archived, or unselected) are handled gracefully in the UI without breaking sync for the remaining spaces

## Privacy & Data

* BuildBetter only imports data from spaces you select
* Posts and comments are stored securely in your BuildBetter workspace
* Member data is used for author attribution only
* You can disconnect at any time to stop all data sync

## Support

Questions about this integration?

* Email: [support@buildbetter.app](mailto:support@buildbetter.app)
* Visit our [Help Center](/pages/Help/common-issues)