Automations

45 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Activate a workflow

automations.activatewriteconfirm

ARMS A LIVE AUTOMATION. Once active, every matching event fires this workflow's steps for real — sending SMS/email, placing calls, dropping voicemails, enrolling contacts in campaigns, spending the tenant's money — with no further human approval. Check the steps before turning it on.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

Field	Type	Required	Description
shared_page_acknowledged	boolean	optional	Set true only after acknowledging that this Page is connected to another Chirply account and enabling automation may send duplicate messages, replies or comments.
id	string (uuid)	required	The workflow to activate.

Example

curl -X POST https://app.chirply.io/api/v1/actions/automations.activate \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'

Field	Type	Required	Description
workflow_id	string (uuid)	required	The workflow to add to.
action	"find_create_contact" \| "google_sheets" \| "gmail_search" \| "gmail_read_message" \| "gmail_read_thread" \| "gmail_attachment" \| … 54 more	required	The action type this step performs.
action_config	map of string → object	optional	The action's settings, keyed by the field keys automations.list_action_types reports for this action type. For webhook/Call an API this includes url, method, query_params, auth_type plus its credential fields, headers, body_mode and the matching body field. Values support {{merge}} tokens where the field does. Default: {}

Field	Type	Required	Description
key	string	required	Your own name for the thing being done once, for example "appt-followup:<contact id>:reminder-1". Opaque to Chirply: two callers race only when they use the SAME string, so compose it from whatever makes two sends duplicates of each other.
ttl_seconds	integer	optional	How long the claim holds before the key can be won again, in seconds. Defaults to 86400 (24 hours); maximum 7776000 (90 days). Set it to the period over which a second send would be wrong, not to the length of the race.
detail	map of string → object	optional	Optional free-form JSON recorded against the claim — a run id, a step name — so a person reading it later can tell which run took the send. Never interpreted by Chirply.

Field	Type	Required	Description
template_id	string	required	Permanent built-in starter id or private saved-template UUID returned by automations.list_templates.
name	string	optional	Optional name for the new paused workflow; defaults to the template name.
asset_id	string (or null)	optional	Connected Instagram account id, Facebook Page id, or WhatsApp phone-number id required by built-in social starters; private saved templates retain their same-account binding.
keyword	string (or null)	optional	Case-insensitive word or phrase that must appear in the inbound comment or message. Required for whatsapp_lead_followup so an answer cannot restart the same workflow.
media_id	string (or null)	optional	Optional Instagram post or Reel id. When omitted, a comment template listens across that account.
destination_url	string (uri) (or null)	optional	Public http:// or https:// link delivered after the person replies. Required for instagram_comment_link; that template is rejected without it.

Field	Type	Required	Description
source	"recent_contact" \| "facebook_lead" \| "native_form"	required	Read the newest saved contact, a recent submission from a connected Facebook lead form, or the most recent completed submission of one of this account's own forms.
form_id	string	optional	Connected Facebook instant form ID. Required for facebook_lead; select a specific form in the trigger.
native_form_id	string (uuid)	optional	One of this account's own forms. Required for native_form; select a specific form in the Form submitted entry point.
mapping	any	optional	Optional JSON input containing trigger references to resolve against this sample without running a workflow step.

Field	Type	Required	Description
limit	integer	optional	Max rows to return (1–100). Default: 25
offset	integer	optional	Rows to skip. Default: 0
trigger	"gmail_message_received" \| "google_sheets_row_new" \| "google_sheets_row_updated" \| "custom_record_created" \| "custom_record_updated" \| "custom_record_deleted" \| … 80 more	optional	Only workflows on this trigger.
is_active	boolean	optional	true for live workflows, false for paused.
query	string	optional	Text to match in the name or description.

Field	Type	Required	Description
source	"starter" \| "saved"	optional	Optional source filter: Chirply starters or private templates saved by this account.
query	string	optional	Optional case-insensitive search across template name, description, category, and channel.
category	string	optional	Optional exact template category, such as social, sales, or support.

Field	Type	Required	Description
usable_as	"start" \| "stop"	optional	Only triggers usable in this position. Start and stop intentionally return the same catalog.
wired_only	boolean	optional	Only triggers something in the app actually raises today.

Field	Type	Required	Description
run_id	string (uuid)	required	Account workflow run supplying retained samples.
input	any	required	JSON action input containing trigger or steps references to preview.

Field	Type	Required	Description
id	string (uuid)	required	The workflow the step belongs to.
node_id	string	required	The canvas node to rename, as `id` on that node in automations.get's `flow.nodes`.
name	string	required	What to call this step, up to 60 characters. An empty string clears the name and restores the derived summary.

