Sign inStart free trial

← All action domains

Bot flows

20 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 bot flow

bot_flows.activatewriteconfirm

ARM A LIVE BOT. Every matching Facebook, Instagram, WhatsApp, comment, ad, link, button, or menu entry can immediately send real provider messages and run paid or mutating actions with no further approval.

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

FieldTypeRequiredDescription
shared_page_acknowledgedbooleanoptionalSet true only after acknowledging that this Page is connected to another Chirply account and enabling automation may send duplicate messages, replies or comments.
idstring (uuid)requiredThe reviewed bot flow to activate.

Example

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

Over MCP the same operation is the tool bot_flows_activate at https://app.chirply.io/api/mcp, same bearer token, same input.

Create bot flow

bot_flows.createwrite

Create a new conversational bot-flow draft with one social or manual entry trigger. It is always PAUSED, creates an editable visual graph, sends no messages, and must be activated separately after review.

Parameters

FieldTypeRequiredDescription
namestringrequiredName shown in the bot-flow studio.
descriptionstring (or null)optionalOptional explanation for teammates, or null.
trigger"manual" | "facebook_message_received" | "facebook_messenger_event_received" | "facebook_comment_received" | "instagram_message_received" | "instagram_comment_received" | … 1 morerequiredHow a person enters this bot flow; bot_flows.list_triggers explains each value and its filters. Use manual for menu-only reusable flows.
page_idstringoptionalConnected Facebook Page, Instagram account, or WhatsApp number id to scope this bot flow.
entry_point"direct_message" | "story_reply" | "story_mention" | "story_reaction" | "quick_reply" | "postback" | … 5 moreoptionalOptional exact Messenger or Instagram conversation origin, such as Get Started, referral link, or ad.
event_type"account_linking" | "customer_feedback" | "response_feedback" | "game_play" | "optin" | "customer_information" | … 1 moreoptionalOptional exact signed Messenger event that starts this flow, such as account linking, customer feedback, or an in-thread lead form submission; leave blank for any supported Messenger event.
payloadstringoptionalOptional exact button, menu, referral, or ad payload for a message entry.
ad_idstringoptionalOptional exact Meta click-to-message ad id for a message entry.
keywordstringoptionalOptional case-insensitive phrase required in an inbound message or comment.
post_idstringoptionalOptional exact Facebook Page or eligible ad-post id for a Facebook comment entry.
media_idstringoptionalOptional exact Instagram post or Reel id for an Instagram comment entry.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.create \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "trigger": "manual"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_create at https://app.chirply.io/api/mcp, same bearer token, same input.

Use bot template

bot_flows.create_from_templatewrite

Create a PAUSED bot flow from a social starter or private bot template. It sends nothing until separately reviewed and activated; normal automation templates are rejected.

Parameters

FieldTypeRequiredDescription
template_idstringrequiredStarter id or saved bot-template UUID returned by bot_flows.list_templates.
namestringoptionalOptional name for the new paused bot flow.
asset_idstring (or null)optionalConnected Facebook Page, Instagram account, or WhatsApp number required by channel starters.
keywordstring (or null)optionalOptional or starter-required inbound keyword matched case-insensitively.
media_idstring (or null)optionalOptional Instagram post or Reel id for a comment starter.
destination_urlstring (uri) (or null)optionalOptional public link a compatible starter delivers after the person replies.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.create_from_template \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_create_from_template at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete bot flow

bot_flows.deletewriteconfirm

Permanently delete one bot flow, its legacy steps, and its complete run history. It can no longer answer connected entry points and this cannot be undone.

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

FieldTypeRequiredDescription
idstring (uuid)requiredThe bot flow to permanently delete.

Example

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

Over MCP the same operation is the tool bot_flows_delete at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete bot template

bot_flows.delete_templatewriteconfirm

Permanently delete one private saved bot-flow template. Existing bot flows remain intact, normal automation templates are rejected, and the deleted template cannot be recovered.

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

