Skip to main content

​
Content Controller

The Content Controller provides comprehensive content management capabilities including social media content creation, synchronization, analytics, and bio link management for the VChata platform.

​
Base Path

/content

​
Overview

This controller enables complete content lifecycle management:
  • 📝 Content Creation - Create and manage social media content posts
  • 🔄 Live Data Sync - Real-time synchronization with social media platforms
  • 📊 Content Analytics - Performance tracking and insights
  • 🔗 Bio Link Management - Create and manage bio links
  • 🎯 Attribution Tracking - Track content performance and lead generation
  • 📈 Performance Optimization - AI-powered content recommendations

​
Authentication & Authorization

  • 🔐 All endpoints require valid JWT authentication token
  • 🏢 All operations are scoped to the user’s current organization
  • 👥 Organization membership required for all operations

​
Content Management

​
Create Content Post

POST /content/org_abc123/posts
Authorization: Bearer <token>
Content-Type: application/json

{
  "socialAccountId": "social_123",
  "platform": "FACEBOOK",
  "content": "Check out our amazing new product! 🚀 #innovation #tech",
  "scheduledAt": "2024-01-20T10:00:00Z",
  "tags": ["product", "launch", "innovation"],
  "keyword": "new-product-2024",
  "utmSource": "social_media",
  "utmMedium": "post",
  "utmCampaign": "product_launch"
}

