Skip to main content

Social Media ExecModules

The ValkyrAI Workflow Engine provides comprehensive social media publishing capabilities through specialized ExecModules. These modules enable automated posting to major social media platforms with enterprise-grade security, RBAC controls, and idempotency.

Available Social Media Modules​

Instagram Business Publishing (social.instagram.publish)​

Publish images and videos to Instagram Business/Creator accounts via the Facebook Graph API.

Configuration Schema:

{
  "media_type": "IMAGE|VIDEO",
  "source_url": "https://cdn.example.com/image.jpg",
  "caption": "Your post caption (max 2200 chars)",
  "schedule_time": "2024-01-15T10:00:00Z",
  "alt_text": "Accessibility description",
  "location_id": "instagram_location_id"
}

Integration Account Requirements:

  • apiKey: Facebook Page Access Token
  • password: Instagram Business Account ID

WorkflowState Keys Emitted:

  • ig.publish.permalink: Direct link to published post
  • ig.publish.media_id: Instagram media ID
  • ig.publish.status: PUBLISHED|SCHEDULED|ERROR

X (Twitter) Posting (social.x.post)​

Post text and media to X with advanced features like replies and quotes.

Configuration Schema:

{
  "text": "Your tweet content (max 280 chars)",
  "media_urls": ["https://example.com/image.jpg"],
  "reply_to_tweet_id": "1234567890123456789",
  "quote_tweet_id": "1234567890123456789",
  "paid_tier": "free|basic|pro|enterprise"
}

Integration Account Requirements:

  • apiKey: X API Bearer Token or OAuth Consumer Key
  • password: OAuth Consumer Secret (if using OAuth 1.0a)

WorkflowState Keys Emitted:

  • x.post.tweet_id: Unique tweet identifier
  • x.post.permalink: Direct link to tweet
  • x.post.status: PUBLISHED|ERROR

LinkedIn Company Sharing (social.linkedin.company_share)​

Share content to LinkedIn company pages with professional formatting.

Configuration Schema:

{
  "organization_id": "urn:li:organization:1234567",
  "text": "Your LinkedIn post content (max 3000 chars)",
  "media_urls": ["https://example.com/image.jpg"],
  "link": "https://example.com/article",
  "visibility": "PUBLIC|CONNECTIONS"
}

Integration Account Requirements:

  • apiKey: LinkedIn Application Client ID
  • password: LinkedIn Application Client Secret

WorkflowState Keys Emitted:

  • li.share.urn: LinkedIn share URN
  • li.share.permalink: Direct link to share
  • li.share.status: PUBLISHED|ERROR

Facebook Page Posting (social.facebook.page_post)​

Publish content to Facebook business pages with scheduling support.

Configuration Schema:

{
  "message": "Your Facebook post content",
  "media_url": "https://example.com/media.mp4",
  "scheduled_publish_time": "2024-01-15T10:00:00Z",
  "published": true
}

Integration Account Requirements:

  • apiKey: Facebook Page Access Token
  • password: Facebook Page ID

WorkflowState Keys Emitted:

  • fb.post.id: Facebook post ID
  • fb.post.permalink: Direct link to post
  • fb.post.status: PUBLISHED|SCHEDULED|ERROR

TikTok Business Publishing (social.tiktok.publish)​

Upload and publish videos to TikTok for Business accounts.

Configuration Schema:

{
  "advertiser_id": "1234567890",
  "video_url": "https://example.com/video.mp4",
  "caption": "Your TikTok caption (max 2200 chars)",
  "cover_time": 2.5,
  "privacy_level": "PUBLIC|FRIENDS|PRIVATE"
}

Integration Account Requirements:

  • apiKey: TikTok Business API Access Token
  • password: TikTok Advertiser ID

WorkflowState Keys Emitted:

  • tt.video.id: TikTok video ID
  • tt.video.permalink: Direct link to video
  • tt.video.status: PUBLISHED|PROCESSING|ERROR

Security Features​

RBAC (Role-Based Access Control)​

All social media modules enforce strict RBAC:

  • USER: Can publish content with approval workflows
  • ADMIN: Can publish content without restrictions
  • ANONYMOUS: Blocked from all publishing operations

Data Protection​

  • PII Redaction: Personal information is automatically redacted from logs
  • Credential Security: API keys and tokens are never logged or stored in WorkflowState
  • Audit Trail: All publishing actions are logged with timestamps and user context

Idempotency​

Each module implements hash-based idempotency to prevent duplicate posts:

  • Hash computed from content + target + scheduling parameters
  • Duplicate executions return cached results without API calls
  • Prevents accidental multiple postings

Usage Examples​

Instagram Story Campaign​

// Configure Instagram module for product launch
ExecModule igModule = new ExecModule()
    .moduleType("social.instagram.publish")
    .moduleData("""
        {
          "media_type": "IMAGE",
          "source_url": "https://cdn.company.com/product-launch.jpg",
          "caption": "🚀 Exciting product launch! #innovation #tech",
          "schedule_time": "2024-01-15T10:00:00Z"
        }
        """);

Multi-Platform Publishing Workflow​

// Chain multiple social media posts
Workflow socialCampaign = new Workflow()
    .addModule(instagramModule)
    .addModule(twitterModule) 
    .addModule(linkedinModule)
    .addModule(facebookModule);

Error Handling​

All modules provide comprehensive error handling:

4xx Client Errors​

  • Invalid credentials → UNAUTHORIZED status
  • Rate limiting → RATE_LIMITED status with retry suggestions
  • Invalid content → VALIDATION_ERROR with specific field errors

5xx Server Errors​

  • Platform downtime → SERVICE_UNAVAILABLE with exponential backoff
  • Temporary failures → RETRY_LATER with suggested delay

Network Errors​

  • Connection timeouts → NETWORK_TIMEOUT with retry logic
  • DNS failures → NETWORK_ERROR with connectivity checks

Best Practices​

Content Guidelines​

  1. Character Limits: Respect platform-specific character limits
  2. Media Formats: Use platform-optimized media formats and sizes
  3. Hashtags: Follow platform hashtag best practices
  4. Accessibility: Include alt text for images when supported

Scheduling Optimization​

  1. Time Zones: Use UTC timestamps for consistent scheduling
  2. Platform Peak Times: Schedule based on audience analytics
  3. Buffer Time: Allow sufficient processing time for media uploads

Error Recovery​

  1. Retry Logic: Implement exponential backoff for transient failures
  2. Fallback Content: Prepare alternative content for validation failures
  3. Manual Review: Set up alerts for persistent failures requiring human intervention

Monitoring and Analytics​

EventLog Tracking​

Each module emits detailed EventLog entries for monitoring:

  • START: Module execution initiated
  • UPLOAD: Media upload progress
  • PROCESSING: Platform processing status
  • PUBLISHED: Successful publication
  • ERROR: Failure details with error codes

WorkflowState Analytics​

Access publishing metrics via WorkflowState:

String publishedPosts = workflow.getWorkflowState()
    .stream()
    .filter(state -> state.getKey().endsWith(".permalink"))
    .collect(Collectors.toList());

Integration with Analytics Tools​

  • Export EventLog data to analytics platforms
  • Track engagement metrics via platform APIs
  • Generate automated performance reports