Developer Handover Pack

Developer Handover Pack

Social & Digital Promotion Automation

Receives an approved post from the content calendar and adapts it into channel-ready versions. Adjusts copy length, hashtag sets, image crop ratios, and platform-specific metadata for each target channel. Outputs one formatted variant per channel, ready for the Scheduling Agent to consume.

// Input
{
  "post_id": "string",
  "approved_copy": "string",
  "asset_url": "string (source image)",
  "channels": ["facebook", "instagram", "linkedin", "twitter"],
  "campaign_id": "string"
}

// Output
{
  "post_id": "string",
  "channel_variants": [
    {
      "channel": "instagram",
      "copy": "string (trimmed to 2200 chars)",
      "hashtags": ["#campaign", "#brand"],
      "asset_url": "string (resized 1080x1080)",
      "canva_export_id": "string"
    },
    { "channel": "linkedin", "..." },
    { "channel": "facebook", "..." },
    { "channel": "twitter", "..." }
  ],
  "status": "formatted | error",
  "error_detail": "string | null"
}

Receives channel-ready post variants from the Channel Formatting Agent and schedules each to its optimal publish time via Buffer. Monitors confirmation of successful publishing. If a publish fails, routes the post to a manual fix-and-reschedule step via Slack notification and awaits resubmission before continuing.

// Input
{
  "post_id": "string",
  "channel_variants": [ { "channel": "string", "copy": "string", "asset_url": "string" } ],
  "preferred_send_window": "string (e.g. 09:00-12:00 local)"
}

// Output (success)
{
  "post_id": "string",
  "scheduled_posts": [
    { "channel": "instagram", "buffer_post_id": "string", "scheduled_at": "ISO8601", "status": "scheduled" },
    { "channel": "linkedin", "buffer_post_id": "string", "scheduled_at": "ISO8601", "status": "published" }
  ],
  "overall_status": "all_published | partial_failure | all_failed"
}

// Output (failure branch)
{
  "post_id": "string",
  "failed_channels": ["twitter"],
  "slack_alert_sent": true,
  "status": "needs_review"
}

Runs on a weekly schedule when the reporting window closes. Pulls performance metrics from Google Analytics for all posts published in the window. Compiles metrics into a structured weekly performance report and distributes it to the team via Slack. Eliminates the Monday-morning manual copy-paste task entirely.

// Input (cron trigger, no external payload)
{
  "reporting_window_start": "ISO8601 (e.g. Monday 00:00)",
  "reporting_window_end": "ISO8601 (e.g. Sunday 23:59)",
  "ga4_property_id": "string",
  "channels_to_report": ["facebook", "instagram", "linkedin", "twitter"]
}

// Output
{
  "report_id": "string",
  "period": { "start": "ISO8601", "end": "ISO8601" },
  "summary": {
    "total_impressions": 18400,
    "total_engagements": 1220,
    "top_post_id": "string",
    "engagement_rate": 0.066
  },
  "channel_breakdown": [
    { "channel": "instagram", "impressions": 7200, "clicks": 540, "engagement_rate": 0.075 },
    { "channel": "linkedin", "impressions": 5100, "clicks": 380, "engagement_rate": 0.074 }
  ],
  "slack_message_ts": "string",
  "data_complete": true
}

// ─────────────────────────────────────────────────────────────────────
// TRIGGER
// ─────────────────────────────────────────────────────────────────────
Content calendar webhook fires  →  post_id, approved_copy, asset_url, channels[]

// ─────────────────────────────────────────────────────────────────────
// AGENT 1: Channel Formatting Agent
// ─────────────────────────────────────────────────────────────────────
IN  : { post_id, approved_copy, asset_url, channels[] }
      │
      ├─ Canva API  →  resize asset per channel spec (1080x1080, 1200x628, etc.)
      ├─ Canva API  →  apply channel template, embed copy with char limit enforced
      └─ Build channel_variants[]  →  { channel, copy, hashtags, asset_url, canva_export_id }

OUT : { post_id, channel_variants[], status: 'formatted' }

      ⚠ ERROR PATH: Canva API error  →  Slack alert to coordinator  →  post paused
                     remaining posts continue unblocked

// ─────────────────────────────────────────────────────────────────────
// AGENT 2: Scheduling Agent
// ─────────────────────────────────────────────────────────────────────
IN  : { post_id, channel_variants[], preferred_send_window }
      │
      ├─ Buffer API  →  POST /v1/profiles/{profile_id}/updates/create per channel
      ├─ Buffer API  →  apply suggested optimal time per profile
      └─ Buffer API  →  poll /v1/updates/{update_id} at T+10 min for status

      DECISION GATE: Publish OK?
      ├─ YES  →  status: 'published'  →  pass post_id to metrics collection queue
      └─ NO   →  Slack alert: { post_id, channel, error_code }
                  coordinator fixes and resubmits  →  re-enters Scheduling Agent

OUT : { post_id, scheduled_posts[], overall_status: 'all_published | partial_failure' }

// ─────────────────────────────────────────────────────────────────────
// METRICS COLLECTION (tool step, no agent)
// ─────────────────────────────────────────────────────────────────────
Google Analytics Data API v1
  →  POST /v1beta/properties/{property_id}:runReport
  →  dimensions: [ sessionSource, campaignName, date ]
  →  metrics:    [ sessions, engagedSessions, screenPageViews, eventCount ]
  →  dateRange:  { reporting_window_start, reporting_window_end }
  →  store raw rows in automation datastore keyed by post_id + channel

// ─────────────────────────────────────────────────────────────────────
// AGENT 3: Reporting Agent  (cron: every Monday 07:00)
// ─────────────────────────────────────────────────────────────────────
IN  : { reporting_window_start, reporting_window_end, ga4_property_id, channels[] }
      │
      ├─ Aggregate channel_breakdown[] from datastore rows
      ├─ Compute summary: total_impressions, total_engagements, top_post_id, engagement_rate
      ├─ Compile report object  →  { report_id, period, summary, channel_breakdown }
      └─ Slack API  →  POST /api/chat.postMessage  →  #marketing channel

      ⚠ ERROR PATH: GA4 rate limit (429)  →  exponential backoff, max 3 retries
                     partial data  →  report sent with data_complete: false + note

OUT : { report_id, slack_message_ts, data_complete: true }

// ─────────────────────────────────────────────────────────────────────
// FINAL OUTPUT
// ─────────────────────────────────────────────────────────────────────
Posts live on all channels  +  weekly performance report in Slack
Manual intervention required only on publish failure or partial GA4 data