Socialfire Logo
Socialfire
Get Started

How can we help you?

Search our documentation or browse categories below

search
rocket_launch

Getting Started

Quick start guide to connect Instagram and create your first feed

code

API Reference

Complete API documentation for custom integrations

integration_instructions

Embedding Feeds

Learn how to add Instagram feeds to your website

help

Troubleshooting

Common issues and how to resolve them

Getting Started

1. Connect Your Instagram Account

Socialfire uses Instagram's official API to sync your posts. You'll need an Instagram Business or Creator account to get started.

Quick Steps:

  1. Visit /connect or go to your dashboard
  2. Click "Connect Instagram Account"
  3. Log in to Instagram and authorize access
  4. Your account will appear in the dashboard

Note: Personal Instagram accounts cannot be connected. Convert to Business or Creator in your Instagram settings → Account → Switch to Professional Account.

2. Create Your First Feed

Once your Instagram account is connected, you can create customizable feeds to display your posts.

Steps:

  1. Go to /dashboard/feeds
  2. Click "Create feed"
  3. Select your Instagram source
  4. Configure layout (Grid, Carousel, or Masonry)
  5. Set columns, rows, and display options
  6. Click "Create feed"

3. Sync Your Posts

After creating a feed, you need to sync it to fetch your Instagram posts.

How to Sync:

  • Click the "Refresh" button next to your feed
  • Wait a few seconds while posts are fetched from Instagram
  • Your feed is now ready to embed!

Feeds automatically refresh based on your cache settings (default: 1 hour). You can manually refresh anytime from the dashboard.

Embedding Feeds

Option 1: NPM Package - React/Next.js (Recommended)

Install the official Socialfire widget package:

npm install @volchoklv/socialfire-widget
import { SocialfireWidget } from '@volchoklv/socialfire-widget';

function App() {
  return (
    <SocialfireWidget
      feedId="507f1f77bcf86cd799439011"
      apiUrl="https://your-api.com"
      onLoad={(feed) => console.log('Feed loaded:', feed)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

Important: The feedId must be a MongoDB ObjectId (24 character hex string). You can find this ID on the Feeds page in your dashboard. Slugs are not supported.

The component handles loading states, errors, and responsive layouts automatically.

Option 2: CDN - Vanilla JavaScript

For non-React sites, use the web component via CDN:

<script src="https://cdn.jsdelivr.net/npm/@volchoklv/socialfire-widget/dist/widget.js" type="module"></script>

<socialfire-widget
  feed-id="507f1f77bcf86cd799439011"
  api-url="https://your-api.com">
</socialfire-widget>

<script>
  const widget = document.querySelector('socialfire-widget');
  widget.addEventListener('load', (e) => console.log('Loaded:', e.detail));
  widget.addEventListener('error', (e) => console.error('Error:', e.detail));
</script>

No build tools required. Works in any HTML page.

Option 3: JSON API

For fully custom implementations, use the JSON API directly:

GET /api/feeds/{feedId}

Replace {feedId} with your feed ID (MongoDB ObjectId) or slug. The API returns JSON with all posts and feed configuration.

View Full API Documentationarrow_forward

Test Preview

Test your feed before embedding:

/test-feed?feed=your-feed-slug

This preview page lets you test your feed's appearance and share it with clients for approval.

Troubleshooting

"Invalid platform app" Error

This error occurs when trying to connect a Personal Instagram account.

Solution:

  1. Open Instagram app on your phone
  2. Go to Settings → Account
  3. Tap "Switch to Professional Account"
  4. Choose Business or Creator
  5. Try connecting again

No Posts Showing in Feed

If your feed is empty after creating it:

Checklist:

  • Click the "Refresh" button in the dashboard
  • Wait 10-15 seconds for sync to complete
  • Check that your Instagram account has public posts
  • Verify the Instagram account is still connected

Token Expired Error

Instagram access tokens expire after 60 days. When this happens:

Fix:

  1. Go to your dashboard
  2. You'll see a warning about expired token
  3. Click "Reconnect" or visit /connect
  4. Authorize access again

Feed Not Updating

Feeds are cached for performance. To force an update:

  • Manual: Click "Refresh" in dashboard
  • Automatic: Feeds refresh when cache expires (default 1 hour)
  • You can adjust cache TTL in feed settings

Client Onboarding

Connecting Client Accounts

If you're building feeds for clients, send them the connection link:

https://yourdomain.com/connect

What happens:

  1. Client clicks the link
  2. Beautiful onboarding page explains the process
  3. Client connects their Instagram Business account
  4. Success confirmation shown
  5. Their account appears in your dashboard
  6. You create and manage feeds for them

Security Note: The /connect page is public (no login required) for easy client access. Once connected, only you (admin) can create and manage feeds.

Still need help?

Can't find what you're looking for? Check the API reference or reach out for support.

codeAPI ReferencesupportGet Support