FieldTypeRequiredDescription
template_idstring (uuid)requiredPrivate saved bot-template UUID to permanently delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.delete_template \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_delete_template at https://app.chirply.io/api/mcp, same bearer token, same input.

Duplicate bot flow

bot_flows.duplicatewrite

Create a separate PAUSED copy of one bot flow's graph without copying runs or history. It sends nothing, preserves bot-flow identity, and rejects normal automation ids.

Parameters

FieldTypeRequiredDescription
workflow_idstring (uuid)requiredBot flow in this account to copy.
namestringoptionalOptional name for the paused copy.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.duplicate \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_duplicate at https://app.chirply.io/api/mcp, same bearer token, same input.

Open a bot flow

bot_flows.getread

Fetch one conversational bot flow with its complete graph and legacy ordered steps. A normal automation id is treated as not found and no messages are sent.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe bot flow id returned by bot_flows.list.

Example

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

Over MCP the same operation is the tool bot_flows_get at https://app.chirply.io/api/mcp, same bearer token, same input.

Open the bot canvas

bot_flows.get_flowread

Fetch the complete graph drawn by the bot-flow canvas, including entry triggers, rich messages, AI replies, questions, logic, waits, actions, and handoffs. This is read-only. Pair it with bot_flows.list_node_types to interpret each node's data, and with automations.fetch_mapping_sample / automations.get_mapping_fields, which accept bot-flow ids, to inspect the data a step can merge.

Parameters

FieldTypeRequiredDescription
workflow_idstring (uuid)requiredThe bot flow whose graph should be returned.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.get_flow \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_get_flow at https://app.chirply.io/api/mcp, same bearer token, same input.

Open a bot-flow run

bot_flows.get_runread

Fetch one bot-flow run with full execution context and error details for debugging. A normal automation run id is treated as not found and nothing is changed.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe bot-flow run id returned by bot_flows.list_runs.

Example

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

Over MCP the same operation is the tool bot_flows_get_run at https://app.chirply.io/api/mcp, same bearer token, same input.

View bot template

bot_flows.get_templateread

Return one bot-flow starter or private bot template with its frozen visual graph. Normal automation templates are hidden and this read changes nothing.

Parameters

FieldTypeRequiredDescription
template_idstringrequiredStarter id or saved bot-template UUID returned by bot_flows.list_templates.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.get_template \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_get_template at https://app.chirply.io/api/mcp, same bearer token, same input.

List bot flows

bot_flows.listread

List only this account's conversational bot flows, never normal CRM automations, with trigger and paused/live state. This is read-only and sends no messages.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
trigger"manual" | "facebook_message_received" | "facebook_messenger_event_received" | "facebook_comment_received" | "instagram_message_received" | "instagram_comment_received" | … 1 moreoptionalOnly bot flows using this first start trigger.
is_activebooleanoptionaltrue for live bot flows or false for paused drafts.
querystringoptionalCase-insensitive text to match in name or description.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.list \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_list at https://app.chirply.io/api/mcp, same bearer token, same input.

List bot-flow step types

bot_flows.list_node_typesread

The complete node vocabulary a bot-flow graph accepts — the same palette the visual builder shows — with each type's purpose, the exact JSON shape of its data field, a ready-to-copy default_data, its preset variants (rich-message formats and Messenger sender actions), and the outlet ids connections leave from. Call this before composing nodes for bot_flows.set_flow so no node shape is guessed; pair it with bot_flows.list_triggers for entry triggers and automations.list_action_types for what an action node can run. Read-only: nothing changes and no messages are sent.

Parameters

FieldTypeRequiredDescription
type"trigger" | "stop_trigger" | "action" | "conversation_message" | "conversation_ask" | "conversation_ai_reply" | … 8 moreoptionalOnly this node type's catalog entry; omit for the whole vocabulary.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.list_node_types \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "trigger"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_list_node_types at https://app.chirply.io/api/mcp, same bearer token, same input.

