poppify-schedule-optimizer

Scheduling for engagement & reach — the optimizer flow

Poppify tracks engagement per {day-of-week, hour} bucket from the account's REAL published posts (the same data behind the mobile calendar heatmap). publish_post exposes it — your job is to use it instead of scheduling blind.

Where the data comes from (so you can explain it honestly)

• aggregates/time_slots per user: avg engagement rate, reach, likes/comments/saves/shares, post count, bestPostType, and a performance tier per day×hour bucket — recomputed from published-post metrics at every sync.
• Ranking is confidence-weighted (ER × log2(samples+1) × reach factor), so one lucky post doesn't crown a slot. Two posts at 142% ER can still rank above ten posts at 2% — but say the sample size out loud when it's thin (postCount ≤ 3).
• All hours are UTC. Convert to the user's timezone when presenting, and say which timezone you're showing.

The flow

1. After get_result returns complete, call publish_post({apiKey, postId}) with no channelIds. The response carries BOTH availableChannels and recommendedSlots.
2. Check recommendedSlots.basis:
   • "engagement_history" → these are the account's own numbers. Present the top 2–3 like: "Your audience engages best Fridays around 19:00 UTC (avg ER 4.2% across 11 posts). Next window: Fri Jul 10."
   • "platform_norms" → no history yet. Say so: "No engagement history on this account yet, so these are general platform norms (Tue–Thu midday). They'll become YOUR numbers as posts accrue metrics." Don't oversell norms as personalized.
3. Let the user pick channels (never auto-select) and a time:
   • User says "best time" → scheduledAt: "best" (auto-picks the top upcoming slot; response's pickedFrom tells you which basis it used), or pass a specific slot's nextOccurrence verbatim.
   • User picks their own time → schedule it, then read slotAssessment in the response. If the verdict says historically weak, surface it with the better alternative — advisory, one sentence, never re-schedule without being asked.
4. "Post now" (omit scheduledAt) is always legitimate for time-sensitive content. For evergreen content, gently note when a top slot is < ~48h away: waiting usually beats posting into a dead zone.