Field	Type	Required	Description
contact_id	string (uuid) (or null)	optional	A contact whose account fields fill {{merge}} tokens. The contact is not enrolled or changed.
url	string	required	The complete public HTTPS request URL. It may contain {{merge}} tokens.
method	"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"	optional	HTTP method to send. Write methods may change the external system. Default: "POST"
query_params	string	optional	Optional query parameters, one name=value pair per line. Do not put JSON here.
auth_type	"none" \| "bearer" \| "basic" \| "api_key"	optional	Authentication scheme added to the request. Default: "none"
auth_token	string	optional	Bearer token when auth_type is bearer. Supports {{merge}} tokens.
auth_username	string	optional	Basic authentication username when auth_type is basic.
auth_password	string	optional	Basic authentication password when auth_type is basic.
api_key_location	"header" \| "query"	optional	Whether an API key is sent as a request header or query parameter. Default: "header"
api_key_name	string	optional	Header or query-parameter name for API-key authentication, such as X-API-Key.
api_key_value	string	optional	API-key value when auth_type is api_key. Supports {{merge}} tokens.
headers	string	optional	Optional custom headers, one Header-Name: value pair per line.
body_mode	"context" \| "json" \| "form" \| "raw" \| "none"	optional	Request-body format. GET never sends a body. Default: "context"
body_json	string	optional	JSON request body when body_mode is json. It must remain valid after merge tokens are filled.
body_form	string	optional	Form body when body_mode is form, one name=value pair per line.
body_raw	string	optional	Unencoded request text when body_mode is raw.
content_type	string	optional	Content-Type header for a raw body, such as text/plain or application/xml.

Field	Type	Required	Description
workflow_id	string (uuid)	required	Workflow in this account holding the steps to freeze — a normal automation or a bot flow.
node_ids	string[]	required	Node ids from that workflow's graph to save. Connections between the chosen nodes are kept; a connection leading out of the selection is not, because it describes where the original went.
include_downstream	boolean	optional	When true, every step reachable from the given nodes is included as well — the way to save a whole follow-up sequence by naming only its first step. Default: false
name	string	required	Name shown in the builder's saved-step list. Reusing a name replaces that saved step.
description	string (or null)	optional	Optional explanation of what these steps do and when to reach for them, or null.

