FlowRun

FlowRun is responsible for initiating a Flow in a MessageThread. The FlowRun resource reflects the flow's current state of the flow, including session variables, the present costs incurred in association with the FlowRun and the status attribute displaying the flow's execution state.

Endpoints

GET /flow-runs - Retrieve a list of all FlowRun.
GET /flow-runs/{id} - Retrieve a specific FlowRun by ID.
POST /flow-runs - Trigger a new FlowRun in a MessageThread.
PATCH /flow-runs/{id} - Update a specific FlowRun by ID.
DELETE /flow-runs/{id} - Delete a specific FlowRun by ID.

Patching a FlowRun

The following attributes can be patched in a FlowRun:

state - The state attribute can can only be updated once a FlowRun is not in a running state. By patching the state attribute you can delete any personal data or other sensitive information from the state.
status - The status attribute can be updated to finished, timeout, cancelled or exception. This can be used to manually finish a flow run or to mark it as a timeout or exception.

Attributes

Field

Type

Description

flowId

UUID

Id of the Flow to be triggered.

messageThreadId

UUID

Id of the MessageThread to trigger the flow on.

state

JSON object

The initial state of the flow run, including session variables.

initialMessage

JSON object

The message to be sent to the candidate when the flow is triggered. Type depends on the channel; for WhatsApp, a template is required. If no message is provided, the flow will be triggered without sending a message to the candidate; this will still mean that the candidate will enter the correct flow upon the next message send. Please set to {} if you wish for no initialMessage.

status

String

The current status of the flow run, which can be one of "running", "finished", "timeout", "exception", "queued".

cost

integer

The current cost in credits of the flow run.

createdAt

DateTime

The timestamp when the flow run was created.

updatedAt

DateTime

The timestamp when the flow run was last updated.

HTTP Methods

Field

GET

POST

PATCH

flowId

messageThreadId

state

initialMessage

status

cost

createdAt

updatedAt

Required Fields for Creation (POST)

Field

Type

Example value

flowId

UUID

cacc1a00-b59f-44da-8a48-d99db3473389

messageThreadId

UUID

cacc1a00-b59f-44da-8a48-d99db3473389

state

JSON object

{}

initialMessage

JSON object

{"type":"template","template":{"id":"7f9a9715-5e7c-4328-ab47-bb9e595438c9","components":[{"type":"body","parameters":[{"type":"text","text":"John"}]}]}}

Initial Message

The initial message is the message that will be sent to the candidate when the flow is triggered. The type of the initial message depends on the channel, for whatsapp a template is required. If no message is provided, the flow will be triggered without sending a message to the candidate this will still mean that the candidate will enter the correct flow upon sending a message.

The initial message can be any of the available Payload values, see the Message resource for more information.

Example POST body

{
    "data": {
        "type": "flowRuns",
        "attributes": {
            "flowId": "eb4c92e9-2548-4e4c-95d5-adfb94270c3f",
            "messageThreadId": "7135853f-26ac-4a65-9044-cab092806249",
            "state": {},
            "initialMessage": {
                "type": "template",
                "template": {
                    "id": "7f9a9715-5e7c-4328-ab47-bb9e595438c9",
                    "components": [
                        {
                            "type": "body",
                            "parameters": [
                                {
                                    "type": "text",
                                    "text": "John"
                                }
                            ]
                        }
                    ]
                }
            }
        }
    }
}

Example PATCH body

{
    "data": {
        "type": "flowRuns",
        "id": "7135853f-26ac-4a65-9044-cab092806249",
        "attributes": {
            "status": "finished"
        }
    }
}

Scheduling

If you have generated a flow with a scheduling step where the mode is set to mode: 'custom' you can provide the Schedule Id when starting the flow by including the following:

{
    "data": {
        "type": "flowRuns",
        "id": "7135853f-26ac-4a65-9044-cab092806249",
        "attributes": {
            "status": "finished",
            "state": {
              "scheduleId": "<my-schedule-id>"
              // Optionally you can add multiple schedule ids aswel:
              // "scheduleId: ["<my-schedule-id>", "<your-schedule-id>"]
            }
        }
    }
}

OpenAPI

Create a FlowRun

post

Authorizations

AuthorizationstringRequired

Bearer

Body

Responses

201

flow_run created

application/vnd.api+json

401

access denied

422

when trying to write a non-writable attribute

post

/flow-runs

POST /public/v2/flow-runs HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 272

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "flowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "messageThreadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "state": "{ \"variable\": \"value\" }",
      "initialMessage": {},
      "context": {},
      "status": "running",
      "publicApiInitiated": true
    }
  }
}

