Spark ERP Docs

Appearance

Reach customers with journeys - Engagement Studio, the CLI and MCP ​

The real problem ​

Northwind wants to tell customers whose contract ends in 30 days about renewal on WhatsApp. If nobody replies in two days, an AI voice agent should call. If the customer is interested, sales gets an opportunity. Nobody should be contacted at night, twice a day, or after they asked to stop.

A journey does this. It is a short flow of steps, run once for each customer, on the platform's workflow engine.

The idea in one minute ​

  • An audience is a saved group of customers: a record type plus filters, with a live count.
  • A journey starts from an audience. Each customer who enters gets their own run.
  • The steps are tiles: Message (e-mail, SMS, WhatsApp, push, in-app), Voice call (an AI voice agent), Wait, Wait for reply, Condition, AI decide, Create or update record, Notify a person and Exit.
  • A contact policy is checked before every message and call: opt-outs, the do-not-contact list, a limit on contacts per customer, and quiet hours. A step inside quiet hours waits until they end.
  • Waiting never holds a thread, so journeys survive a restart.

Designer path (Studio) ​

  1. Open Engagement Studio from the Home page, the Explorer tree or the command palette.
  2. Audiences > New: pick the record type, add filters, check the count and the preview.
  3. Journeys > New. Pick the audience, add tiles with the "+" between steps, and set branches side by side under a Condition, Voice call or Wait for reply tile.
  4. Or choose Describe the journey and type the goal. The model drafts the steps using only your own templates, agents and record types. Anything it could not decide comes back as a note. Read it before you publish.
  5. Check shows problems on the tile that has them (a message without a template, a voice call without an agent, a branch with no path).
  6. Publish, then Launch. Each tile shows how many customers reached it, are waiting, went down each branch or failed.

Code path (CLI and MCP) ​

Log in once with erp login. Then every Studio action has an operation: erp plugin op <name> on the command line, or the erp_plugin_op tool in your AI coding agent.

bash
# see the audience first
erp plugin op engagement-audience-preview --json '{"entity":"customer","phoneField":"phone","filters":[{"field":"status","op":"eq","value":"active"}]}'

# draft a journey from a plain description, then save what you like
erp plugin op engagement-journey-draft --need "Tell customers whose contract ends in 30 days about renewal on WhatsApp"
erp plugin op engagement-journey-set --code renewal-30 --json '{"name":"Renewal 30 days","audienceCode":"expiring-contracts","definition":{"tiles":[ ... ]}}'

# check, publish, launch
erp plugin op engagement-journey-check   --code renewal-30
erp plugin op engagement-journey-publish --code renewal-30
erp plugin op engagement-journey-launch  --code renewal-30

# watch it
erp plugin op engagement-members --code renewal-30
erp plugin op engagement-journey-pause   --code renewal-30

Run erp plugin op with no name to list every operation; the Engagement ones start with engagement-.

Safety and limits ​

  • Every message and call goes through the contact policy, whatever started it. Read it with engagement-contact-policy and the do-not-contact list with engagement-dnc.
  • A bot may draft a journey or count an audience, but launching waits for a person's approval.
  • WhatsApp messages to someone who has not written to you first need a template approved by Meta. Spark sends what the provider allows; the approval happens at Meta.
  • Journeys start from records. Starting from a website visitor, A/B splits and send-time optimisation are not built yet.

Seeing what happened ​

  • Members shows where each customer is and how their run ended.
  • A workflow run exists for every customer, so the workflow run record shows each step and its result.
  • Voice calls keep a recording and a summary on the call itself.

Where next ​