Automations

Workflows, their runs, and email / WhatsApp templates.

Each tool below is one switch in Settings → MCP Server. Your AI app sees a tool only when it is switched on for your role; every call is checked again on the server.

workflows

Automations: view · Read only

See the institute’s automations (workflows): each one’s trigger or schedule, its nodes, recent runs and per-node results, plus the authoring catalog and the batches, lead campaigns and message templates an automation can reference.

Action	What it does
list	every automation with its trigger or schedule, status, last/next run.
get	one automation as builder JSON — nodes with their config, edges, trigger, schedule — plus a one-line step summary.
runs	recent executions; with execution_id, that run’s per-node log (status, timing, error). A run marked COMPLETED can still contain FAILED nodes — read the node log before saying it worked.
catalog	the authoring contract the builder enforces. overview (default) has the workflow JSON shape and the hard generation rules; node_types each node’s config; queries prebuilt query keys with their output keys and item field names; triggers the common trigger events and every #ctx key each event provides; trigger_events the full event list; query_keys every query’s parameter contract; all everything.
context	the REAL ids to reference — batches (package_session_id), audiences (lead campaigns), templates (ACTIVE email + APPROVED WhatsApp, with their placeholders; WhatsApp templates still DRAFT/PENDING/REJECTED are listed separately and cannot be sent yet), live_sessions, invites. Never invent an id or a template name: take them from here.
template	one template in full — an email’s subject and HTML, or a WhatsApp template’s body, header, footer, buttons, sample values, status and rejection reason. Read it before reusing a template or writing templateVars for it.

Parameters

action · string · required

The action to run: list, get, runs, catalog, context, template.

workflow_id · string

get / runs: an automation id (from list).

execution_id · string

runs: one execution id (from runs) to get its per-node log.

status · string

list: ACTIVE, DRAFT, INACTIVE or ALL (default ALL).

search · string

list: name filter. context: filter batches/templates/etc. by name.

limit · integer

list / runs: max rows (default 20, max 50).

section · string

catalog: which part of the contract (default overview). One of: overview, node_types, queries, triggers, trigger_events, query_keys, all.

kind · string

context: one kind; omit for all kinds (capped). One of: batches, audiences, templates, live_sessions, invites.

channel · string

template: which channel the name belongs to. One of: EMAIL, WHATSAPP.

name · string

template: the template name (from context).

What your AI app is told about this tool

Read the institute's automations (workflows): event-driven or scheduled flows of nodes (QUERY, SEND_EMAIL, SEND_WHATSAPP, DELAY, CONDITION, ...) that message learners, leads and staff. Pick an `action`:
- list (status?, search?, limit?): every automation with its trigger or schedule, status, last/next run.
- get (workflow_id): one automation as builder JSON — nodes with their config, edges, trigger, schedule — plus a one-line step summary.
- runs (workflow_id?, execution_id?, limit?): recent executions; with execution_id, that run's per-node log (status, timing, error). A run marked COMPLETED can still contain FAILED nodes — read the node log before saying it worked.
- catalog (section?): the authoring contract the builder enforces. `overview` (default) has the workflow JSON shape and the hard generation rules; `node_types` each node's config; `queries` prebuilt query keys with their output keys and item field names; `triggers` the common trigger events and every #ctx key each event provides; `trigger_events` the full event list; `query_keys` every query's parameter contract; `all` everything.
- context (kind?, search?): the REAL ids to reference — batches (package_session_id), audiences (lead campaigns), templates (ACTIVE email + APPROVED WhatsApp, with their placeholders; WhatsApp templates still DRAFT/PENDING/REJECTED are listed separately and cannot be sent yet), live_sessions, invites. Never invent an id or a template name: take them from here.
- template (channel, name): one template in full — an email's subject and HTML, or a WhatsApp template's body, header, footer, buttons, sample values, status and rejection reason. Read it before reusing a template or writing templateVars for it.
To build an automation: read catalog(overview) and the sections you need, fetch context for the ids and templates, create any missing template with workflows_edit(create_email_template | create_whatsapp_template), compose the workflow JSON, then use workflows_edit(validate) until it is clean and workflows_edit(create_draft) to save it as a draft the admin publishes.

workflows_edit

Automations: draft · Makes changes · Drafts only — nothing goes live until someone publishes it in the admin portal.

Let the connected AI app build automations by conversation — compose the workflow (trigger, queries, emails, WhatsApp, delays, conditions), check it against the builder’s rules and save it as a DRAFT, and create the new email and WhatsApp templates it needs (WhatsApp templates go to Meta for approval). A draft never runs until you open it in the builder and publish it; published automations and existing templates cannot be changed or removed from here. Uses no AI credits.

What keeps it safe: draft-only + additive: every workflow save forces status=DRAFT, which never fires (triggers and the scheduler only run ACTIVE workflows); update/discard refuse anything that is not a DRAFT; the template actions only CREATE new email/WhatsApp templates (unused until an automation references them) and never edit or remove an existing one

