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

X

X

messageThreadId

X

X

state

X

X

X

initialMessage

X

X

status

X

cost

X

createdAt

X

updatedAt

X

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
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
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
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
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
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
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
  }
}
PreviousFlowNextFlowGeneration

Last updated