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, otherwise the run stops here. Ops: eq|neq|contains|ncontains|startsWith|gt|lt|exists • { do: “branch”, rules, logic?, then: [steps], otherwise: [steps], thenEnds?, otherwiseEnds? }: routes instead of stopping. then runs when the rules match, otherwise when they do not, and whatever follows the branch runs on both paths. Set thenEnds/otherwiseEnds to true to finish the run on that side instead of carrying on. One side may be empty (“if it matches do this, otherwise just carry on”), but not both. Branches may nest three deep, and a nested branch must be the LAST step of the side it sits on. Rule fields for BOTH filter and branch depend on what reaches the step: while media is flowing use name|duration|sourceLanguage|tags|transcript|speakers or a custom field name; straight after an ai_chat step only “answer” is available, so put the branch BEFORE the ai_chat step if you need a media field. A filter and a branch CANNOT read the webhook payload: they only see the media and earlier answers. To branch on payload data, upload first with mapFields to write the value into a custom field, then branch on that field. • { 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), analyse?: “transcript” (default) | “audio” | “video”. What the model receives. “audio” lets it hear tone and delivery, “video” also lets it see the screen; on a video file “audio” extracts the audio track first. Premium: requires the account’s audio/video analysis opt-in and costs credits per hour of media } • { 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) } Legacy: a flat list where steps after a branch carry runWhen: “true”|“false” is still accepted and folded into then/otherwise, but it cannot express nesting or an ending side. Prefer then/otherwise. 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.
- Can delete or overwrite data. Use with care.
- Repeating an identical call can have an extra effect.
- Stays inside Speak AI. Does not reach other systems.
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.