reviews

Invocation#

echo-cli reviews programs list --product <id>
echo-cli reviews programs add --product <id> --name <text> --app <web or mobile source> --success <event name> --venue <text> --url <https-url> --interval-days <n> --sequence <sequence id> [--satisfied-survey <name> --satisfied-answer <answer>...] --by <name>
echo-cli reviews programs remove --id <program-id>
echo-cli reviews request --product <id> --days <n>
echo-cli reviews requests --program <program-id>
echo-cli reviews export --program <program-id>
echo-cli reviews reviewed --id <request-id> --url <https-url>

Inputs and output#

programs list writes the product's programmes by name: id, product_id, name, app_id, success_event_name, venue, review_url, interval_days, sequence_id, satisfied_survey and satisfied_answers (both null without a gate), created_by and created_at; programs add and programs remove write the programme they made or removed. request writes since (the start of the window read) and runs, one per programme with program_id, name, requested (the requests it made) and not_satisfied (the successes it did not ask because their person gave no satisfied answer; 0 without a gate). requests writes a programme's requests newest first: id, program_id, subject, email (or null), success_event, requested_at, clicked_at, reviewed_at and posted_url (each null until it happens). export writes the same requests as email-sequencing-cli enrollments: id, sequenceId, contact { id, email, variables { review_link, venue } }, enrolledAt, status and events. reviewed writes the request with its posted review.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/reviews, /run or /requests with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Review requests section of the tracking screen and of Echo Desktop's GEO screen calls the same operations, and echo-mcp lists programmes (echo_list_review_programs) and reads requests (echo_review_requests) but asks no one. request reads the source's stored events of the window — a web source's web events or a mobile app's mobile events — and joins every identifier the identity edges and the events link into one person. A programme declared with --satisfied-survey and at least one --satisfied-answer (repeat the flag per answer; each must be a choice some version of that survey of the product offers, unless a version takes free answers) asks only a person one of whose identifiers answered any version of that survey with one of those answers; every other success is counted in not_satisfied and not asked. Each success event asks its person once, named by its user id, else its anonymous id, with that user's email when Echo's sign-in knows it, unless the same person was asked less than --interval-days before it, in this run or an earlier one; a success event is never asked twice. Echo Web also asks daily at /api/cron/review-requests over the last ECHO_REVIEW_WINDOW_DAYS days, which the deployment declares. The ask itself is the email-sequencing-cli sequence the programme names: export into a file and run email-sequencing plan --sequence <sequence.json> --enrollments <file>, with {{review_link}} and {{venue}} in its templates. The review link is Echo Web's /api/public/reviews/<request id>/click on NEXT_PUBLIC_SITE_URL; opening it records the first click and redirects to the programme's review page.

Refusals#

• A wrong invocation is refused before anything is sent: "reviews takes <every usage, separated by semicolons>; got <words>", "reviews <verb> does not take <flag>; it takes …", "<flag> needs a value" and "reviews <verb> needs <flag>" for each flag the verb needs.
• Echo Web answers a bad request with "product_id is required: …", "name is required: …", "app_id is required: …", "success_event_name is required: …", "venue is required: …", "review_url is required: …", "review_url must be an https address: the venue's review page; got <url>", "interval_days must be a positive whole number of days: …", "sequence_id is required: …", "satisfied_survey is required with satisfied_answers: …", "satisfied_answers is required with satisfied_survey: at least one answer to <survey> that counts as satisfied", "survey <survey> offers <choices>; <answers> is no answer it takes", "days must be a positive whole number: the window to read", "program_id is required: …", "id is required: …", "posted_url must be the https address of the posted review; got <value>" or "created_by is required: …"; not found with "no product has id <id>; echo-cli products lists the ones that exist", "product <id> has no survey named <survey>; echo-cli surveys list --product <id> lists them", "no review programme has id <id>; echo-cli reviews programs list --product <id> lists them" or "no review request has id <id>; echo-cli reviews requests --program <id> lists them"; and a conflict with "product <id> already has the review programme <name> as <id>". The daily run without its window answers "ECHO_REVIEW_WINDOW_DAYS is required" or "ECHO_REVIEW_WINDOW_DAYS must be a positive whole number of days, not <value>" as unavailable. The command prints Echo Web's sentence and exits 1.