List bot-flow runs

bot_flows.list_runsread

List execution history only for bot flows, including status, contact, current step, and errors. Normal automation runs are excluded and this read changes nothing.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
workflow_idstring (uuid)optionalOnly runs of this bot flow.
status"pending" | "running" | "waiting" | "completed" | "failed" | "canceled"optionalOnly runs in this execution status.
contact_idstring (uuid)optionalOnly runs for this contact.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.list_runs \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_list_runs at https://app.chirply.io/api/mcp, same bearer token, same input.

List bot templates

bot_flows.list_templatesread

List Chirply's social bot starters and this account's private saved bot-flow templates. Normal automation templates are excluded; this read creates nothing.

Parameters

FieldTypeRequiredDescription
source"starter" | "saved"optionalOptional source filter for Chirply starters or account-saved bot templates.
querystringoptionalOptional case-insensitive template search text.
categorystringoptionalOptional exact template category such as social or support.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.list_templates \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "starter",
    "query": "example"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_list_templates at https://app.chirply.io/api/mcp, same bearer token, same input.

List bot-flow entry triggers

bot_flows.list_triggersread

Every way a person can ENTER a bot flow — the only values bot_flows.create's trigger and a trigger node's data.trigger accept — with each entry's meaning and the optional config filters that narrow it (such as page_id, keyword, entry_point, payload, ad_id, event_type, post_id, media_id). Stop-trigger nodes are not limited to this list; they accept any automations.list_trigger_types event with can_stop true. Read-only: nothing changes and no messages are sent.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.list_triggers \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool bot_flows_list_triggers at https://app.chirply.io/api/mcp, same bearer token, same input.

Pause bot flow

bot_flows.pausewrite

Stop a bot flow from accepting new matching entries while retaining its graph and run history. It can be activated again later and this action sends no messages.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe bot flow to pause.

Example

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

Over MCP the same operation is the tool bot_flows_pause at https://app.chirply.io/api/mcp, same bearer token, same input.

Rename a bot flow node

bot_flows.rename_nodewrite

Give one card on a bot flow's canvas its own name, so several cards that all send a message can be told apart. The name replaces the summary the card derives from its settings — on the canvas, in the next-step pickers and in a conversation's run history — and an empty name puts that summary back. A caption only: the node keeps its id, its settings, its connections and its place in the conversation, so nothing the bot says or does changes. Use bot_flows.get_flow to read the current graph and its node ids.

Parameters

FieldTypeRequiredDescription
workflow_idstring (uuid)requiredThe bot flow the node belongs to.
node_idstringrequiredThe canvas node to rename, as `id` on that node in bot_flows.get_flow's `flow.nodes`.
namestringrequiredWhat to call this node, up to 60 characters. An empty string clears the name and restores the derived summary.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.rename_node \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "node_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "name": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_rename_node at https://app.chirply.io/api/mcp, same bearer token, same input.

Save bot template

bot_flows.save_as_templatewrite

Save a private frozen copy of a bot flow's current graph for reuse in this account. It sends nothing, preserves bot-flow identity, and rejects normal automation ids.

Parameters

FieldTypeRequiredDescription
workflow_idstring (uuid)requiredBot flow whose current graph should be frozen.
namestringrequiredPrivate bot-template name.
descriptionstring (or null)optionalOptional explanation, or null.
categorystringoptionalSearchable template category such as social or support. Default: "social"

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.save_as_template \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "name": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_save_as_template at https://app.chirply.io/api/mcp, same bearer token, same input.

Save the bot canvas

bot_flows.set_flowwriteconfirm

