Workflow definition
The objects you send to Create workflow and Update workflow and get back from Get workflow. What goes into data.config is described on the Triggers, Conditions and Actions pages.
The workflow object
| Key | Values | Description |
|---|---|---|
name | string, 1 to 255 characters | Shown in the panel. |
nodes | list of 1 to 200 nodes | See below. A draft can have zero or one trigger node. |
edges | list of 0 to 400 edges | See below. Always sent together with nodes. |
viewport | optional { x, y, zoom } | Position of the builder canvas. |
meta | optional object | Free-form data, stored as is. |
An account can have at most 100 workflows (error 168). An invalid definition returns http status 400 with error 164 and an error_info list with every problem as { path, message }, e.g. nodes.2.data.config.operator. Keys that are not documented are rejected with their path, so a typo in a config key is caught before the workflow runs.
Nodes
{
"id": "reply",
"type": "actionNode",
"position": { "x": 640, "y": 120 },
"data": {
"title": "Auto-reply",
"config": { "actionType": "send_sms", "messageType": "reply_message", "message": "Thanks {{ contact.firstname }}, we will get back to you." }
}
}
| Key | Values | Description |
|---|---|---|
id | string, 1 to 64 characters | Unique within the workflow; edges refer to it. |
type | triggerNode / conditionNode / actionNode | What kind of node this is. |
data.config | object, required | The settings of the node: Triggers, Conditions, Actions. |
data.title | optional string, max. 255 | Label shown in the builder and in execution results. |
data.subtitle | optional string, max. 255 | Second line in the builder. |
position | optional { x, y } | Where the builder draws the node. |
width, height | optional numbers | Builder layout. |
selected, dragging and positionAbsolute (builder state) are accepted and stripped.
Edges
{ "id": "e2", "source": "is_stop", "sourceHandle": "true", "target": "opt_out", "targetHandle": "in" }
{ "id": "e2", "source": "is_stop", "sourceHandle": "true", "target": "opt_out", "targetHandle": "in" }
| Key | Values | Description |
|---|---|---|
id | string | Unique within the workflow. |
source | node id | The node the edge leaves. |
sourceHandle | out / true / false / fallback | Which output of the source node: out for trigger and action nodes (default), true or false for condition nodes, fallback for send_whatsapp_message. |
target | node id | The node the edge enters. A trigger node can never be a target. |
targetHandle | absent or in | Nodes have one input. |
type | optional string | Edge style in the builder. |
Other builder keys (animated, label, style, markerEnd, ...) are accepted and stripped. Several edges may leave the same handle (every branch runs) and a node may have several incoming edges.
IDs inside a definition
Like everywhere in the API, objects are referenced by their public ID; numeric IDs are accepted on input and every ID is checked against your account. A forged ID or one of the wrong type (e.g. a sub_ ID where a group is expected) is reported as a definition error (164) at its path.
| Object | Public ID | Where it appears |
|---|---|---|
| Workflow | flw_... | {flow_id} in the URL, id in responses. uuid is the ID the panel uses in the URL of the builder. |
| Contact group | gid_... | groupid / groupId in action and trigger configs and the value of a contact.group_id condition. Always gid_... in responses. |
| Team member | sub_... | teamMember / teamMembers of assign_conversation. Always sub_... in responses (see List subaccounts). |
| Inbox / virtual number | numeric (0 = every inbox) | inboxId of the inbound_message trigger. A num_... ID is accepted in the value of a message.inbox_id condition; responses stay numeric. |
| Contact | con_... | contact_id of Run workflow and Get sample payload. |
| Execution | uuid | {execution_id} in the URL, id / execution in responses. |
Publish rules
A draft only has to be well-formed. To be published a workflow additionally needs:
| Rule | Error |
|---|---|
Exactly one trigger node with a triggerType | 165, error_info names the problem |
| Every node reachable from the trigger | 165, error_info lists the unreachable node IDs |
A cron trigger in seconds mode has an interval of at least 10 | 165 |