{
  "success": true,
  "contentPost": {
    "id": "post_123",
    "organizationId": "org_abc123",
    "socialAccountId": "social_123",
    "platform": "FACEBOOK",
    "content": "Check out our amazing new product! 🚀 #innovation #tech",
    "scheduledAt": "2024-01-20T10:00:00Z",
    "tags": ["product", "launch", "innovation"],
    "keyword": "new-product-2024",
    "utmSource": "social_media",
    "utmMedium": "post",
    "utmCampaign": "product_launch",
    "status": "SCHEDULED",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "message": "Content post created successfully"
}
Description: Creates a new content post for social media platforms with scheduling and tracking capabilities.
​
body
object

​
Get Content Posts

GET /content/org_abc123/posts?platform=FACEBOOK&includeLiveData=true&page=1&limit=10
Authorization: Bearer <token>

{
  "success": true,
  "contentPosts": [
    {
      "id": "post_123",
      "organizationId": "org_abc123",
      "socialAccountId": "social_123",
      "platform": "FACEBOOK",
      "content": "Check out our amazing new product! 🚀 #innovation #tech",
      "platformPostId": "123456789",
      "url": "https://facebook.com/posts/123456789",
      "scheduledAt": "2024-01-20T10:00:00Z",
      "publishedAt": "2024-01-20T10:00:00Z",
      "tags": ["product", "launch", "innovation"],
      "keyword": "new-product-2024",
      "status": "PUBLISHED",
      "liveMetrics": {
        "likes": 150,
        "comments": 25,
        "shares": 12,
        "clicks": 45,
        "reach": 1250,
        "impressions": 2100
      },
      "socialAccount": {
        "id": "social_123",
        "platform": "FACEBOOK",
        "name": "Acme Corp Facebook"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T10:05:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "hasMore": false
  },
  "message": "Content posts retrieved successfully"
}
Description: Retrieves content posts with optional filtering and live data synchronization.
​
query
object

​
Update Content Post

PATCH /content/org_abc123/posts/post_123
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Updated content with new information! 🚀 #innovation #tech #updated",
  "tags": ["product", "launch", "innovation", "updated"],
  "scheduledAt": "2024-01-21T10:00:00Z"
}

{
  "success": true,
  "contentPost": {
    "id": "post_123",
    "content": "Updated content with new information! 🚀 #innovation #tech #updated",
    "tags": ["product", "launch", "innovation", "updated"],
    "scheduledAt": "2024-01-21T10:00:00Z",
    "updatedAt": "2024-01-15T15:30:00Z"
  },
  "message": "Content post updated successfully"
}
Description: Updates an existing content post with new information.

​
Delete Content Post

DELETE /content/org_abc123/posts/post_123
Authorization: Bearer <token>

{
  "success": true,
  "message": "Content post deleted successfully"
}
Description: Permanently deletes a content post from the system. 
POST /bio/org_abc123/links
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Summer Sale 2024",
  "description": "Check out our amazing summer deals!",
  "url": "https://acme.com/summer-sale",
  "imageUrl": "https://acme.com/images/summer-banner.jpg",
  "buttonText": "Shop Now",
  "utmSource": "bio_link",
  "utmMedium": "social",
  "utmCampaign": "summer_2024",
  "isActive": true
}

{
  "success": true,
  "bioLink": {
    "id": "bio_link_123",
    "organizationId": "org_abc123",
    "title": "Summer Sale 2024",
    "description": "Check out our amazing summer deals!",
    "url": "https://acme.com/summer-sale",
    "shortUrl": "https://vchata.link/summer2024",
    "imageUrl": "https://acme.com/images/summer-banner.jpg",
    "buttonText": "Shop Now",
    "utmSource": "bio_link",
    "utmMedium": "social",
    "utmCampaign": "summer_2024",
    "isActive": true,
    "clickCount": 0,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "message": "Bio link created successfully"
}
Description: Creates a new bio link for social media profiles.
​
body
object
GET /bio/org_abc123/links?isActive=true&page=1&limit=10
Authorization: Bearer <token>

{
  "success": true,
  "bioLinks": [
    {
      "id": "bio_link_123",
      "title": "Summer Sale 2024",
      "description": "Check out our amazing summer deals!",
      "url": "https://acme.com/summer-sale",
      "shortUrl": "https://vchata.link/summer2024",
      "imageUrl": "https://acme.com/images/summer-banner.jpg",
      "buttonText": "Shop Now",
      "isActive": true,
      "clickCount": 45,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T15:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "hasMore": false
  },
  "message": "Bio links retrieved successfully"
}
Description: Retrieves bio links with optional filtering. 
PATCH /bio/org_abc123/links/bio_link_123
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Summer Sale 2024",
  "description": "New and improved summer deals!",
  "url": "https://acme.com/summer-sale-v2",
  "buttonText": "Shop Now - Updated"
}

{
  "success": true,
  "bioLink": {
    "id": "bio_link_123",
    "title": "Updated Summer Sale 2024",
    "description": "New and improved summer deals!",
    "url": "https://acme.com/summer-sale-v2",
    "buttonText": "Shop Now - Updated",
    "updatedAt": "2024-01-20T16:00:00Z"
  },
  "message": "Bio link updated successfully"
}
Description: Updates an existing bio link. 
DELETE /bio/org_abc123/links/bio_link_123
Authorization: Bearer <token>

{
  "success": true,
  "message": "Bio link deleted successfully"
}
Description: Permanently deletes a bio link.

​
Content Analytics

​
Get Content Analytics

GET /content/org_abc123/analytics?dateFrom=2024-01-01&dateTo=2024-01-31&platform=FACEBOOK
Authorization: Bearer <token>

{
  "success": true,
  "analytics": {
    "overview": {
      "totalPosts": 25,
      "totalEngagement": 1250,
      "totalReach": 15000,
      "totalClicks": 450,
      "averageEngagementRate": 8.3,
      "averageClickThroughRate": 3.0
    },
    "platforms": [
      {
        "platform": "FACEBOOK",
        "posts": 15,
        "engagement": 850,
        "reach": 10000,
        "clicks": 300
      },
      {
        "platform": "INSTAGRAM",
        "posts": 10,
        "engagement": 400,
        "reach": 5000,
        "clicks": 150
      }
    ],
    "topPerformingPosts": [
      {
        "id": "post_123",
        "content": "Check out our amazing new product! 🚀",
        "engagement": 150,
        "reach": 1250,
        "clicks": 45
      }
    ],
    "engagementTrends": [
      {
        "date": "2024-01-01",
        "engagement": 50,
        "reach": 600
      },
      {
        "date": "2024-01-02",
        "engagement": 75,
        "reach": 800
      }
    ]
  },
  "message": "Content analytics retrieved successfully"
}
Description: Retrieves comprehensive content performance analytics.
​
query
object

​
Get Content Performance

GET /content/org_abc123/posts/post_123/performance
Authorization: Bearer <token>

{
  "success": true,
  "performance": {
    "postId": "post_123",
    "content": "Check out our amazing new product! 🚀",
    "metrics": {
      "likes": 150,
      "comments": 25,
      "shares": 12,
      "clicks": 45,
      "reach": 1250,
      "impressions": 2100,
      "engagementRate": 12.0,
      "clickThroughRate": 3.6
    },
    "demographics": {
      "ageGroups": {
        "18-24": 25,
        "25-34": 45,
        "35-44": 20,
        "45-54": 10
      },
      "genders": {
        "male": 60,
        "female": 40
      }
    },
    "timing": {
      "bestPerformingHour": 14,
      "bestPerformingDay": "Tuesday",
      "averageEngagementTime": 25
    },
    "attribution": {
      "leadsGenerated": 5,
      "conversions": 2,
      "revenue": 250.00
    }
  },
  "message": "Content performance retrieved successfully"
}
Description: Retrieves detailed performance metrics for a specific content post.

​
Content Status Values

  • DRAFT - Content is being created/edited
  • SCHEDULED - Content is scheduled for future posting
  • PUBLISHED - Content has been posted to social media
  • FAILED - Content posting failed
  • DELETED - Content has been deleted from social media

​
Error Responses

​
Common Errors

{
  "success": false,
  "statusCode": 400,
  "message": [
    "content is required",
    "socialAccountId must be a valid UUID",
    "platform must be one of: FACEBOOK, INSTAGRAM, TIKTOK"
  ],
  "error": "Bad Request"
}

{
  "success": false,
  "statusCode": 404,
  "message": "Content post not found or you don't have access",
  "error": "Not Found"
}

{
  "success": false,
  "statusCode": 409,
  "message": "Content already exists with this keyword",
  "error": "Conflict"
}

{
  "success": false,
  "statusCode": 502,
  "message": "Social media platform temporarily unavailable",
  "error": "Bad Gateway"
}

​
Advanced Features

​
Live Data Synchronization

The content controller includes advanced live data synchronization capabilities:
  • Real-time Metrics - Fetch live engagement metrics from social platforms
  • Auto-Sync - Automatically sync new posts from social media platforms
  • Conflict Resolution - Handle conflicts between local and platform data
  • Batch Processing - Efficient batch synchronization for large datasets

​
Content Attribution

Track how content generates leads and conversions:
  • UTM Tracking - Complete UTM parameter support for attribution
  • Lead Generation - Link content interactions to lead creation
  • Conversion Tracking - Track revenue and conversions from content
  • ROI Analysis - Calculate return on investment for content campaigns

​
Performance Optimization

  • Caching - Intelligent caching for frequently accessed content
  • Rate Limiting - Respect platform API rate limits
  • Batch Operations - Efficient batch processing for bulk operations
  • Error Recovery - Automatic retry mechanisms for failed operations

​
Multi-Platform Support

  • Cross-Platform Content - Create content for multiple platforms simultaneously
  • Platform-Specific Features - Leverage platform-specific capabilities
  • Unified Analytics - Consolidated analytics across all platforms
  • Consistent Tracking - Unified tracking and attribution across platforms