Action	What it does
validate	normalise + lint + run the backend validator on a workflow JSON you composed. Saves nothing. Returns errors (must fix) and warnings (tell the admin).
create_draft	validate, then save as a new DRAFT. Returns the id and editor_url the admin reviews and publishes at. Refused while errors remain.
update_draft	replace a DRAFT automation’s definition. Refused for ACTIVE/INACTIVE automations — published ones are edited in the dashboard.
discard_draft	remove a DRAFT automation (the undo for create_draft). Refused for anything that is not a DRAFT.
create_email_template	a NEW email template a SEND_EMAIL node can reference by name. Write {{placeholders}} in the subject/html for per-recipient values; the placeholder list is derived for you and becomes the node’s templateVars keys. Plain {{var}} substitution only — no conditionals or loops. Names must be unique; existing templates are never changed (they may be in use by live automations).
create_whatsapp_template	a NEW WhatsApp template. Meta rules: name is lowercase letters/digits/underscores; variables are {{1}}, {{2}}, … in order; the body cannot start or end with a variable; one sample value per variable; body <= 1024 chars; category UTILITY (transactional: confirmations, reminders, credentials — default) or MARKETING (promotions; Meta rate-limits repeats to one number). It is submitted to Meta (status PENDING) unless submit=false; approval usually takes minutes to hours — the automation can be drafted now but the admin should publish after it is APPROVED.
sync_whatsapp_templates	pull the latest template statuses from Meta (use it to check whether a PENDING template got APPROVED, or to see templates made in Meta Business Manager).

Parameters

action · string · required

The action to run: validate, create_draft, update_draft, discard_draft, create_email_template, create_whatsapp_template, sync_whatsapp_templates.

workflow_id · string

update_draft / discard_draft: the DRAFT automation’s id.

workflow · object

validate / create_draft / update_draft: the workflow JSON (builder shape, see workflows(catalog)).

name · string

create_*_template: the template name. Email: any unique name, e.g. ‘welcome_new_learner’. WhatsApp: lowercase letters, digits, underscores.

subject · string

create_email_template: subject line; may contain {{placeholders}}.

html · string

create_email_template: the HTML body with {{placeholders}}, e.g. {{fullName}}.

placeholder_labels · object

create_email_template: optional human labels per placeholder, e.g. {“fullName”: “Learner name”} (shown in the builder’s mapping UI).

body · string

create_whatsapp_template: the message body with {{1}}, {{2}}, … variables.

category · string

create_whatsapp_template: UTILITY (default) or MARKETING. One of: UTILITY, MARKETING.

language · string

create_whatsapp_template: Meta language code, default en.

sample_values · string[]

create_whatsapp_template: one realistic example per {{n}} variable, in order (Meta reviews with these).

variable_names · string[]

create_whatsapp_template: optional semantic names per variable, e.g. [‘name’, ‘class_time’].

header_text · string

create_whatsapp_template: optional short text header (no variables).

footer_text · string

create_whatsapp_template: optional footer line.

buttons · object[]

create_whatsapp_template: optional buttons (max 3): {type: QUICK_REPLY|URL|PHONE_NUMBER, text, url?, phone_number?}.

submit · boolean

create_whatsapp_template: submit to Meta for approval right away (default true).

What your AI app is told about this tool

Create and edit DRAFT automations (workflows). Nothing here ever runs or goes live: every action saves status=DRAFT, and a draft fires only after the admin reviews it in the builder and presses Publish. Pick an `action`:
- validate (workflow): normalise + lint + run the backend validator on a workflow JSON you composed. Saves nothing. Returns errors (must fix) and warnings (tell the admin).
- create_draft (workflow): validate, then save as a new DRAFT. Returns the id and editor_url the admin reviews and publishes at. Refused while errors remain.
- update_draft (workflow_id, workflow): replace a DRAFT automation's definition. Refused for ACTIVE/INACTIVE automations — published ones are edited in the dashboard.
- discard_draft (workflow_id): remove a DRAFT automation (the undo for create_draft). Refused for anything that is not a DRAFT.
- create_email_template (name, subject, html, placeholder_labels?): a NEW email template a SEND_EMAIL node can reference by name. Write {{placeholders}} in the subject/html for per-recipient values; the placeholder list is derived for you and becomes the node's templateVars keys. Plain {{var}} substitution only — no conditionals or loops. Names must be unique; existing templates are never changed (they may be in use by live automations).
- create_whatsapp_template (name, body, category?, language?, sample_values?, variable_names?, header_text?, footer_text?, buttons?, submit?): a NEW WhatsApp template. Meta rules: name is lowercase letters/digits/underscores; variables are {{1}}, {{2}}, ... in order; the body cannot start or end with a variable; one sample value per variable; body <= 1024 chars; category UTILITY (transactional: confirmations, reminders, credentials — default) or MARKETING (promotions; Meta rate-limits repeats to one number). It is submitted to Meta (status PENDING) unless submit=false; approval usually takes minutes to hours — the automation can be drafted now but the admin should publish after it is APPROVED.
- sync_whatsapp_templates: pull the latest template statuses from Meta (use it to check whether a PENDING template got APPROVED, or to see templates made in Meta Business Manager).
`workflow` follows workflows(catalog) → workflowJsonShape: {name, description, workflow_type EVENT_DRIVEN|SCHEDULED, trigger{trigger_event_name, event_applied_type, event_ids[], idempotency_generation_setting} | schedule{schedule_type CRON, cron_expression, timezone}, nodes[{id, name, node_type, config, is_start_node}], edges[{source_node_id, target_node_id, label?, condition?}]}. Wire the flow with edges (routing is derived from them): a CONDITION node's true branch is the edge carrying `condition`, its false branch the edge labelled 'false'. Use only ids and template names returned by workflows(context). Obey every rule in catalog.generationRules; the same rules are linted here.