social

Invocation#

echo-cli social slots --account <account-id> --days <n> --time-zone <IANA zone> | analytics --by <format|platform|account|weekday|hook|topic> --days <n> [--platform <platform>] | link --post <post-id> --app <web source> --landing <https url> --source <v> --medium <v> --campaign <v> --by <who> | links --app <web source> | signups --app <web source> --signup-event <event> --days <n> | codes | code --post <post-id> --promo <promo-code-id> --by <who> | uncode --post <post-id>

Inputs and output#

slots writes account_id, days, time_zone and slots: per weekday and hour the account's posts went out in the time zone, key, weekday, hour, posts, post_ids, sums (views, likes, comments, shares, and unmeasured, the posts no scrape measured) and engagement, interactions per view or null when nothing was viewed; slots with an engagement come first, best first. analytics writes by, days and groups, each the same figures for one value of the dimension, ordered the same way. link writes the post's link (post_id, app_id, url, created_by, created_at); links writes { links } of the source. signups writes since, posts and accounts: per linked post, post_id, url, visitors (the people who arrived through its link in the window), signups and signup_subjects (those of them who sent --signup-event at or after arriving); per social account the content queue files the linked posts under, social_account_id, posts, and visitors and signups counted over all its posts, one person once — the linked posts the content queue does not hold are summed under social_account_id null. codes writes every post's code, newest assignment first: post_id, promo_code_id, code, redemptions (Stripe's times_redeemed for its promotion code, read now), active, assigned_by and assigned_at; code writes the assignment and uncode the one taken off.

State effect#

slots and analytics call Echo Web's authenticated /api/analytics/social-breakdowns, link, links and signups /api/analytics/social-links, codes, code and uncode /api/analytics/post-codes, with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the When and what to post, Signups from posts and Discount codes per post sections of the ecosystem analytics tab and of Echo Desktop's GEO screen call the same operations, and echo-mcp runs them as echo_social_slots, echo_social_dimensions, echo_social_post_link, echo_social_post_links, echo_social_post_signups, echo_social_post_codes, echo_social_post_code and echo_social_post_uncode. Breakdowns read the published posts of the last --days days and the metrics their scrapes recorded, as the post analytics do; a metric no scrape recorded adds nothing and is counted as unmeasured; the weekday dimension reads the UTC weekday, slots the --time-zone named; the hook dimension reads a post's declared hook (echo-cli content hooks set), else its caption's first line; the topic dimension reads the topic declared with echo-cli content topics set; a post without a value for the dimension is left out. A post's link is built from the source's declared UTM values with utm_content set to the post's id, which link declares in the source's vocabulary as the post; links are kept in social_post_links, one per post. signups reads the source's stored web events: a person is the identifiers joined wherever one event carries both a user id and an anonymous id, arriving through a post when an event of theirs carries its utm_content. A post's code is a promo code made with echo-cli promos create, kept in post_promo_codes: a post carries one and a code belongs to one post; its redemptions are asked of Stripe each time they are read, never stored.

Refusals#

• A wrong invocation is refused before anything is sent: "social takes <every verb's usage, separated by semicolons>; got <word>", "social <verb> does not take <flag>; it takes …", "<flag> needs a value" and "social <verb> needs <flag>".
• Echo Web answers a bad request with "account_id is required: the social account whose posting slots to read", "days must be a positive whole number: the window of published posts to read; got <value>", "time_zone is required: the IANA time zone the slots are read in, such as Europe/Warsaw", "time_zone must be an IANA time zone, such as Europe/Warsaw; got <value>", "by must be one of format, platform, account, weekday, hook, topic; got <value>", "<field> is required: …" for each link field, for app_id and signup_event, and for post_id and promo_code_id, "days must be a positive whole number: the window to read", "url must be an HTTPS address, not <url>" or "<app> does not declare <parameter>=<value>; add it with echo-cli tracking utm add first"; not found with "account <id> published no post in the last <n> days, so it has no slots to read", "no promo code has id <id>; echo-cli promos list shows them" or "post <id> carries no promo code"; and a conflict with "post <id> already has its link <url>", "post <id> already carries promo code <id>, assigned by <who> at <time>" or "the code <code> already belongs to post <id>". When Stripe cannot answer for a code, codes answers "Stripe could not answer for promotion code <id> (<code>): <reason>". The command prints Echo Web's sentence and exits 1.