Create a workflow · Workflows API · Kustomer Developers

Admins build workflows without code in Settings › Platform › Workflows, and apps can install their own. Use them to tag and route conversations, keep records in sync, call your own services when something changes, or handle data from inbound webhooks. Underneath the builder, each workflow is a JSON document, and this API reads and writes that document, so you can back workflows up, review changes in code, or copy them between a sandbox and production.

A workflow is created disabled unless you send enabled: true. Once it's enabled, every matching event starts a run; creating, enabling or changing a workflow takes about a minute to take effect. Runs execute in parallel, finish in any order, and stop after five minutes. There is no delete operation in this API: set enabled to false to stop a workflow.

The document

Part	What it holds
`trigger`	What starts a run: an `eventName` such as `kustomer.conversation.update`, or `callable: true` with an input `schema` for workflows that are called rather than triggered by an event. Its output is step `1`.
`steps`	The actions to run, each with an `id`, an `action` and `params`. A step's output is stored under its ID for later steps to reference as `/#steps.<id>`.
`transitions`	On the trigger and each step: where to go next, each guarded by a condition. The first match wins; if none match, the run ends normally.
`errorCases`	On a step: whether to continue or stop when it fails.

name is required and unique in the org: letters, numbers, -, _ and ., up to 128 characters. replaces names another workflow, usually one an app installed, that this one overrides; when both match an event, only this one runs. See Workflow JSON for every field and limit.

Read-only attributes

Responses also include lastError (the most recent failure, or {}), editable (whether the builder can edit it), containsVariables, and timestamps. Strip these before sending a document back, because unknown keys are rejected with 400.

Which endpoint to use

To	Call
List workflows, filtered by `enabled`, trigger `eventName` or `callable`	`GET /v1/workflows`
Read one workflow	`GET /v1/workflows/{id}`
Create a workflow	`POST /v1/workflows`
Change, enable or disable a workflow	`PUT /v1/workflows/{id}`
Store secrets the workflow uses	`POST /v1/workflows/{id}/variables`
See why runs failed	`GET /v1/workflows/{id}/processes`

PUT updates only the root keys you send, and each one replaces the stored value wholesale, so send trigger and steps together and keep step IDs stable because references depend on them. To switch a workflow on or off, send only enabled. Create new workflows disabled, add their variables, then enable them. Workflows reference org-specific IDs such as tags, teams, users and queues, so replace those before copying a workflow to another org. A workflow that updates the record that triggered it fires again, so guard update triggers with a condition on changes.

curl --request POST \ --url 'https://api.kustomerapp.com/v1/workflows' \ --header "Authorization: Bearer $KUSTOMER_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "name": "example_name", "replaces": "string", "description": "Example text", "meta": {}, "trigger": { "id": "65f2c0a1b4e3d2001234abcd", "callable": true, "schema": {}, "transitions": [ { "meta": {}, "target": "string", "condition": { "op": "and", "values": [ null ] } } ] }, "enabled": true }'

{ "data": { "type": "workflow", "id": "57504f6460da071c000dfaee", "attributes": { "name": "assign-user-on-message-send", "description": "Assign user to a conversation when the user sends a message and the conversation was previously unassigned.", "lastError": {}, "trigger": { "transitions": [ { "condition": { "values": [ { "values": [ "/#steps.1.createdBy" ], "op": "exists" }, { "values": [ "/#steps.1.status", "sent" ], "op": "eq" } ], "op": "and" }, "target": "2" } ], "eventName": "kustomer.message.create", "id": "1" }, "steps": [ { "id": "2", "action": "kustomer.conversation.find-by-id", "params": { "id": "/#steps.1.conversation" }, "_id": "57504f6460da071c000dfaf0", "errorCases": [], "transitions": [ { "target": "3", "condition": { "op": "lt", "values": [ "/#steps.2.assignedUsers.length", 1 ] } } ] }, { "id": "3", "action": "kustomer.conversation.update", "params": { "id": "/#steps.1.conversation", "assignedUsers": [ "/#steps.1.createdBy" ] }, "_id": "57504f6460da071c000dfaef", "errorCases": [], "transitions": [] } ], "enabled": true, "editable": true, "updatedAt": "2016-06-02T15:23:16.431Z", "createdAt": "2016-06-02T15:23:16.431Z", "containsVariables": false }, "relationships": { "org": { "links": { "self": "/v1/orgs/57504f64d76808100089eb44" }, "data": { "type": "org", "id": "57504f64d76808100089eb44" } }, "createdBy": null, "modifiedBy": null }, "links": { "self": "/v1/workflows/57504f6460da071c000dfaee" } } }

Workflows

The document

Read-only attributes

Which endpoint to use

Request body

Responses