build_automation is a tool in the Speak AI MCP server. High-level automation
builder: create (or update) a Speak automation from a friendly spec without knowing
the wire format.
What does it do?
High-level automation builder: create (or update) a Speak automation from a friendly
spec without knowing the wire format. Accepts folder/custom-field NAMES (resolved to
ids; missing folders are auto-created), payload.<path> shorthand for webhook
tokens, and simple step types (filter, branch, upload, ai_chat, translate, notify,
call_webhook). For inbound-webhook automations the result includes the receive URL
and mappable payload tokens. Prefer this over create_automation unless you need
raw control.
Parameters
build_automation takes 7 parameters, 3 of them required.
| Name | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Display name for the automation |
trigger |
object | Yes | What starts the automation. Object with: • on (required): “media_analyzed” | “inbound_webhook” | “field_updated” • folders: array of folder names or ids (required for media_analyzed; missing folders are created) • childKey: dot-path narrowing the webhook payload root, e.g. “data” (inbound_webhook only) • webhookId: reuse a webhook from provision_inbound_webhook (inbound_webhook only; omit to auto-provision) • watchFields: array of { field: name-or-id, values?: string[] } (required for field_updated. Fires when the field changes; values restricts to specific new values) • matchLogic: “AND”|“OR” for combining multiple watchFields value matches (default OR) |
steps |
array of object | Yes | Ordered actions. Each step is an object with a do key plus its options. String values may be literals, “payload.<path>” shorthand (converted to {{trigger.payload.<path>}} only when it is the ENTIRE value), or raw {{…}} tokens: inside longer text, write the full {{trigger.payload.<path>}} form. • { do: “filter”, rules: [{ field, op, value? }], logic?: “AND”|“OR” }. Continue only if rules match. Fields: media flows use name|duration|sourceLanguage|tags|transcript|speakers or a custom field name; webhook payloads use payload paths like “contact.status”. Ops: eq|neq|contains|ncontains|startsWith|gt|lt|exists • { do: “branch”, rules, logic? }. Like filter but routes instead of stopping; later steps with runWhen: “true”|“false” only run on that outcome. NOTE: branch routing requires the server’s DAG runner (feature-flagged); when it is off, steps run in order and runWhen markers are ignored. Prefer filter for guaranteed gating • { do: “upload”, source (URL or payload.<path>, required), name?, language? (e.g. “en-US”), folder? (name or id; created if missing), folderFromPayload? (payload key holding the destination folder name. Dynamic routing), onNoFolderMatch?: “create”|“default”, mapFields?: { <field name or id>: <value or payload.<path>> } (writes payload values into custom fields on the uploaded media) } • { do: “ai_chat”, prompt? (required unless saveToFields given), title?, saveToFields?: [field names or ids] (max 10. Values are extracted into these custom fields; prompt may be omitted for extraction-only steps), model? (a Speak-supported LLM id, e.g. “gemini-2.5-flash”, “claude-sonnet-4-6”; omit for the workspace default) } • { do: “translate”, language: region-qualified code like “es-ES”, “fr-FR” } • { do: “notify”, message (required, tokens allowed), channel?: “in_app”|“email”|“slack” (default in_app; email currently falls back to an in-app notification), target? (reserved. Not yet used for delivery) } • { do: “call_webhook”, url (required), method?, headers?, body? (string or object template, tokens allowed) } Steps may also set runWhen (after a branch step). Composio app actions (Google Drive, Slack apps, …) are not supported by this builder yet: use create_automation directly for those. |
automationId |
string | No | Update this existing automation instead of creating a new one (full replace) |
description |
string | No | Optional description |
isActive |
boolean | No | Whether the automation is active (default true) |
orTriggers |
array of object | No | Additional “Or” triggers (same shape as trigger, but inbound_webhook is not allowed here). The automation runs when ANY trigger fires. |
Behaviour
The Speak AI MCP server publishes these behaviour hints for build_automation.
- Can change data in your workspace.
- Does not delete or overwrite existing data.
- Repeating an identical call can have an extra effect.
- Can reach systems outside Speak AI.
Related
- Automations lists the rest of the Automations category.
- Tool reference lists every Speak AI MCP server tool.
- MCP server covers setup, supported clients, and what agents can do once connected.