---
title: "Build Automation"
description: "High-level automation builder: create (or update) a Speak automation from a friendly spec without knowing the wire format."
---

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

# Build Automation

`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](/mcp/tools/automations/) lists the rest of the Automations category.
- [Tool reference](/mcp/tools/) lists every Speak AI MCP server tool.
- [MCP server](/mcp/) covers setup, supported clients, and what agents can do once
  connected.

Source: https://docs.speakai.co/mcp/tools/automations/build_automation/index.mdx