Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vchata.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Content Services

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

​
Overview

The Content Services layer includes:
  • 📝 Content Service - Core content creation and management
  • 🔄 Content Sync Service - Social media synchronization and live data fetching
  • 🔗 Bio Link Service - Bio link creation and management
  • 📊 Content Analytics - Performance tracking and insights
  • 🎯 Content Attribution - Track content performance and lead generation

​
Content Service

​
Core Content Management

The Content Service handles all content-related operations including creation, updates, and retrieval.

​
Create Content Post

// Create a new content post
const contentPost = await contentService.createContentPost(
  organizationId,
  {
    socialAccountId: "social_123",
    platform: "FACEBOOK",
    content: "Check out our new product!",
    scheduledAt: "2024-01-20T10:00:00Z",
    tags: ["product", "launch"],
    keyword: "new-product-2024",
    utmSource: "social_media",
    utmMedium: "post",
    utmCampaign: "product_launch"
  }
);

​
Get Content Posts

// Get content posts with filtering
const posts = await contentService.getContentPosts(
  organizationId,
  {
    socialAccountId: "social_123",
    platform: "FACEBOOK",
    tags: ["product"],
    dateFrom: "2024-01-01",
    dateTo: "2024-01-31",
    includeLiveData: true
  }
);

​
Update Content Post

// Update content post
const updatedPost = await contentService.updateContentPost(
  postId,
  {
    content: "Updated content with new information",
    tags: ["product", "updated"],
    scheduledAt: "2024-01-21T10:00:00Z"
  }
);

​
Content Operations

​
Content Sync Service

​
Social Media Synchronization

The Content Sync Service handles synchronization with social media platforms and live data fetching.

​
Sync Content

// Sync content from social media platform
const syncResult = await contentSyncService.syncContent(
  organizationId,
  {
    socialAccountId: "social_123",
    platform: "FACEBOOK",
    syncType: "posts",
    dateRange: {
      start: "2024-01-01",
      end: "2024-01-31"
    }
  }
);

​
Fetch Live Data

// Fetch live data for existing posts
const liveData = await contentSyncService.fetchLiveData(
  organizationId,
  {
    postIds: ["post_123", "post_456"],
    includeMetrics: true,
    includeComments: true,
    includeReactions: true
  }
);

​
Auto-Sync New Posts

// Automatically sync new posts from platform
const newPosts = await contentSyncService.autoSyncNewPosts(
  organizationId,
  {
    socialAccountId: "social_123",
    platform: "FACEBOOK",
    batchSize: 20,
    createTrackingRecords: true
  }
);

​
Sync Operations

The Bio Link Service handles creation and management of bio links for social media profiles. 
// Create a new bio link
const bioLink = await bioLinkService.createBioLink(
  organizationId,
  {
    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
  }
);

// Get bio links for organization
const bioLinks = await bioLinkService.getBioLinks(
  organizationId,
  {
    isActive: true,
    sortBy: "createdAt",
    sortOrder: "desc"
  }
);

// Update bio link
const updatedBioLink = await bioLinkService.updateBioLink(
  bioLinkId,
  {
    title: "Updated Summer Sale 2024",
    description: "New and improved summer deals!",
    url: "https://acme.com/summer-sale-v2"
  }
);

​
Content Analytics

​
Performance Tracking

Content analytics provide insights into content performance and engagement.

​
Get Content Performance

// Get content performance metrics
const performance = await contentService.getContentPerformance(
  organizationId,
  {
    dateRange: {
      start: "2024-01-01",
      end: "2024-01-31"
    },
    platforms: ["FACEBOOK", "INSTAGRAM"],
    metrics: ["reach", "engagement", "clicks", "conversions"]
  }
);

​
Get Top Performing Content

// Get top performing content
const topContent = await contentService.getTopPerformingContent(
  organizationId,
  {
    metric: "engagement_rate",
    limit: 10,
    dateRange: {
      start: "2024-01-01",
      end: "2024-01-31"
    }
  }
);

​
Get Content Insights

// Get detailed content insights
const insights = await contentService.getContentInsights(
  organizationId,
  {
    postId: "post_123",
    includeAudience: true,
    includeTiming: true,
    includeKeywords: true
  }
);

​
Analytics Operations

​
Content Attribution

​
Lead Generation Tracking

Content attribution tracks how content generates leads and conversions.

​
Track Content Interaction

// Track content interaction for attribution
await contentService.trackContentInteraction(
  organizationId,
  {
    contentPostId: "post_123",
    interactionType: "click",
    userId: "user_456",
    utmData: {
      source: "social_media",
      medium: "post",
      campaign: "summer_sale"
    }
  }
);

​
Get Content Attribution

// Get content attribution data
const attribution = await contentService.getContentAttribution(
  organizationId,
  {
    contentPostId: "post_123",
    dateRange: {
      start: "2024-01-01",
      end: "2024-01-31"
    },
    includeConversions: true
  }
);

​
Link Content to Lead

// Link content to lead for attribution
await contentService.linkContentToLead(
  organizationId,
  {
    contentPostId: "post_123",
    leadId: "lead_456",
    attributionType: "first_touch",
    attributionWeight: 1.0
  }
);

​
Attribution Operations

​
Integration Examples

​
Complete Content Creation Flow

