content interactive

Invocation#

echo-cli content interactive list --app <web source>
echo-cli content interactive add --app <web source> --slug <slug> --title <text> --questions <questions.json> [--results <results.json>] --event <completion event> --list <crm-list-id> --by <name>
echo-cli content interactive remove --piece <piece-id>
echo-cli content interactive completions --piece <piece-id>

Inputs and output#

list writes the source's pieces by slug: id, app_id, slug, title, questions (key, prompt and options, or key, prompt, kind number and unit), results (a calculator's declared results: key, label, unit, constant and terms; empty for a quiz), completion_event, list_id, created_by, created_at and page_url, Echo Web's page that renders the piece; add and remove write the piece. completions writes the piece's completions, newest first: id, piece_id, subject, answers (an option, or the number typed), results (each declared result computed from the answers, by key), contact_id (the CRM contact when an email was left, else null), event_id and completed_at.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/interactive with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Interactive content section of the tracking screen and of Echo Desktop's GEO screen call the same operation and open each piece's page, and echo-mcp reads pieces (with page_url) and completions as echo_interactive_content. --questions holds a JSON list of questions, each with its own key: a choice is { key, prompt, options } with at least two options, a number question { key, prompt, kind: "number", unit } (unit null for a bare number). --results, for a calculator, holds a JSON list of { key, label, unit, constant, terms }, each term { factor, keys } naming number questions: a result is its constant plus, for every term, the factor times the product of the numbers typed for its keys — { "constant": 0, "terms": [{ "factor": 52, "keys": ["hours", "rate"] }] } is a year of hours × rate — so a savings, cost or ROI calculator is declared without code. A page on a declared origin reads GET /api/public/interactive/<slug> for the title, the questions and results, the calculator's declared results as { key, label, unit } without their formulas (none for a quiz), and posts { subject, answers, email? } to the same address, a number question answered with a JSON number: every question answered is stored as a completion in interactive_completions with each result computed from the answers, the completion event is stored for the subject in the source's web events as a backend event (as tracking events report stores one) with the answers and results as its properties, and an email becomes a CRM contact — reused when the address is known — added once to the piece's list; the completion the endpoint answers carries the results by key, which the page shows beside the labels it read. A product that does not draw the piece itself links to Echo's page for it, /interactive/<slug> on Echo Web (page_url), which renders choices as options and number questions as a number field in their unit, with the optional email, completes the piece the same way and then shows each result by its label and unit; the link may carry ?subject=<the anonymous or user id its analytics send> so the completion joins that visitor, and without one the page uses an id the visitor's browser keeps for Echo's pages. The page shows a refusal as Echo Web's sentence and a stored completion with its time; a slug no piece is published at is not found.

Refusals#

• A wrong invocation is refused before anything is sent: "content takes evergreen, interactive; got <word>", "content interactive takes <every verb's usage>; got <word>", "content interactive <verb> needs <flag>", "--questions <path> is not a readable JSON file: <cause>" and "--results <path> is not a readable JSON file: <cause>".
• Echo Web answers a bad request with "app_id is required: …", "slug is required: …", "title is required: …", "questions is required: a list of { key, prompt, options } or { key, prompt, kind: \"number\", unit }", "questions[<n>].options must list at least two choices", "questions[<n>].kind must be number, or absent for a choice; got <value>", "questions name <key> twice; each question's key is its own", "results must be a list of { key, label, unit, constant, terms }", "results[<n>].terms must list at least one { factor, keys }", "results[<n>].constant must be a finite number: …" (and each term's factor), "results[<n>].terms[<m>] names <key>, which is not a number question of the piece", "results name <key> twice; each result's key is its own", "result <key> uses a question's key; …", "completion_event is required: …" or "list_id is required: …"; not found with "no CRM list has id <id>" or "no interactive piece has id <id>; …"; and a conflict with "<slug> is already piece <id> of <source>". The public endpoint answers "no interactive piece is published at <slug>" with 404, and "subject is required: …", "answers is required: …", "question <key> needs one of <options>; got <value>", "question <key> needs a number; got <value>" or "email must be one email address; got <value>" with 400. The command prints Echo Web's sentence and exits 1.