> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vacademy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. |

<Accordion title="Parameters">
  <ParamField path="action" type="string" required>
    The action to run: `list`, `get`, `runs`, `catalog`, `context`, `template`.
  </ParamField>

  <ParamField path="workflow_id" type="string">
    get / runs: an automation id (from `list`).
  </ParamField>

  <ParamField path="execution_id" type="string">
    runs: one execution id (from `runs`) to get its per-node log.
  </ParamField>

  <ParamField path="status" type="string">
    list: ACTIVE, DRAFT, INACTIVE or ALL (default ALL).
  </ParamField>

  <ParamField path="search" type="string">
    list: name filter. context: filter batches/templates/etc. by name.
  </ParamField>

  <ParamField path="limit" type="integer">
    list / runs: max rows (default 20, max 50).
  </ParamField>

  <ParamField path="section" type="string">
    catalog: which part of the contract (default overview). One of: `overview`, `node_types`, `queries`, `triggers`, `trigger_events`, `query_keys`, `all`.
  </ParamField>

  <ParamField path="kind" type="string">
    context: one kind; omit for all kinds (capped). One of: `batches`, `audiences`, `templates`, `live_sessions`, `invites`.
  </ParamField>

  <ParamField path="channel" type="string">
    template: which channel the name belongs to. One of: `EMAIL`, `WHATSAPP`.
  </ParamField>

  <ParamField path="name" type="string">
    template: the template name (from context).
  </ParamField>
</Accordion>

<Accordion title="What your AI app is told about this tool">
  ```text theme={null}
  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.
  ```
</Accordion>

## `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.

<Note>
  **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
</Note>

| 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). |

<Accordion title="Parameters">
  <ParamField path="action" type="string" required>
    The action to run: `validate`, `create_draft`, `update_draft`, `discard_draft`, `create_email_template`, `create_whatsapp_template`, `sync_whatsapp_templates`.
  </ParamField>

  <ParamField path="workflow_id" type="string">
    update\_draft / discard\_draft: the DRAFT automation's id.
  </ParamField>

  <ParamField path="workflow" type="object">
    validate / create\_draft / update\_draft: the workflow JSON (builder shape, see workflows(catalog)).
  </ParamField>

  <ParamField path="name" type="string">
    create\_\*\_template: the template name. Email: any unique name, e.g. 'welcome\_new\_learner'. WhatsApp: lowercase letters, digits, underscores.
  </ParamField>

  <ParamField path="subject" type="string">
    create\_email\_template: subject line; may contain \{\{placeholders}}.
  </ParamField>

  <ParamField path="html" type="string">
    create\_email\_template: the HTML body with \{\{placeholders}}, e.g. \{\{fullName}}.
  </ParamField>

  <ParamField path="placeholder_labels" type="object">
    create\_email\_template: optional human labels per placeholder, e.g. \{"fullName": "Learner name"} (shown in the builder's mapping UI).
  </ParamField>

  <ParamField path="body" type="string">
    create\_whatsapp\_template: the message body with \{\{1}}, \{\{2}}, ... variables.
  </ParamField>

  <ParamField path="category" type="string">
    create\_whatsapp\_template: UTILITY (default) or MARKETING. One of: `UTILITY`, `MARKETING`.
  </ParamField>

  <ParamField path="language" type="string">
    create\_whatsapp\_template: Meta language code, default en.
  </ParamField>

  <ParamField path="sample_values" type="string[]">
    create\_whatsapp\_template: one realistic example per \{\{n}} variable, in order (Meta reviews with these).
  </ParamField>

  <ParamField path="variable_names" type="string[]">
    create\_whatsapp\_template: optional semantic names per variable, e.g. \['name', 'class\_time'].
  </ParamField>

  <ParamField path="header_text" type="string">
    create\_whatsapp\_template: optional short text header (no variables).
  </ParamField>

  <ParamField path="footer_text" type="string">
    create\_whatsapp\_template: optional footer line.
  </ParamField>

  <ParamField path="buttons" type="object[]">
    create\_whatsapp\_template: optional buttons (max 3): \{type: QUICK\_REPLY|URL|PHONE\_NUMBER, text, url?, phone\_number?}.
  </ParamField>

  <ParamField path="submit" type="boolean">
    create\_whatsapp\_template: submit to Meta for approval right away (default true).
  </ParamField>
</Accordion>

<Accordion title="What your AI app is told about this tool">
  ```text theme={null}
  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.
  ```
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.