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 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

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

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

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.

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: [e-mail]
• Visit our Help Center