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.

object

Show Request Body

ID of the social media account to post to

string

required

Social media platform (FACEBOOK, INSTAGRAM, TIKTOK, etc.)

string

required

Content text to post

string

ISO 8601 timestamp for scheduled posting

array

Array of tags for categorization

string

Keyword for tracking and attribution

string

UTM source parameter for tracking

string

UTM medium parameter for tracking

string

UTM campaign parameter for tracking

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.

object

Show Query Parameters

Filter by social account ID

string

Filter by platform (FACEBOOK, INSTAGRAM, TIKTOK, etc.)

string

Filter by tags (comma-separated)

string

Filter by exact keyword match

string

Search in content text

string

Filter posts from date (ISO 8601)

string

Filter posts to date (ISO 8601)

boolean

Include live metrics from social platforms

number

Page number for pagination (default: 1)

number

Number of items per page (default: 10, max: 100)

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.

Bio Link Management

Create Bio Link

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.

object

Show Request Body

string

required

Title of the bio link

string

Description of the bio link

string

required

Destination URL

string

Optional image URL for the link

string

Text for the call-to-action button

string

UTM source parameter

string

UTM medium parameter

string

UTM campaign parameter

boolean

Whether the bio link is active (default: true)

Get Bio Links

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.

Update Bio Link

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 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.

object

Show Query Parameters

string

Start date for analytics (ISO 8601)

string

End date for analytics (ISO 8601)

string

Filter by platform (FACEBOOK, INSTAGRAM, TIKTOK, etc.)

Filter by social account ID

string

Filter by tags (comma-separated)

string

Specific metrics to include (comma-separated)

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

Getting Started

Authentication

Core Services

Content & Social

AI & Automation

Analytics & Insights

Communication

Utilities

Services

Content Controller

Content Controller

Base Path

Overview

Authentication & Authorization

Content Management

Create Content Post

Get Content Posts

Update Content Post

Delete Content Post

Bio Link Management

Create Bio Link

Get Bio Links

Update Bio Link

Delete Bio Link

Content Analytics

Get Content Analytics

Get Content Performance

Content Status Values

Error Responses

Common Errors

Advanced Features

Live Data Synchronization

Content Attribution

Performance Optimization

Multi-Platform Support

​Content Controller

​Base Path

​Overview

​Authentication & Authorization

​Content Management

​Create Content Post

​Get Content Posts

​Update Content Post

​Delete Content Post

​Bio Link Management

​Create Bio Link

​Get Bio Links

​Update Bio Link

​Delete Bio Link

​Content Analytics

​Get Content Analytics

​Get Content Performance

​Content Status Values

​Error Responses

​Common Errors

​Advanced Features

​Live Data Synchronization

​Content Attribution

​Performance Optimization

​Multi-Platform Support

Content Controller

Base Path

Overview

Authentication & Authorization

Content Management

Create Content Post

Get Content Posts

Update Content Post

Delete Content Post

Bio Link Management

Create Bio Link

Get Bio Links

Update Bio Link

Delete Bio Link

Content Analytics

Get Content Analytics

Get Content Performance

Content Status Values

Error Responses

Common Errors

Advanced Features

Live Data Synchronization

Content Attribution

Performance Optimization

Multi-Platform Support