Integration and API Spec

Integration and API Spec

Social Media Scheduling

Used by all three agents. Agent 1 polls or receives webhook events when a record status changes to 'Ready for Review'. Agent 2 logs rejection feedback and resets record status. Agent 3 updates record status to 'Scheduled' and writes the confirmed Buffer post URL back to the record.

// Webhook payload (incoming)
{
  "webhook_id": "<string>",
  "timestamp": "<ISO8601>",
  "changedTablesById": {
    "<AIRTABLE_TABLE_ID>": {
      "changedRecordsById": {
        "<record_id>": {
          "current": { "cellValuesByFieldId": { "fldStatus": "Ready for Review" } }
        }
      }
    }
  }
}
// Write back (Agent 3 update)
PATCH /v0/{AIRTABLE_BASE_ID}/{AIRTABLE_TABLE_ID}/{record_id}
{ "fields": { "Status": "Scheduled", "Buffer Post URL": "<url>" } }

Used by Agent 1 only. Retrieves the caption document and image asset associated with a given Airtable content record. The Airtable record stores direct Google Drive file URLs; the integration resolves those URLs to readable content using the Drive API.

// Fetch file metadata
GET https://www.googleapis.com/drive/v3/files/{FILE_ID}
  ?fields=id,name,mimeType,webContentLink
  &supportsAllDrives=true
Authorization: Bearer {GDRIVE_ACCESS_TOKEN}

// Fetch caption text content (Google Doc exported as plain text)
GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/export
  ?mimeType=text/plain

// Output passed to Agent 2
{
  "caption_text": "<string>",
  "image_url": "<direct_download_url>",
  "file_name": "<string>",
  "mime_type": "image/jpeg | image/png"
}

Used by Agent 2 (approval request with interactive buttons and response capture) and Agent 3 (weekly schedule summary post). Requires a custom Slack App installed to the workspace with bot and interactive component permissions enabled.

// Approval request message payload (chat.postMessage)
POST https://slack.com/api/chat.postMessage
{
  "channel": "{SLACK_APPROVAL_CHANNEL_ID}",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn", "text": "*New post ready for approval*\n{caption_text}" } },
    { "type": "image", "image_url": "{image_url}", "alt_text": "Post asset" },
    { "type": "section", "fields": [
        { "type": "mrkdwn", "text": "*Channels:* {target_channels}" },
        { "type": "mrkdwn", "text": "*Scheduled:* {scheduled_time}" }
    ]},
    { "type": "actions", "elements": [
        { "type": "button", "text": { "type": "plain_text", "text": "Approve" }, "style": "primary", "action_id": "approve_post", "value": "{record_id}" },
        { "type": "button", "text": { "type": "plain_text", "text": "Reject" }, "style": "danger", "action_id": "reject_post", "value": "{record_id}" }
    ]}
  ]
}

// Incoming interactive payload (approve or reject)
{
  "type": "block_actions",
  "actions": [{ "action_id": "approve_post | reject_post", "value": "{record_id}" }],
  "user": { "id": "<slack_user_id>", "name": "<slack_username>" }
}

Used by Agent 3 only. Receives approved content packages and schedules posts to the configured social channels via the Buffer Publishing API. Each Airtable content record maps to one or more Buffer updates depending on the number of target channels.

// Schedule a post (POST /v1/updates/create.json)
POST https://api.bufferapp.com/1/updates/create.json
Authorization: Bearer {BUFFER_ACCESS_TOKEN}
{
  "profile_ids": ["{BUFFER_PROFILE_ID_1}", "{BUFFER_PROFILE_ID_2}"],
  "text": "{caption_text}",
  "media": {
    "photo": "{image_public_url}",
    "thumbnail": "{image_public_url}"
  },
  "scheduled_at": "{unix_timestamp_utc}",
  "now": false
}

// Successful response
{
  "success": true,
  "buffer_count": 1,
  "updates": [{ "id": "<buffer_update_id>", "status": "buffer", "due_at": <unix_ts> }]
}

// Credential store contents
// All values are injected at runtime via the platform credential manager.
// Never commit these values to version control or hardcode in workflow nodes.

AIRTABLE_PAT                  // Airtable Personal Access Token
AIRTABLE_WEBHOOK_SECRET       // HMAC secret for Airtable webhook signature validation
AIRTABLE_BASE_ID              // Base ID of the content calendar Airtable base
AIRTABLE_TABLE_ID             // Table ID of the 'Content Calendar' table

GDRIVE_SERVICE_ACCOUNT_JSON   // Full JSON key file for the Google Drive service account
GDRIVE_ROOT_FOLDER_ID         // Folder ID of the shared content asset folder in Google Drive

SLACK_BOT_TOKEN               // Bot User OAuth Token for all Slack API calls
SLACK_SIGNING_SECRET          // Secret for validating inbound Slack interactive payloads
SLACK_APPROVAL_CHANNEL_ID     // Channel ID where approval request messages are posted
SLACK_SUMMARY_CHANNEL_ID      // Channel ID where weekly schedule summary is posted
APPROVAL_TIMEOUT_HOURS        // Number of hours before an unanswered approval triggers a reminder (default: 24)

BUFFER_ACCESS_TOKEN           // Long-lived OAuth access token for Buffer Publishing API
BUFFER_PROFILE_MAP            // JSON object mapping channel names to Buffer profile IDs
                              // e.g. { "instagram": "abc123", "linkedin": "def456",
                              //        "twitter": "ghi789", "facebook": "jkl012" }