{
  "data": {
    "id": "98e5af31-5fbb-4166-b792-9b8764b835b1",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:05+00:00",
      "updatedAt": "2024-08-20T10:45:05+00:00",
      "flowId": "6d6e3b3d-e0b0-4b9d-b42b-ff0b58746cee",
      "messageThreadId": "06bd4b24-7a67-4c09-a5af-0e88c569ab6f",
      "state": {},
      "initialMessage": {},
      "status": "finished",
      "cost": 0
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/6d6e3b3d-e0b0-4b9d-b42b-ff0b58746cee"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/06bd4b24-7a67-4c09-a5af-0e88c569ab6f"
        }
      }
    }
  },
  "meta": {}
}

Destroy a Candidate

delete

Authorizations

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

204

candidate destroyed

401

access denied

404

Candidate not found

delete

/candidates/{id}

DELETE /public/v2/candidates/{id} HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

No content

Retrieve a single flow_run

get

Authorizations

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

200

flow_run found

application/vnd.api+json

401

access denied

404

FlowRun not found

get

/flow-runs/{id}

GET /public/v2/flow-runs/{id} HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": {
    "id": "7460b017-59e7-439a-a1a0-b9e95b301b1c",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:03+00:00",
      "updatedAt": "2024-08-20T10:45:03+00:00",
      "flowId": "25cbfffb-0105-41fe-afdc-454c4aa1bc4b",
      "messageThreadId": "92137559-ea63-4beb-91cf-bf6d477dbf14",
      "state": {},
      "initialMessage": {},
      "status": "finished",
      "cost": 29
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/25cbfffb-0105-41fe-afdc-454c4aa1bc4b"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/92137559-ea63-4beb-91cf-bf6d477dbf14"
        }
      }
    }
  },
  "meta": {}
}

Destroy a FlowRun

delete

Authorizations

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

204

flow_run destroyed

401

access denied

404

FlowRun not found

delete

/flow-runs/{id}

DELETE /public/v2/flow-runs/{id} HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

No content

Update a FlowRun

patch

Authorizations

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Body

Responses

200

flow_run updated

application/vnd.api+json

401

access denied

404

FlowRun not found

422

Invalid Request opening message can not be updated

patch

/flow-runs/{id}

PATCH /public/v2/flow-runs/{id} HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 272

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "flowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "messageThreadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "state": "{ \"variable\": \"value\" }",
      "initialMessage": {},
      "context": {},
      "status": "running",
      "publicApiInitiated": true
    }
  }
}

{
  "data": {
    "id": "9b438057-cd8c-4de7-a966-0345ec1414e5",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:04+00:00",
      "updatedAt": "2024-08-20T10:45:04+00:00",
      "flowId": "d972cc73-1487-4ac0-99e7-b5f592d9d94f",
      "messageThreadId": "725791eb-9f29-4211-98d0-c1ca4db35723",
      "state": {
        "first_name": "Henk"
      },
      "initialMessage": {},
      "status": "finished",
      "cost": 30
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/d972cc73-1487-4ac0-99e7-b5f592d9d94f"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/725791eb-9f29-4211-98d0-c1ca4db35723"
        }
      }
    }
  },
  "meta": {}
}

Retrieve a single flow_run including flow

get

Authorizations

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

200

flow_run found with included flow

application/vnd.api+json

get

/flow_runs/{id}?include=flow

GET /public/v2/flow_runs/{id}?include=flow HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

200

flow_run found with included flow

{
  "data": {
    "id": "a9a37c94-173b-4f6d-b9bf-7983a7ef9322",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:02+00:00",
      "updatedAt": "2024-08-20T10:45:02+00:00",
      "flowId": "7f873317-66a6-4312-bc77-3a1056726687",
      "messageThreadId": "37bb741c-e4ac-42b3-aaba-01415126ef9c",
      "state": {},
      "initialMessage": {},
      "status": "finished",
      "cost": 55
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/7f873317-66a6-4312-bc77-3a1056726687"
        },
        "data": {
          "type": "flows",
          "id": "7f873317-66a6-4312-bc77-3a1056726687"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/37bb741c-e4ac-42b3-aaba-01415126ef9c"
        }
      }
    }
  },
  "meta": {},
  "included": [
    {
      "id": "7f873317-66a6-4312-bc77-3a1056726687",
      "type": "flows",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "name": "aperiam",
        "reminderInterval": 15,
        "reminderMessage": "Are you still there? There are still a few questions left to finish your application.",
        "sessionTimeout": 1440,
        "publishedAt": null,
        "unpublishedChanges": true,
        "flowGenerationId": null
      },
      "relationships": {
        "flowGeneration": {
          "links": {
            "related": "/public/v2/flow-generations?filter[flowId]=7f873317-66a6-4312-bc77-3a1056726687"
          }
        },
        "nodes": {
          "links": {
            "related": "/public/v2/nodes?filter[flowId]=7f873317-66a6-4312-bc77-3a1056726687"
          }
        }
      }
    }
  ]
}

