Configuration

Configure the Meta App credentials and module settings required for Social Marketing to connect to Facebook and Instagram.

Required Permissions

Only System Administrators (base.group_system) can access the configuration settings.

Meta Developer App Setup

Before configuring the module, you need a Meta Developer App:

  1. Go to developers.facebook.com

  2. Create a new app or select an existing one

  3. Set the app type to Business

  4. Add the Facebook Login product to your app

  5. In the Facebook Login settings, add the OAuth redirect URI:

    https://your-Progrid-domain.com/social/oauth/callback

    Replace your-Progrid-domain.com with your actual Progrid server URL.

  6. Note your App ID (numeric) and App Secret from the App Dashboard

Required Meta Permissions

Your Meta App must have the following permissions approved (or available in development mode for testing):

  • pages_manage_posts - Publish content to Pages

  • pages_read_engagement - Read engagement metrics

  • pages_manage_engagement - Reply to comments

  • pages_show_list - List user’s Pages during OAuth

  • instagram_basic - Read Instagram account info

  • instagram_content_publish - Publish to Instagram

  • instagram_manage_comments - Read and reply to IG comments

  • instagram_manage_insights - Read Instagram engagement insights

Important

For production use, these permissions must pass Meta’s App Review process. During development, they work for users who have a role on the Meta App.

Module Configuration

Navigate to Social Marketing ‣ Configuration ‣ Settings.

Meta App Credentials

Meta App ID

Your numeric App ID from the Meta Developer Dashboard (e.g., 123456789012345). Must be at least 10 digits.

Meta App Secret (Encrypted)

Your App Secret. This is encrypted with AES-256-GCM before storage using the APP_KMS_KEY environment variable.

API Settings

Graph API Version

The Meta Graph API version to use. Default is v22.0. Must start with v (e.g., v22.0). Only change this if Meta deprecates the current version.

IG Posts Per Day Limit

Instagram’s API limit for posts per 24-hour rolling window. Default is 25. This is Instagram’s platform limit – do not increase unless Meta changes it.

Engagement Sync

Enable Engagement Sync

Toggle automatic syncing of engagement metrics (likes, comments, shares, reach, impressions) for published posts. Enabled by default.

Sync Comments

Toggle comment syncing as part of engagement sync. Only visible when engagement sync is enabled. Enabled by default.

Testing the Configuration

After entering your Meta App credentials:

  1. Click Test Configuration at the bottom of the settings dialog

  2. The system validates that:

    • The App ID is present and numeric

    • The App Secret is stored

    • An authorization URL can be generated

  3. A success or error notification appears

Note

This tests the configuration format only. To fully test the connection, you need to connect an account via the OAuth flow. See Connecting Accounts.

Environment Variables

APP_KMS_KEY

The APP_KMS_KEY environment variable provides the encryption key for all sensitive token storage. It is used to derive a 256-bit AES key via PBKDF2.

Warning

If APP_KMS_KEY is not set, the module falls back to a default key that is not secure for production. Always set this in your server environment.

Set it in your Progrid server environment:

export APP_KMS_KEY="your-strong-random-key-here"

Or in your systemd service file, Docker configuration, or deployment platform’s environment variable settings.

Tip

Generate a strong key with: openssl rand -base64 32

Automated Cron Jobs

The module installs six cron jobs. All are enabled by default:

Job Name

Interval

Description

Process Scheduled Posts

1 minute

Enqueues posts whose scheduled time has arrived

Process Publish Queue

1 minute

Executes queued publish operations (max 25 per run)

Reset Stale Jobs

5 minutes

Re-queues targets stuck in “Processing” for 15+ minutes

Check Token Refresh

6 hours

Refreshes tokens expiring within 7 days

Sync Engagement Metrics

15 minutes

Fetches engagement data with tiered frequency by post age

Cleanup Old Records

Daily

Removes completed/failed targets older than 90 days

To check or modify cron jobs, navigate to Settings ‣ Technical ‣ Automation ‣ Scheduled Actions and search for “Social Publisher”.

Publish Queue

Administrators can monitor the publishing pipeline at Social Marketing ‣ Configuration ‣ Publish Queue.

This shows all queue entries with:

  • Target and post references

  • Account name

  • Scheduled and processed timestamps

  • State (Pending, Processing, Completed, Failed)

  • Processing time in milliseconds

  • Error messages for failed entries

See also