// Complete content creation and publishing workflow
async function createAndPublishContent(
  organizationId: string,
  contentData: any
) {
  try {
    // 1. Create content post
    const contentPost = await contentService.createContentPost(
      organizationId,
      contentData
    );

    // 2. Sync with social media platform
    const syncResult = await contentSyncService.syncContent(
      organizationId,
      {
        socialAccountId: contentData.socialAccountId,
        platform: contentData.platform,
        syncType: "posts",
        createTrackingRecords: true
      }
    );

    // 3. Track for attribution
    await contentService.trackContentInteraction(
      organizationId,
      {
        contentPostId: contentPost.id,
        interactionType: "created",
        userId: contentData.userId
      }
    );

    // 4. Set up analytics tracking
    await contentService.setupAnalyticsTracking(
      contentPost.id,
      {
        trackClicks: true,
        trackEngagement: true,
        trackConversions: true
      }
    );

    return {
      contentPost,
      syncResult,
      success: true
    };
  } catch (error) {
    // Handle content creation errors
    throw error;
  }
}

​
Live Data Synchronization Flow

// Live data synchronization workflow
async function syncLiveData(organizationId: string, options: any) {
  try {
    // 1. Get existing posts
    const existingPosts = await contentService.getContentPosts(
      organizationId,
      {
        socialAccountId: options.socialAccountId,
        platform: options.platform,
        includeLiveData: false
      }
    );

    // 2. Fetch live data from platform
    const liveData = await contentSyncService.fetchLiveData(
      organizationId,
      {
        postIds: existingPosts.map(p => p.id),
        includeMetrics: true,
        includeComments: true,
        includeReactions: true
      }
    );

    // 3. Merge live data with existing posts
    const mergedPosts = await contentSyncService.mergeLiveData(
      existingPosts,
      liveData
    );

    // 4. Update posts with live data
    for (const post of mergedPosts) {
      await contentService.updateContentPost(post.id, {
        liveMetrics: post.liveMetrics,
        lastSyncedAt: new Date().toISOString()
      });
    }

    // 5. Check for new posts and sync them
    const newPosts = await contentSyncService.autoSyncNewPosts(
      organizationId,
      {
        socialAccountId: options.socialAccountId,
        platform: options.platform,
        batchSize: 20,
        createTrackingRecords: true
      }
    );

    return {
      updatedPosts: mergedPosts,
      newPosts,
      success: true
    };
  } catch (error) {
    // Handle sync errors
    throw error;
  }
}

​
Content Performance Analysis Flow

// Content performance analysis workflow
async function analyzeContentPerformance(
  organizationId: string,
  analysisOptions: any
) {
  try {
    // 1. Get performance metrics
    const performance = await contentService.getContentPerformance(
      organizationId,
      analysisOptions
    );

    // 2. Get top performing content
    const topContent = await contentService.getTopPerformingContent(
      organizationId,
      {
        metric: "engagement_rate",
        limit: 10,
        dateRange: analysisOptions.dateRange
      }
    );

    // 3. Get content insights
    const insights = await Promise.all(
      topContent.map(post =>
        contentService.getContentInsights(organizationId, {
          postId: post.id,
          includeAudience: true,
          includeTiming: true,
          includeKeywords: true
        })
      )
    );

    // 4. Get attribution data
    const attribution = await contentService.getAttributionReport(
      organizationId,
      {
        dateRange: analysisOptions.dateRange,
        includeConversions: true,
        includeRevenue: true
      }
    );

    // 5. Generate recommendations
    const recommendations = await contentService.generateRecommendations(
      organizationId,
      {
        performance,
        topContent,
        insights,
        attribution
      }
    );

    return {
      performance,
      topContent,
      insights,
      attribution,
      recommendations,
      success: true
    };
  } catch (error) {
    // Handle analysis errors
    throw error;
  }
}

​
Error Handling

​
Common Error Scenarios

​
Performance Optimization

​
Caching Strategy

// Implement caching for content data
const cachedContent = await contentCache.get(`content:${organizationId}:${postId}`);
if (!cachedContent) {
  const content = await contentService.getContentPost(postId);
  await contentCache.set(`content:${organizationId}:${postId}`, content, 3600); // 1 hour
}

​
Batch Operations

// Batch content operations for better performance
const batchResults = await Promise.allSettled(
  contentPosts.map(post =>
    contentService.updateContentPost(post.id, updateData)
  )
);

​
Rate Limiting

// Implement rate limiting for platform APIs
const rateLimiter = new RateLimiter({
  windowMs: 60000, // 1 minute
  max: 60 // 60 requests per minute
});

const syncWithRateLimit = rateLimiter.wrap(contentSyncService.syncContent);

​
Monitoring and Analytics

​
Content Metrics

// Track content metrics
const contentMetrics = {
  totalPosts: await contentService.getTotalPosts(organizationId),
  averageEngagement: await contentService.getAverageEngagement(organizationId),
  topPlatform: await contentService.getTopPlatform(organizationId),
  contentVelocity: await contentService.getContentVelocity(organizationId)
};

await analyticsService.track('content_metrics_updated', contentMetrics);

​
Sync Metrics

// Track sync performance
const syncMetrics = {
  syncSuccessRate: await contentSyncService.getSyncSuccessRate(organizationId),
  averageSyncTime: await contentSyncService.getAverageSyncTime(organizationId),
  failedSyncs: await contentSyncService.getFailedSyncs(organizationId),
  newPostsDiscovered: await contentSyncService.getNewPostsCount(organizationId)
};

await analyticsService.track('sync_metrics_updated', syncMetrics);