Field	Type	Required	Description
shared_page_acknowledged	boolean	optional	Set true only after acknowledging that this Page is connected to another Chirply account and enabling automation may send duplicate messages, replies or comments.
workflow_id	string (uuid)	required	The workflow to rewrite.
is_active	boolean	optional	Turn the automation on or off as part of the save. Turning it on is refused while the graph has blocking problems. Omit to leave it as it is.
flow	object	required	The complete flow graph.
flow.version	number	optional	Graph schema version. Omit for the current one.
flow.nodes	object[]	required	Every node in the graph, including at least one trigger.
flow.nodes[].id	string	required	Unique within this graph; edges reference it.
flow.nodes[].type	"trigger" \| "stop_trigger" \| "action" \| "wait" \| "branch" \| "switch" \| … 2 more	required	'trigger' enrolls a contact; 'stop_trigger' cancels their in-flight run; 'action' performs a registry action; 'wait' defers the run; 'branch' and 'switch' route it; 'end' finishes it; 'note' is canvas-only documentation.
flow.nodes[].label	string	required	Non-empty caption drawn on the builder's card.
flow.nodes[].position	object	required	Where the card sits on the canvas. Layout only; does not affect execution.
flow.nodes[].position.x	number	required	Horizontal canvas coordinate in pixels, increasing to the right.
flow.nodes[].position.y	number	required	Vertical canvas coordinate in pixels, increasing downward.
flow.nodes[].ends	string[]	optional	Outlet names on this node whose path deliberately finishes — the graph's way of saying "nothing runs after this" without an extra 'end' node. Purely a statement of intent: an unconnected outlet already stops the run either way, and an outlet named here that also has a connection is ignored (the connection wins). Omit it unless you are recording that choice.
flow.nodes[].data	map of string → object	required	Type-specific settings. trigger/stop_trigger: {trigger,config}. action: {action:{type,config}}. wait: {amount,unit}. branch: {condition:{type,key?,value?,op?}} where type is one of has_tag (key = tag id), lifecycle_is (value), has_email / has_phone (whether an address is HELD), can_email / can_text (whether it may be USED right now — reads the same unsubscribed list the send itself reads, so the branch and the send cannot disagree), form_answer (key = the submitted field's key, op = is \| is_not \| is_ticked \| is_not_ticked \| is_blank \| is_not_blank, value for the first two; only meaningful below a form_submitted trigger, and is_blank is the only operator that tells an explicitly unticked box apart from a question that was never asked), has_upcoming_appointment (key = an appointment type id to narrow to one type, or omit it for any — answers Yes when the calendar holds a confirmed appointment for the contact that has not happened yet, read live at the moment the branch runs, so a reschedule keeps answering Yes and cancelling one of two bookings leaves the other answering Yes), has_active_subscription (value = a Stripe product id 'prod_…', a comma-separated list of them, or a word matched case-insensitively against the plan/product name; omit it for any subscription at all — answers Yes when the contact holds a subscription that is 'active' or 'trialing', read live at the moment the branch runs, which is what makes it safe under a cancellation trigger: a contact who cancels one plan while still paying for another stays Yes), or field_equals / field_contains, where key is a contact column ('lifecycle', 'source', 'title', 'business_name', 'website', 'notes'), one of the organization's OWN contact custom fields written as 'custom.<field key>' (call contacts.list_fields for the keys), or a data reference such as '{{trigger.price_id}}' — a reference is resolved and compared against `value` itself, which is how a run is routed by what the enrolling event carried rather than by the contact record. switch: {key,cases} where key accepts the same three forms. end: {}. note: {text}.
flow.edges	object[]	required	The connections that define execution order.
flow.edges[].id	string	required	Unique within this graph.
flow.edges[].source	string	required	Node id this connection leaves.
flow.edges[].sourceHandle	string	required	Which outlet it leaves by: 'next' on most nodes, 'answered'/'invalid'/'timeout' on a conversation_ask, 'true'/'false' on a branch, or 'case:<key>'/'default' on a switch. One connection per outlet. Every start trigger's 'next' must point at the same node.
flow.edges[].target	string	required	Node id this connection arrives at.

Field	Type	Required	Description
id	string (uuid)	required	The automation (workflow) whose inbound webhook to configure.
field_map	object[]	optional	The complete mapping, replacing the current one. An empty array removes it. Unmapped keys stay run data (merge fields) as before.
field_map[].key	string	required	The incoming key: a top-level body key (an Elementor field label such as 'Your Email'), a dotted path into nested JSON ('lead.email'), or an Elementor Advanced Data field id ('email').
field_map[].target	string	required	The contact field it fills: email, phone, full_name, first_name, last_name, business_name, title, website, birthday, notes, address.line1, address.city, address.state, address.postal_code, address.country, tags (values become tag names, still subject to the tag policy), or custom.<field key> for one of the account's custom contact fields.
tag_mode	"any" \| "allowlist"	optional	'any' (the original behaviour): a request may apply any tag name it sends, creating tags that do not exist. 'allowlist': only names in allowed_tags are applied; anything else is ignored, never created, and reported in the response and the run log.
allowed_tags	string[]	optional	The tag names a request may apply when tag_mode is 'allowlist', replacing the current list. An empty list with 'allowlist' means no request may apply any tag.
write_policy	"create_and_update" \| "create_only" \| "update_fields"	optional	What a request may do to a contact that already exists. 'create_and_update' (the original behaviour) overwrites every field sent, email and phone included. 'create_only' adds new people but never changes an existing contact or its tags (the automation still runs for them). 'update_fields' changes only the fields in update_fields. New contacts are always created in full.
update_fields	string[]	optional	For write_policy 'update_fields': the fields a request may change on an existing contact, replacing the current list.
rate_limit_per_minute	integer	optional	Requests accepted per minute (a fixed one-minute window; default 120). Requests over it get HTTP 429 with Retry-After and are counted as rejected on the settings card.
consent_mode	"off" \| "field" \| "always"	optional	Email consent. 'off': requests record no consent. 'field': consent_field says whether the person ticked an email opt-in. 'always': every request is an opt-in (a newsletter-only form). A tick is recorded in the contact's communication-preferences history exactly like a native form's consent question, through double opt-in when it covers Automation webhooks. An unticked or missing box changes nothing.
consent_field	string (or null)	optional	For consent_mode 'field': the incoming key of the opt-in checkbox (for example Elementor's acceptance field id). Ticked = any value other than blank, no, false, 0 or off.
consent_text	string	optional	The opt-in wording shown beside the checkbox, recorded with every consent and quoted in a double opt-in email. Required while consent is on.
consent_text_field	string (or null)	optional	Optional incoming key that carries the wording; its value is recorded instead of consent_text when present.

Activate a workflow

Parameters

Example

Add a workflow step

Parameters

Example

Claim a send

Parameters

Example

Create automation

Parameters

Example

Build this flow

Parameters

Example

Delete a workflow

Parameters

Example

Delete saved step

Parameters

Example

Delete a workflow step

Parameters

Example

Delete workflow template

Parameters

Example

Duplicate workflow

Parameters

Example

Duplicate steps

Parameters

Example

Add contacts to an automation

Parameters

Example

Fetch sample data

Parameters

Example

Open a workflow

Parameters

Example

Check a claim

Parameters

Example

Open the automation flow

Parameters

Example

List automation mapping fields

Parameters

Example

Open an automation run

Parameters

Example

View saved step

Parameters

Example

Inspect automation step data

Parameters

Example

View workflow template

Parameters

Example

Copy AI instructions

Parameters

Example

Open webhook settings

Parameters

Example

Insert saved step

Parameters

Example

List workflows

Parameters

Example

List available step actions

Parameters

Example

List automation node events

Parameters