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

messageThreadId

UUID

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.

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

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

OpenAPI

PreviousFlow NextFlowGeneration

Last updated 16 days ago

FlowRun

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 to be triggered.

messageThreadId

UUID

Id of the to trigger the flow on.

state

JSON object

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

initialMessage

JSON object

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 can be any of the available , see the 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 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:
              // "scheduleIds: ["<my-schedule-id>", "<your-schedule-id>"]
            }
        }
    }
}

OpenAPI

PreviousFlow NextFlowGeneration

Last updated 16 days ago

{ "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" } } } } ] }

{ "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" } } } } ] }

{ "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 } }

FlowRun

Endpoints

Patching a FlowRun

Attributes

HTTP Methods

Required Fields for Creation (POST)

Initial Message

Example POST body

Example PATCH body

Scheduling

OpenAPI

FlowRun

Endpoints

Patching a FlowRun

Attributes

HTTP Methods

Required Fields for Creation (POST)

Initial Message

Example POST body

Example PATCH body

Scheduling

OpenAPI

Destroy a Candidate

Retrieve a single flow_run

Destroy a FlowRun

Retrieve a single flow_run including flow

Retrieve a single flow_run including messageThread

Retrieve all FlowRuns

Create a FlowRun

Update a FlowRun