Retrieve a single flow_run including messageThread

get

Authorizations

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

200

flow_run found with included messageThread

application/vnd.api+json

get

/flow_runs/{id}?include=messageThread

GET /public/v2/flow_runs/{id}?include=messageThread HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

200

flow_run found with included messageThread

{
  "data": {
    "id": "aee1a798-34b9-482e-bddf-d1c58ef7e438",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:02+00:00",
      "updatedAt": "2024-08-20T10:45:02+00:00",
      "flowId": "9b5007f1-38fe-4e14-a235-a3a075a46c39",
      "messageThreadId": "e811c955-a9be-4730-8ad7-1153416fc0e0",
      "state": {},
      "initialMessage": {},
      "status": "finished",
      "cost": 38
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/9b5007f1-38fe-4e14-a235-a3a075a46c39"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/e811c955-a9be-4730-8ad7-1153416fc0e0"
        },
        "data": {
          "type": "messageThreads",
          "id": "e811c955-a9be-4730-8ad7-1153416fc0e0"
        }
      }
    }
  },
  "meta": {},
  "included": [
    {
      "id": "e811c955-a9be-4730-8ad7-1153416fc0e0",
      "type": "messageThreads",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "channel": "whatsapp",
        "identifier": "31652071191",
        "candidateId": null
      },
      "relationships": {
        "candidate": {
          "links": {
            "related": null
          }
        },
        "flowRuns": {
          "links": {
            "related": "/public/v2/flow-runs?filter[messageThreadId]=e811c955-a9be-4730-8ad7-1153416fc0e0"
          }
        },
        "messages": {
          "links": {
            "related": "/public/v2/messages?filter[messageThreadId]=e811c955-a9be-4730-8ad7-1153416fc0e0"
          }
        },
        "conversation": {
          "links": {
            "related": "/public/v2/conversations?filter[messageThreadId]=e811c955-a9be-4730-8ad7-1153416fc0e0"
          }
        }
      }
    }
  ]
}

Retrieve all FlowRuns

get

Authorizations

AuthorizationstringRequired

Bearer

Responses

200

flow_runs found

application/vnd.api+json

401

access denied

get

/flow-runs

GET /public/v2/flow-runs HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "11948e49-4480-4cf7-85dd-92fcba2ea8d8",
      "type": "flowRuns",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "flowId": "ca3a046a-d71d-45af-b62d-93f272372157",
        "messageThreadId": "64c98b9d-fe20-4e67-a518-391b1ef20a07",
        "state": {},
        "initialMessage": {},
        "status": "finished",
        "cost": 36
      },
      "relationships": {
        "flow": {
          "links": {
            "related": "/public/v2/flows/ca3a046a-d71d-45af-b62d-93f272372157"
          }
        },
        "messageThread": {
          "links": {
            "related": "/public/v2/message-threads/64c98b9d-fe20-4e67-a518-391b1ef20a07"
          }
        }
      }
    },
    {
      "id": "b9d9425a-ff3d-4f7a-8119-3775a7ddf0f1",
      "type": "flowRuns",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "flowId": "2cf095b7-f93c-44dc-ae56-5325c2de5f6e",
        "messageThreadId": "587b954c-599f-4001-a26d-17f33fa3596b",
        "state": {},
        "initialMessage": {},
        "status": "finished",
        "cost": 15
      },
      "relationships": {
        "flow": {
          "links": {
            "related": "/public/v2/flows/2cf095b7-f93c-44dc-ae56-5325c2de5f6e"
          }
        },
        "messageThread": {
          "links": {
            "related": "/public/v2/message-threads/587b954c-599f-4001-a26d-17f33fa3596b"
          }
        }
      }
    },
    {
      "id": "1c59170d-e8e0-4c17-835b-a7ad3d2b7e7c",
      "type": "flowRuns",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "flowId": "99e55620-aa7b-4737-8cd3-943a606f8505",
        "messageThreadId": "7f09643d-0068-4f30-853b-0e70ca3f973a",
        "state": {},
        "initialMessage": {},
        "status": "finished",
        "cost": 53
      },
      "relationships": {
        "flow": {
          "links": {
            "related": "/public/v2/flows/99e55620-aa7b-4737-8cd3-943a606f8505"
          }
        },
        "messageThread": {
          "links": {
            "related": "/public/v2/message-threads/7f09643d-0068-4f30-853b-0e70ca3f973a"
          }
        }
      }
    }
  ],
  "meta": {
    "total": 3,
    "totalUnfiltered": 3,
    "currentSize": 25,
    "currentPage": 1,
    "maxPage": 1
  }
}

PreviousFlow NextFlowGeneration

Last updated 5 months ago