Replace a bot flow's complete graph. If the bot is live, future matching people immediately follow the new graph and its real provider messages, AI replies billed to its own OpenRouter account, CRM changes, calls, or paid actions; pass the whole graph, not a partial patch. Call bot_flows.list_node_types and bot_flows.list_triggers FIRST for every legal node type, its data shape, and the entry triggers, instead of guessing against validation errors. Reusable saved steps work here too: automations.list_saved_steps, automations.insert_saved_step, and automations.duplicate_steps accept bot-flow ids.

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

FieldTypeRequiredDescription
shared_page_acknowledgedbooleanoptionalSet true only after acknowledging that this Page is connected to another Chirply account and enabling automation may send duplicate messages, replies or comments.
workflow_idstring (uuid)requiredThe bot flow whose complete graph should be replaced.
flowobjectrequiredThe complete replacement graph, not a partial patch.
flow.versionnumberoptionalGraph schema version; omit to use the current version.
flow.nodesobject[]requiredEvery node in the complete bot-flow graph.
flow.nodes[].idstringrequiredUnique node id inside this graph; connections reference it.
flow.nodes[].type"trigger" | "stop_trigger" | "action" | "conversation_message" | "conversation_ask" | "conversation_ai_reply" | … 8 morerequiredThe behavior represented by this visual-canvas node. Call bot_flows.list_node_types for each type's purpose, data shape, presets, and outlets.
flow.nodes[].labelstringrequiredThe palette caption for this node type, stamped when the card is created. Use `name` to give one card its own title.
flow.nodes[].namestringoptionalThe author's own name for this node, shown instead of the derived summary on the canvas, in the step pickers and in run history. Omit it, or send an empty string, to fall back to that summary. A caption only — it never changes what the node does.
flow.nodes[].positionobjectrequiredVisual position only; it does not affect execution.
flow.nodes[].position.xnumberrequiredHorizontal canvas coordinate in pixels.
flow.nodes[].position.ynumberrequiredVertical canvas coordinate in pixels.
flow.nodes[].endsstring[]optionalOutlet 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[].datamap of string → objectrequiredType-specific trigger, message, question, Messenger sender action, Messenger webview, action, branch, wait, handoff, or note settings. Never guess this shape: bot_flows.list_node_types documents every type's exact data structure with a ready-to-copy default, and bot_flows.list_triggers holds the legal data.trigger values for trigger nodes.
flow.edgesobject[]requiredEvery directed connection in the complete bot-flow graph.
flow.edges[].idstringrequiredUnique connection id inside this graph.
flow.edges[].sourcestringrequiredNode id this connection leaves.
flow.edges[].sourceHandlestringrequiredOutlet name such as next, reply:<quick-reply-id>, answered, submitted, invalid, timeout, true, false, case:<key>, or default. Connecting any reply:<quick-reply-id> outlet on a Send Message node makes that card wait for a trusted quick-reply tap; unconnected replies and typed answers fall back to next.
flow.edges[].targetstringrequiredNode id this connection enters.

Example

curl -X POST https://app.chirply.io/api/v1/actions/bot_flows.set_flow \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "flow": {
      "nodes": [
        {
          "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
          "type": "trigger",
          "label": "example",
          "position": {
            "x": 1,
            "y": 1
          },
          "data": {}
        }
      ],
      "edges": [
        {
          "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
          "source": "example",
          "sourceHandle": "example",
          "target": "example"
        }
      ]
    }
  }'
Test with your API key

Over MCP the same operation is the tool bot_flows_set_flow at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit bot flow details

bot_flows.updatewrite

Update a bot flow's internal name or teammate description. This does not change its graph, activation state, recipients, or message delivery.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe bot flow to rename or describe.
namestringoptionalNew bot-flow name; omit to keep it.
descriptionstring (or null)optionalNew teammate description, null to clear it, or omit to keep it.

Example

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

Over MCP the same operation is the tool bot_flows_update at https://app.chirply.io/api/mcp, same bearer token, same input.

The machine-readable version of this page is GET https://app.chirply.io/api/v1/actions?domain=bot_flows — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.