Workflows

A workflow is an automation you build in the workflow builder of your panel. It starts with one trigger (an inbound message, a delivery report, a schedule or a birthday), can branch on conditions and performs actions: send an SMS or WhatsApp message, call a webhook, edit the contact, opt out, wait, assign the conversation to a team member. The /v1/flows endpoints work on the same workflows as the panel: a workflow created through the API shows up in the builder and the other way round.

The reference is split over a few pages: Definition (the workflow, node and edge objects), Triggers, Conditions and Actions (the settings of every node type), Executions (what a run reports) and Examples. The endpoints follow after that.

How a workflow is built

A definition is a small graph: a list of nodes and a list of edges that connect them. Every node has a type and a data.config object; the first key of that object says what the node does.

The smallest useful workflow: opt the sender out when an inbound message contains STOP.

{
	"name": "STOP = opt out",
	"nodes": [
		{ "id": "trigger", "type": "triggerNode",
		  "data": { "config": { "triggerType": "inbound_message", "inboxId": 0 } } },
		{ "id": "is_stop", "type": "conditionNode",
		  "data": { "title": "Says STOP?", "config": { "conditionType": "if", "field": "message.body", "operator": "contains", "value": "STOP" } } },
		{ "id": "opt_out", "type": "actionNode",
		  "data": { "title": "Opt out", "config": { "actionType": "opt_out", "editMethod": "opt_out" } } }
	],
	"edges": [
		{ "id": "e1", "source": "trigger", "sourceHandle": "out", "target": "is_stop" },
		{ "id": "e2", "source": "is_stop", "sourceHandle": "true", "target": "opt_out" }
	]
}

When the trigger fires, the engine builds a payload (the message, the contact, ...) and walks the graph from the trigger node: a condition evaluates the payload and the engine follows every edge that leaves the matching handle; an action runs and the engine follows its out edges. Actions such as get_contact add data to the payload for the nodes that follow, and text fields can use {{ placeholders }} from the payload (see Triggers).

Draft and published versions

A workflow has a status: draft (never published), active (published and running on its trigger) or inactive (unpublished). Every change is kept as a version:

Get workflow, Test workflow and Run workflow use the builder version: the draft when there is one, otherwise the published version. The trigger itself only ever runs the published version. Every workflow response tells you which version you are looking at with version_number and version_status (draft, published or archived), next to published_version_number, draft_version_number, has_draft_changes and published_at.

Permissions

Workflow automations have to be enabled on your account; otherwise every endpoint returns http status 403 with error 166. Team users need API access and the Allow workflows permission (403 / error 1403 otherwise); Run workflow additionally needs the permission to send messages, because a run really executes the actions.

Errors