Conversational flows
MarkdownEsta página aún no está disponible en tu idioma.
Build, edit node by node, test, publish and roll back the flows that run the virtual agent.
choice_create
Section titled “choice_create”Create a choice node · Changes data · can overwrite or remove · Listed to the agent from the start
Creates a semantic choice node wired to an existing intent set. branch_targets = {branch_name: target_node_id}: each branch_name must exist in the set (validated) and the value is the target node. default_to = node used when there is no semantic match. The node is born with mode='semantic' and intentSetId; edit it later with flow_patch_node. Populate the set first with intent_set_upsert_branch. It is inserted like flow_add_node, without regenerating the flow.
| Argument | Type | Required | Description |
|---|---|---|---|
branch_targets |
object | Yes | |
client_id |
string | Yes | |
default_to |
string | Yes | |
flow_id |
string | Yes | |
intent_set_id |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
input |
string | No | |
label |
string | No | |
node_id |
string | No | |
threshold |
number | No | |
top_k |
integer | No | |
ui |
object | No |
flow_activate
Section titled “flow_activate”Activate a version of a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Makes version the active one of the flow in environment (“prod” default | “testing”). Transactional: if the version does not exist it fails without touching anything. Instant rollback is activating the previous version (it brings its frozen modules). With Module nodes, prod runs with the modules frozen at publish and testing with the latest; mode only accepts “floating” and only in testing. A module has no environments, so it is not activated in testing. Activating a module returns callerWarnings (who uses it frozen in prod, which drafts become outdated); a caller floating in testing that breaks blocks the activation.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
version |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
environment |
string | No | Default: "prod". |
mode |
string | No |
flow_add_node
Section titled “flow_add_node”Add a node to the draft · Changes data · can overwrite or remove · Listed to the agent from the start
Inserts a new node in the draft; only the node is sent. ui = {x, y} canvas position; if omitted the server places it. To wire it, another node must reference it (flow_patch_node on the node that points here). Fails if node_id already exists. Give it a label (in an END, config.label) or the builder shows the id and adds a warning. An agent node without them gets stayInAgent: true, loopMaxIterations: 20 and agentCapabilities.endCall on; with no required data loopExitLogic: "AND" (talks until it calls end_call, so onDone/next is never followed), with required data “OR” (moves on through onDone). A classifier (role: classifier) gets no defaults.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
node |
object | Yes | |
node_id |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
ui |
object | No |
flow_create_module
Section titled “flow_create_module”Create a module · Changes data · can overwrite or remove · Listed to the agent from the start
Creates a new shared Module (type “module”, fixed forever): a flow that other flows call with a Module node, with inputs and outputs. It starts with a listo END and the listo exit declared, with no data inputs or outputs. A flow that calls it is published normally: on publish the module version it uses is frozen. Then build it with flow_add_node and flow_patch_node, and declare its inputs and outputs with flow_patch_meta(updates={"settings": {"interface": {...}}}). The flowId is always generated by the tool: an existing flow cannot be converted into a module. Use modules only if 2 or more flows share the logic.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_name |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_create_voice
Section titled “flow_create_voice”Create a voice flow · Changes data · can overwrite or remove · Listed to the agent from the start
Creates a new voice flow (type “voice”, fixed forever): it handles calls and voice sessions instead of text chat. It starts with a single END and with the company’s default voice and STT (voice_library_list -> default) in settings.voiceConfig, with enabled: true; if the company has no default voice, it starts only with enabled: true. Then build it with flow_add_node and flow_patch_node; change the voice with flow_voice_set. The flowId is always generated by the tool; the type cannot be changed later nor an existing flow converted.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_name |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_delete
Section titled “flow_delete”Delete a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Deletes the whole flow with all its versions. Destructive action. For safety the agent does not run this action: the tool returns a link to the Dakso admin screen where a person confirms it. Give the user that link.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_delete_version
Section titled “flow_delete_version”Delete a version of a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Deletes one version of the flow (the active version cannot be deleted). Destructive action. For safety the agent does not run this action: the tool returns a link to the Dakso admin screen where a person confirms it. Give the user that link.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
version |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_diff
Section titled “flow_diff”Compare two versions of a flow · Read only · Listed to the agent from the start
Compares two versions of a flow and returns only what changes, per node and per field (systemPrompt as a line diff). a and b accept “draft”, “active” or a version number (for example “89”). With neither, it compares the active version against the draft, that is, what changes compared to what is live. Moving nodes on the canvas does not count; identical: true means same content. Show the summary to the user before publishing or promoting.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
a |
string | No | Default: "active". |
b |
string | No | Default: "draft". |
flow_export
Section titled “flow_export”Export a flow · Read only · Listed to the agent from the start
Exports a flow as portable JSON. source = “active” | “draft”. The result is what flow_import takes to create a flow.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
source |
string | No | Default: "active". |
flow_extract_task
Section titled “flow_extract_task”Extract a block of the draft into a task · Changes data · can overwrite or remove · Listed to the agent from the start
Turns an existing block of the draft (node_ids) into a reusable task without changing what the flow does: its entry becomes the start, each outside destination a task end and everything entering the block goes through a new call node. Without apply it returns a preview and writes nothing; with apply=True and the preview’s planHash in plan_hash it applies. The preview has entry, incoming, exits (each with its exitName), call (the new node), closes (what inside closes the conversation) and blockers, plus planHash. With blockers, apply writes nothing. If the draft changed since the preview, apply refuses.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
name |
string | Yes | |
node_ids |
array of string | Yes | |
apply |
boolean | No | Default: false. |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
plan_hash |
string | No | Default: "". |
flow_get_active
Section titled “flow_get_active”Get the active version of a flow · Read only · Listed to the agent from the start
Returns a flow’s active pointer in an environment (environment: “prod” by default, or “testing”): activeVersion, environment, activatedBy and updatedAt. It does not include the version content; use flow_get_version for that.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
environment |
string | No | Default: "prod". |
flow_get_draft
Section titled “flow_get_draft”Get the draft of a flow · Read only · Listed to the agent from the start
Returns the full draft (the version being edited) of a flow. It can be large: to see which nodes exist use flow_list_nodes, and to read one node use flow_get_node.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes |
flow_get_node
Section titled “flow_get_node”Get one node of a flow · Read only · Listed to the agent from the start
Reads one full node with its real fields: untruncated systemPrompt, contextCapture, modelConfig, templateKey, etc. Also returns connections ({field: target}), referencedBy, isStart, ui, bytes and texts: the real reply text, resolved from i18n ({key: {language: text}}); keys declared without a translation come in missingTexts (a silent node). Reply text is edited in i18n with flow_patch_meta, not on the node. fields (optional) = top-level fields to fetch (for example [“systemPrompt”]); the rest is listed in omitted. source = “draft” (default) | “active” (with environment). Read the node before editing it with flow_patch_node.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
node_id |
string | Yes | |
environment |
string | No | Default: "prod". |
fields |
array | No | |
source |
string | No | Default: "draft". |
flow_get_version
Section titled “flow_get_version”Get a version of a flow · Read only · Listed to the agent from the start
Returns the full content of one published version of a flow, identified by version. For the version currently live use flow_get_active to find its number first.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
version |
string | Yes |
flow_import
Section titled “flow_import”Import a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Imports a flow from an export JSON (from flow_export). It is created as a new draft in the organization. flow_name is optional, to rename it on import. To copy content into an existing flow use flow_import_draft.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
export_data |
object | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_name |
string | No | Default: "". |
flow_import_draft
Section titled “flow_import_draft”Import content into the draft of an existing flow · Changes data · can overwrite or remove · Listed to the agent from the start
Copies the content of one flow into the draft of another: source_flow_id (its active version by default, or its draft with source="draft") goes into the draft of the existing flow flow_id. Unlike flow_import, it creates no new flow: the target keeps its flowId, flowName and history. It overwrites the target draft, so it requires confirm=True: without it, it only warns which flow would be overwritten and writes nothing. If the target has an unpublished draft it stops (IMPORT_DRAFT_CONFLICT). The force=True variant does not replace confirm and a person confirms it in the admin: the agent does not run it, the tool returns a link to the admin screen.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
source_flow_id |
string | Yes | |
confirm |
boolean | No | Default: false. |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
force |
boolean | No | Default: false. |
source |
string | No | Default: "active". |
flow_lint
Section titled “flow_lint”Check a flow for errors · Read only · Listed to the agent from the start
Static check of a flow for errors, with rules born from real mistakes: dangling references (the engine rejects the whole flow), router default pointing to END (closes the conversation when nothing matches), ${var} with no producer (becomes empty text silently), inline agent without systemPrompt, promptSections present, and the flow weight against the 400 KB per item limit (warning from 60%, error from 80%; at 80% writes are blocked). Read-only. source = “draft” (default) | “active”. Run it before publishing and fix what it reports.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
source |
string | No | Default: "draft". |
flow_list_nodes
Section titled “flow_list_nodes”List the nodes of a flow · Read only · Listed to the agent from the start
Map of a flow: for each node its id, type, label, the nodes it goes to (to) and its weight (bytes), without the content (prompts, captures, texts). It is the light way to get oriented in a large flow before reading a node with flow_get_node. source = “draft” (default) | “active” (with environment = “prod” | “testing”). Optional filters: node_type (for example “agent”) and query (text in the id or label). Also returns startAt, nodeCount, byType, heaviest (the 5 heaviest) and totalBytes.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
environment |
string | No | Default: "prod". |
node_type |
string | No | |
query |
string | No | |
source |
string | No | Default: "draft". |
flow_list_versions
Section titled “flow_list_versions”List versions of a flow · Read only · Listed to the agent from the start
Lists the published versions of a flow. Use a version number from this list with flow_get_version, flow_activate or flow_diff.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes |
flow_module_dependents
Section titled “flow_module_dependents”See which flows use a module · Read only · Listed to the agent from the start
“Used by” of a shared Module: which flows call it and, per environment, which module version they run (frozen at publish in prod, the latest in testing, or pinned on the node). outdated = a newer version exists than the frozen one; bring it up with flow_refreeze_modules. Returns the module activeVersion and callers[] with flowId, flowName, draft (its draft uses it) and environments.{prod,testing} = {version, moduleVersion, mode: frozen|floating|pinned, pendingVersion?}. pendingVersion = the update is already published at that version and only needs activating: do not update again. Read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes |
flow_patch_meta
Section titled “flow_patch_meta”Edit the general data of a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Edits top-level fields of the flow merging only the difference: settings, i18n, defaultLLMConfig, startAt, followUpResponse, flowName, etc. It does not edit steps (that goes through flow_patch_node, flow_add_node and flow_remove_node). Example: add the text of a new answer node with updates={“i18n”: {“es”: {“node_text_answer_X”: “…”}}}.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
updates |
object | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_patch_node
Section titled “flow_patch_node”Edit one node of the draft · Changes data · can overwrite or remove · Listed to the agent from the start
Edits one node of the draft without resending the whole flow. The server reads the draft, deep-merges updates into node node_id (and optionally deletes the keys in remove_keys) and saves; only the difference is sent. The merge is deep but lists are REPLACED whole: send the full list, not only the new item. If another editor saved in between, the change is re-applied on the new state without overwriting their work.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
node_id |
string | Yes | |
updates |
object | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
remove_keys |
array | No |
flow_preflight
Section titled “flow_preflight”Pre-publish check of a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Pre-publish check in one deterministic pass: (1) diff of the draft against the active version, (2) static check of the draft, (3) run of the testScenarios saved in the draft (publishing strips them: they live only there) against a preview of the flow. ready=true means 0 check errors and 0 failed scenarios; it is data to decide with, not a gate. Running the scenarios creates test sessions but does not change the flow.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes |
flow_promote
Section titled “flow_promote”Promote a flow between environments · Changes data · can overwrite or remove · Listed to the agent from the start
Promotes a flow between environments: the pointer of to_env is set to the same active version as from_env; nothing is copied. Needs publish permission. Call it first without confirm to see the diff: it is a simulation that returns diff (active in target -> version to promote), lint, from/to and pointerUpdatedAt, and writes nothing. With confirm=True and pointer_updated_at = the simulation’s pointerUpdatedAt it applies; if someone promoted in between it answers PROMOTE_CONFLICT, and it is blocked if validation has errors or the previous version cannot be read. Show the diff to the user first. Rollback: flow_activate(versionBefore, environment=to_env).
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
confirm |
boolean | No | Default: false. |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
from_env |
string | No | Default: "testing". |
pointer_updated_at |
string | No | |
to_env |
string | No | Default: "prod". |
flow_publish
Section titled “flow_publish”Publish a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Publishes the draft as a new version. With activate=True it also activates it in environment: “prod” (default) goes live in production immediately; “testing” only for test channels (promote later with flow_promote). The static check cannot be skipped: errors (dangling references) stop the publish and are fixed in the draft with flow_patch_node; warnings never block and come back as lintWarnings. With Module nodes, each module is frozen at the version active at publish time (frozenModules); a broken module contract does not pass. To bring a newer module version to prod use flow_refreeze_modules and then flow_activate. Run flow_lint and flow_run_scenario first.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
activate |
boolean | No | Default: false. |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
environment |
string | No | Default: "prod". |
force |
boolean | No | Default: false. |
notes |
string | No | Default: "". |
flow_refreeze_modules
Section titled “flow_refreeze_modules”Update the modules of a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Updates to the new module version: publishes a new version of a flow that calls modules, with the same content as its active version in environment and the modules frozen again at their active version (or only module_id). It does not touch the draft nor activate. Without apply it returns a preview (changes, contract lint, planHash); with apply=True and plan_hash it publishes. If the contract breaks, or something changed since the preview, apply does not publish. With pendingVersion in the preview, that update is already published and only needs activating (flow_activate, a separate step). Applying needs publish permission.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
apply |
boolean | No | Default: false. |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
environment |
string | No | Default: "prod". |
module_id |
string | No | |
plan_hash |
string | No | Default: "". |
flow_remove_node
Section titled “flow_remove_node”Remove a node from the draft · Changes data · can overwrite or remove · Listed to the agent from the start
Deletes a node from the draft. Fails if it does not exist. It does not rewire references: fix the nodes that pointed to it with flow_patch_node.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
node_id |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_rollback
Section titled “flow_rollback”Restore a previous version as the draft · Changes data · can overwrite or remove · Listed to the agent from the start
Restores version as the new draft of the flow; it does not touch the active version. The current draft is replaced. To make the old version live, publish the draft or activate the version with flow_activate.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
version |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_run_scenario
Section titled “flow_run_scenario”Test a flow with a test conversation · Changes data · can overwrite or remove · Listed to the agent from the start
Runs a flow as a test conversation and returns the turn-by-turn transcript plus serious execution errors. messages is the script of user messages (one per turn, at most 20 messages of up to 2000 characters each); source = “draft” (default) | “active”; with source="active", environment = “prod” (default) | “testing” picks the version. It creates a test session but does not modify the flow. Use it to test a draft before publishing and judge whether replies are right. If a turn hands off to a human agent, it includes agentContextPreview (the ctx.* the agent screen pop would receive) and screenPopIdPreview.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
messages |
array of string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
environment |
string | No | Default: "prod". |
source |
string | No | Default: "draft". |
flow_save_draft
Section titled “flow_save_draft”Save the draft of a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Saves the complete flow as a draft. Use it only to create a new flow: it does not overwrite an existing draft that already has several nodes, tasks or UI (the save is rejected if the incoming flow collapses steps compared with the current draft, or if the current draft cannot be verified). To edit, add or remove nodes of an existing flow use flow_patch_node, flow_add_node and flow_remove_node, which do not regenerate the whole flow.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow |
object | Yes | |
flow_id |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_search
Section titled “flow_search”Search text inside a flow · Read only · Listed to the agent from the start
Searches a text inside a flow and says which node holds it: where a word is mentioned, which nodes use a tool, who says a given text. It checks every field of each node (prompts, captures, tools, conditions) and also the reply text, which lives in i18n; case and accent insensitive. Returns results[] {nodeId, type, label, field, snippet} (fragments, never the whole prompt), plus matched and truncated. It does not return the whole flow; open the node afterwards with flow_get_node. source = “draft” (default) | “active” (with environment).
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
query |
string | Yes | |
environment |
string | No | Default: "prod". |
limit |
integer | No | Default: 20. |
source |
string | No | Default: "draft". |
flow_task_delete
Section titled “flow_task_delete”Delete a task of a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Deletes a reusable task and its nodes from the draft, like “Delete” in the builder. Destructive because it deletes nodes. It deletes nothing if someone calls the task, an outside node points inside, another task starts at one of its nodes or a module gate enters through it: the error lists what to resolve first. For safety the agent does not run this action: the tool returns a link to the Dakso admin screen where a person confirms it. Give the user that link.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
task_id |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
flow_task_list
Section titled “flow_task_list”List the tasks of a flow · Read only · Listed to the agent from the start
Reusable tasks and module calls of a flow: for each task its start, its exits (the task ends), its nodes and who calls it; for each Module node, the module exits its on does not cover. If the flow is a shared module it returns kind and interface. source = “draft” (default) | “active” (with environment). Read it before creating, changing or deleting a task. Use tasks only if the block is called from 2 or more places in the same flow.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
environment |
string | No | Default: "prod". |
source |
string | No | Default: "draft". |
flow_task_save
Section titled “flow_task_save”Save a task of a flow · Changes data · can overwrite or remove · Listed to the agent from the start
Creates or edits a reusable task of the draft (settings.tasks). Without task_id it creates it with name (the id is derived from the name) and, if start is given, its start node; with task_id it renames it (name) and/or changes its start (start, an existing node). Use tasks only if the block is called from 2 or more places in the same flow.
| Argument | Type | Required | Description |
|---|---|---|---|
client_id |
string | Yes | |
flow_id |
string | Yes | |
descripcion |
string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
name |
string | No | Default: "". |
start |
string | No | Default: "". |
task_id |
string | No | Default: "". |
flows_list
Section titled “flows_list”List flows · Read only · Listed to the agent from the start
Lists the organization’s flows, active and inactive. Each flow has its clientId and flowId (other tools ask for both) and environments: the version active in production (prod) and in testing (testing; with no testing environment, only prod).
No arguments.