Spark ERP Docs

Appearance

Build a bot - flows, triggers, approvals, portal data and phone calls ​

The real problem ​

Northwind wants a bot that answers customers on the website, looks up their own orders, and can change a delivery date only after a person approves. It should also call customers whose payment is overdue, and start by itself when an invoice crosses a limit.

A bot and a voice agent are the same thing: an agent with extra settings. Chat, WhatsApp, the website and the phone are its channels.

The idea in one minute ​

  • The Bot designer starts from a business need. You describe it, or pick a template, and the designer drafts the bot using only your real record types and tools.
  • A bot has a type (eight kinds), data (which record types it may read or change, with which tools), starter questions and a flow.
  • The flow is a list of steps: trigger, data, knowledge, reasoning, condition, action, workflow, API, approval, hand to a person, notify, phone call and respond. It becomes the bot's written procedure.
  • An approval step makes the next action wait for a person, whatever its risk level.
  • Triggers start a bot by itself: a record change (optionally to a given value), a threshold being crossed (fires once, when it starts to match), a schedule (every N minutes or daily), a webhook, a document upload, or a call ending (optionally with a given outcome). Each runs as a chosen user, with a per-hour limit.
  • Portal member data: on a website chat shown on the bot's portal, a signed-in member gets my_records and search_my_data. They use the member's own sign-in, so the portal's rules decide what comes back. There is nothing without a sign-in and nothing across portals.

Designer path (Studio) ​

  1. Open AI Studio > Bots > New. Describe the need, or choose a template such as Customer Care Voice.
  2. Fill the empty steps. Templates leave tools, e-mail addresses and trigger records empty on purpose, because they travel between organisations. The designer marks each empty step.
  3. Triggers tab: add a trigger, pick the user it runs as, set the limit. Run now tests it with a made-up event.
  4. Voice tab: choose speech profiles, the voice, speed, languages, persona and greeting. Set consent, how the agent verifies callers, whether it reads an action back before doing it, transfer to a person, recording and retention. Hear the greeting plays the saved voice. Talk to it lets you speak to the bot in the browser.
  5. Voice and calls: phone lines, calls with summary, transcript and recordings, analytics, and campaigns.

Phone calls ​

  • Lines: a line ties a phone number to an answering agent and a run-as user. Twilio is the first provider. The webhook address is shown for each line; give it to Twilio. Twilio's signature is checked on every call.
  • Callers are verified by their number, a code sent by text message, an id and PIN, or an id and questions. Only hashes of the expected answers are kept. A caller's number alone only identifies the record when another method follows, because numbers can be spoofed or shared.
  • Spoken confirmation: before a change, the agent reads it back ("Before I go ahead: ..., shall I do it?"). Yes or 1 approves it, up to the agent's risk level. Yes and no are understood in English and ten Indian languages.
  • Transfer: to a person when asked, when the agent decides, or after failed verification. The call record gets the reason.
  • After each call: a summary, outcome, sentiment and follow-ups, plus the agent's own outcomes and noted fields. The call ending is announced and can start another bot. Recordings are kept only with consent, stored in document management, and removed after the agent's retention days.
  • Campaigns call a list of people inside a calling window and time zone, on chosen days, once or on repeat, with tries and a retry gap.

Code path (CLI and MCP) ​

bash
erp plugin op agent-list
erp plugin op agent-draft     --prompt "A bot that answers order questions and can move a delivery date after approval"
erp plugin op agent-publish   --agentCode order-helper
erp plugin op agent-run       --agentCode order-helper --input "Where is order 1042?"
erp plugin op agent-executions --agentCode order-helper
erp plugin op agent-steps     --executionId <id>        # model calls, tool calls, approvals
erp plugin op voice-calls
erp plugin op voice-call      --id <sessionId>
erp plugin op voice-campaigns

A bot ships inside a plugin as an agent asset, or through the AI bundle export and import.

Safety and limits ​

  • Every tool call runs with the caller's permissions. The platform enforces them, not the model.
  • A published agent follows the organisation's publish policy and guardrails.
  • Triggers run as a named user, not as an administrator by default, and have an hourly limit.
  • Phone webhooks and the bot webhook are open at the gateway but check their own key or signature.

Seeing what happened ​

  • Trace explorer and the run's steps show what the bot did and why.
  • Hand-overs lists open requests where a bot passed a conversation to a person.
  • The call page shows the transcript, summary and earlier calls from the same person.

What is not built, and what is not yet tested live ​

  • Browser voice sends one spoken sentence at a time over HTTP. It is not a streaming audio connection, and there is no guaranteed time to first words.
  • Twilio is the only phone provider. There is no hold or conference.
  • The hand-over summary arrives seconds after the transfer starts, not before the person picks up.
  • No payment-link tool ships. Add one, for example an integration flow or a commerce tool, before using the template's payment step.
  • The designer does not yet show all channels in one place.
  • The unit tests pass, but these have not been run end to end in a live environment: approval holding a real changing action, every trigger kind, portal member tools with two members, and a real phone call. Check them in your environment before relying on them.

Where next ​