UniPulse integrates with three social platforms for publishing, analytics, and conversation management. All social API interactions go through the backend -- the frontend never calls platform APIs directly.
| Platform | API | Auth | Publishing | Metrics | Conversations |
|---|
| Facebook | Meta Graph API v19+ | OAuth 2.0 (Facebook Login) | Yes | Yes | Yes |
| Instagram | Meta Graph API v19+ | OAuth 2.0 (via Facebook) | Yes | Yes | Yes |
| TikTok | Content Publishing API | OAuth 2.0 (Login Kit) | Yes | Yes | Yes (limited) |
Authentication
| Step | Endpoint | Scopes |
|---|
| OAuth initiation | GET /api/v1/auth/oauth/facebook | pages_manage_posts, pages_read_engagement, pages_manage_metadata, instagram_basic, instagram_content_publish, instagram_manage_comments, instagram_manage_insights |
| Token exchange | Facebook OAuth callback | Access token + page tokens |
| Token refresh | Automatic via token-refresh queue | Long-lived tokens (60 days) |
Publishing
| Platform | API Call | Content Types |
|---|
| Facebook Page | POST /{page-id}/feed | Text, images, videos, links |
| Instagram | POST /{ig-user-id}/media + POST /{ig-user-id}/media_publish | Images, carousels, reels |
Metrics Sync
| Metric | API | Sync Queue |
|---|
| Post reach, impressions | GET /{post-id}/insights | analytics-sync |
| Post engagement (likes, comments, shares) | GET /{post-id}?fields=likes,comments,shares | analytics-sync |
| Page follower count | GET /{page-id}/insights | analytics-sync |
Conversations
| Feature | API | Queue |
|---|
| Read comments | GET /{post-id}/comments | ice-process |
| Reply to comments | POST /{comment-id}/replies | via sendAgentReply() |
| Read DMs | Messenger Platform API | ice-process |
| Webhooks (real-time) | Facebook Webhooks (comment, message events) | webhook-process |
TikTok (Content Publishing API)
Authentication
| Step | Endpoint | Scopes |
|---|
| OAuth initiation | GET /api/v1/auth/oauth/tiktok | user.info.basic, video.publish, video.list, video.insights |
| Token exchange | TikTok OAuth callback | Access token + refresh token |
| Token refresh | Automatic via token-refresh queue | Refresh token (90 days) |
Publishing
| API Call | Content Types |
|---|
| Content Publishing API (v2) | Videos, images (photo mode) |
Metrics Sync
| Metric | API |
|---|
| Video views, likes, comments, shares | TikTok Insights API |
| Profile follower count | TikTok User Info API |
Token Management
Social platform tokens are stored encrypted in the SocialAccount model:
| Field | Storage |
|---|
accessToken | AES-256 encrypted (using ENCRYPTION_KEY) |
refreshToken | AES-256 encrypted |
tokenExpiresAt | Plaintext DateTime |
Automatic Token Refresh
The token-refresh queue proactively refreshes tokens before they expire:
Rate Limiting
Each platform enforces API rate limits. UniPulse implements per-platform rate limiting to stay within bounds:
| Platform | Rate Limit | Strategy |
|---|
| Facebook/Instagram | 200 calls per hour per user | Queue-based throttling |
| TikTok | Varies by endpoint | Exponential backoff on 429 |
The publish queue processes one platform at a time and implements backoff when rate limits are hit.
Environment Variables
| Variable | Platform | Required For |
|---|
FACEBOOK_APP_ID | Facebook/Instagram | OAuth initiation |
FACEBOOK_APP_SECRET | Facebook/Instagram | Token exchange |
INSTAGRAM_CALLBACK_URL | Instagram | OAuth callback |
TIKTOK_CLIENT_KEY | TikTok | OAuth initiation |
TIKTOK_CLIENT_SECRET | TikTok | Token exchange |